https://en.doc.boardgamearena.com/api.php?action=feedcontributions&user=Tutchek&feedformat=atom
Board Game Arena - User contributions [en]
2024-03-19T03:39:11Z
User contributions
MediaWiki 1.39.0
https://en.doc.boardgamearena.com/index.php?title=Template:Studio_Framework_Navigation&diff=4052
Template:Studio Framework Navigation
2020-04-15T21:29:58Z
<p>Tutchek: Changed hedlines to bold centered text to avoid collision with TOCs</p>
<hr />
<div><br />
<div style="float: right; width: 300px; border: solid #000 1px; padding: 1em; margin-left: 1em; background: #fff;"><br />
<br />
<center>'''Studio Framework Navigation'''</center><br />
<br />
[[Studio file reference|File structure of a BGA game]]<br />
<br />
<center>'''Game logic (Server side)'''</center><br />
* [[Main game logic: yourgamename.game.php]]<br />
* [[Your game state machine: states.inc.php]]<br />
* [[Game database model: dbmodel.sql]]<br />
* [[Players actions: yourgamename.action.php]]<br />
* [[Game material description: material.inc.php]]<br />
* [[Game statistics: stats.inc.php]]<br />
<br />
<center>'''Game interface (Client side)'''</center><br />
* [[Game interface logic: yourgamename.js]]<br />
* [[Game art: img directory]]<br />
* [[Game interface stylesheet: yourgamename.css]]<br />
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl]]<br />
* [[Your game mobile version]]<br />
<br />
<center>'''Other components'''</center><br />
* [[Translations]] (how to make your game translatable)<br />
* [[Game options and preferences: gameoptions.inc.php]]<br />
* [[Game meta-information: gameinfos.inc.php]]<br />
* [[Game replay]]<br />
* [[3D]]<br />
* [[Some usual board game elements image ressources]]<br />
<br />
<center>'''BGA Studio game components reference'''</center><br />
* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).<br />
* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).<br />
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).<br />
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.<br />
* [[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).<br />
<br />
Undocumented component (if somebody knows please help with docs)<br />
* [[Draggable]]: a JS component to manage drag'n'drop actions.<br />
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.<br />
* [[Wrapper]]: a JS component to wrap a &lt;div&gt; element around its child, even if these elements are absolute positioned.<br />
<br />
<center>'''BGA Studio user guide'''</center><br />
* [[BGA game Lifecycle]]<br />
* [[First steps with BGA Studio]]<br />
* [[Tutorial reversi]] <br />
* [[Tutorial gomoku]] <br />
* [[Tutorial hearts]]<br />
* [[Create a game in BGA Studio: Complete Walkthrough]]<br />
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment<br />
* [[Practical debugging]] - Tips focused on debugging<br />
* [[Studio logs]] - Instructions for log access<br />
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks<br />
* [[BGA Studio Guidelines]]<br />
* [[Troubleshooting]] - Most common "I am really stuck" situations<br />
* [[Studio FAQ]]<br />
* [[Pre-release checklist]] - Go throught this list if you think you done development<br />
* [[Post-release phase]]<br />
* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links<br />
<br />
<br />
</div></div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Template:Studio_Framework_Navigation&diff=4051
Template:Studio Framework Navigation
2020-04-15T21:24:44Z
<p>Tutchek: </p>
<hr />
<div><br />
<div style="float: right; width: 300px; border: solid #000 1px; padding: 1em; margin-left: 1em; background: #fff;"><br />
<br />
=== Studio Framework Navigation ===<br />
<br />
This part of the documentation focuses on the development framework itself: functions and methods available to build your game.<br />
<br />
[[Studio file reference|File structure of a BGA game]]<br />
<br />
==== Game logic (Server side) ====<br />
<br />
* [[Main game logic: yourgamename.game.php]]<br />
* [[Your game state machine: states.inc.php]]<br />
* [[Game database model: dbmodel.sql]]<br />
* [[Players actions: yourgamename.action.php]]<br />
* [[Game material description: material.inc.php]]<br />
* [[Game statistics: stats.inc.php]]<br />
<br />
==== Game interface (Client side) ====<br />
<br />
* [[Game interface logic: yourgamename.js]]<br />
* [[Game art: img directory]]<br />
* [[Game interface stylesheet: yourgamename.css]]<br />
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl]]<br />
* [[Your game mobile version]]<br />
<br />
==== Other components ====<br />
<br />
* [[Translations]] (how to make your game translatable)<br />
* [[Game options and preferences: gameoptions.inc.php]]<br />
* [[Game meta-information: gameinfos.inc.php]]<br />
* [[Game replay]]<br />
* [[3D]]<br />
* [[Some usual board game elements image ressources]]<br />
<br />
=== BGA Studio game components reference ===<br />
<br />
Game components are useful tools you can use in your game adaptations.<br />
<br />
* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).<br />
* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).<br />
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).<br />
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.<br />
* [[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).<br />
<br />
Undocumented component (if somebody knows please help with docs)<br />
* [[Draggable]]: a JS component to manage drag'n'drop actions.<br />
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.<br />
* [[Wrapper]]: a JS component to wrap a &lt;div&gt; element around its child, even if these elements are absolute positioned.<br />
<br />
=== BGA Studio user guide ===<br />
<br />
This part of the documentation is a user guide for the BGA Studio online development environment.<br />
<br />
* [[BGA game Lifecycle]]<br />
* [[First steps with BGA Studio]]<br />
* [[Tutorial reversi]] <br />
* [[Tutorial gomoku]] <br />
* [[Tutorial hearts]]<br />
* [[Create a game in BGA Studio: Complete Walkthrough]]<br />
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment<br />
* [[Practical debugging]] - Tips focused on debugging<br />
* [[Studio logs]] - Instructions for log access<br />
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks<br />
* [[BGA Studio Guidelines]]<br />
* [[Troubleshooting]] - Most common "I am really stuck" situations<br />
* [[Studio FAQ]]<br />
* [[Pre-release checklist]] - Go throught this list if you think you done development<br />
* [[Post-release phase]]<br />
* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links<br />
<br />
<br />
</div></div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Template:Studio_Framework_Navigation&diff=4050
Template:Studio Framework Navigation
2020-04-15T21:24:20Z
<p>Tutchek: Dont include NOTOC</p>
<hr />
<div><noinclude>__NOTOC__</noinclude><br />
<br />
<div style="float: right; width: 300px; border: solid #000 1px; padding: 1em; margin-left: 1em; background: #fff;"><br />
<br />
=== Studio Framework Navigation ===<br />
<br />
This part of the documentation focuses on the development framework itself: functions and methods available to build your game.<br />
<br />
[[Studio file reference|File structure of a BGA game]]<br />
<br />
==== Game logic (Server side) ====<br />
<br />
* [[Main game logic: yourgamename.game.php]]<br />
* [[Your game state machine: states.inc.php]]<br />
* [[Game database model: dbmodel.sql]]<br />
* [[Players actions: yourgamename.action.php]]<br />
* [[Game material description: material.inc.php]]<br />
* [[Game statistics: stats.inc.php]]<br />
<br />
==== Game interface (Client side) ====<br />
<br />
* [[Game interface logic: yourgamename.js]]<br />
* [[Game art: img directory]]<br />
* [[Game interface stylesheet: yourgamename.css]]<br />
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl]]<br />
* [[Your game mobile version]]<br />
<br />
==== Other components ====<br />
<br />
* [[Translations]] (how to make your game translatable)<br />
* [[Game options and preferences: gameoptions.inc.php]]<br />
* [[Game meta-information: gameinfos.inc.php]]<br />
* [[Game replay]]<br />
* [[3D]]<br />
* [[Some usual board game elements image ressources]]<br />
<br />
=== BGA Studio game components reference ===<br />
<br />
Game components are useful tools you can use in your game adaptations.<br />
<br />
* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).<br />
* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).<br />
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).<br />
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.<br />
* [[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).<br />
<br />
Undocumented component (if somebody knows please help with docs)<br />
* [[Draggable]]: a JS component to manage drag'n'drop actions.<br />
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.<br />
* [[Wrapper]]: a JS component to wrap a &lt;div&gt; element around its child, even if these elements are absolute positioned.<br />
<br />
=== BGA Studio user guide ===<br />
<br />
This part of the documentation is a user guide for the BGA Studio online development environment.<br />
<br />
* [[BGA game Lifecycle]]<br />
* [[First steps with BGA Studio]]<br />
* [[Tutorial reversi]] <br />
* [[Tutorial gomoku]] <br />
* [[Tutorial hearts]]<br />
* [[Create a game in BGA Studio: Complete Walkthrough]]<br />
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment<br />
* [[Practical debugging]] - Tips focused on debugging<br />
* [[Studio logs]] - Instructions for log access<br />
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks<br />
* [[BGA Studio Guidelines]]<br />
* [[Troubleshooting]] - Most common "I am really stuck" situations<br />
* [[Studio FAQ]]<br />
* [[Pre-release checklist]] - Go throught this list if you think you done development<br />
* [[Post-release phase]]<br />
* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links<br />
<br />
<br />
</div></div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=BGA_Code_Sharing&diff=4049
BGA Code Sharing
2020-04-15T21:23:06Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This page is for listing of externally hosted bga projects, tools and resources, as well as internal project<br />
intended for sharing<br />
<br />
== Projects hosted not in studio ==<br />
<br />
See the table a link and nickname of the developer on bga (same as used for dev forum), and short description<br />
<br />
'''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.<br />
'''<br />
<br />
{| class="wikitable"<br />
|-<br />
! NON-GAME PROJECTS<br />
! CODE LINK<br />
! DEVELOPER<br />
|-<br />
| Shared Code (not a game)<br />
| https://github.com/elaskavaia/bga-sharedcode<br />
| Victoria_La<br />
|-<br />
| BoardGameArena Workbench (not a game)<br />
| https://github.com/danielholmes/bga-workbench<br />
| Daniel Holmes (dhau)<br />
|-<br />
! GAME<br />
! CODE LINK<br />
! DEVELOPER<br />
|-<br />
| Assyria <br />
| https://github.com/sebastien-prudhomme/bga-assyria<br />
| daikinee <br />
|-<br />
| The Battle for Hill 218<br />
| https://github.com/danielholmes/battle-for-hill-218<br />
| Daniel Holmes (dhau)<br />
|-<br />
| Bonbons<br />
| https://github.com/AntonioSoler/bga-bonbons<br />
| Morgalad <br />
|-<br />
| Coup: City State<br />
| https://github.com/quietmint/bga-coupcitystate<br />
| quietmint<br />
|-<br />
| Eruption<br />
| https://github.com/AndyKerrison/bga-eruption<br />
| Andy_K<br />
|-<br />
| Florenza: The Card Game<br />
| https://github.com/alberto-bottarini/bga-florenza<br />
| tarini <br />
|-<br />
| Hearts '''(Tutorial)'''<br />
| https://github.com/elaskavaia/bga-heartsla<br />
| Victoria_La<br />
|-<br />
| Incan Gold<br />
| https://github.com/AntonioSoler/bga-incangold<br />
| Morgalad <br />
|-<br />
| Marco Polo<br />
| https://github.com/rcitaliano/MarcoPolo<br />
| rcitaliano<br />
|-<br />
| Nile<br />
| https://github.com/AndyKerrison/bga-nile<br />
| Andy_K<br />
|-<br />
| Noir: Killer vs Inspector<br />
| https://bitbucket.org/chhuang76/bga_noirkvi<br />
| ch huang<br />
|-<br />
| Penny Press<br />
| https://github.com/AdamNovotny/bga-blooms<br />
| A-dam<br />
|-<br />
| P.I.<br />
| https://gitlab.com/fa81/bga-pi, https://github.com/hellp/bga-pi (mirror)<br />
| Fabian Neumann (fa81)<br />
|-<br />
| Tablut<br />
| https://github.com/Lucas-C/tablut<br />
| Lucas-C & ntaffore<br />
|-<br />
| Takara Island<br />
| https://github.com/AntonioSoler/bga-takaraisland<br />
| Morgalad<br />
|-<br />
| Teotihuacan: City of Gods<br />
| https://github.com/Trompetenhut/bga-teotihuacan<br />
| Trompetenhut<br />
|}<br />
<br />
== Projects on studio ==<br />
<br />
Links to studio project which owner wish share as read only.<br />
Project owner please add you project here, dev nickname and short description if you would like to share it.<br />
For the projects below any developer can add themselves to a project as read-only from http://en.studio.boardgamearena.com/#!projects page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! NAME<br />
! CODE LINK<br />
! DEVELOPER<br />
|-<br />
| Shared Code<br />
| http://en.studio.boardgamearena.com/#!studiogame?game=sharedcode<br />
| Victoria_La<br />
|-<br />
| Original BGA template<br />
| http://en.studio.boardgamearena.com/#!studiogame?game=template<br />
| Victoria_La<br />
|-<br />
|}<br />
<br />
== Other useful resources ==<br />
<br />
* Archive of tutorial projects https://www.dropbox.com/s/rsd5r4v49xudpp0/Studio.zip?dl=0<br />
** Note: Hearts project is corrupted there, use Hearts tutorial project above<br />
* Website with bunch of textures and sounds http://www.grsites.com/archive/textures/<br />
* Shrink images without loss of quality https://tinypng.com/ or http://www.iloveimg.com/ (recommended by Gregory Isabelli)<br />
* CSS shapes https://css-tricks.com/examples/ShapesOfCSS/<br />
* PDF Scraper - extract images - http://www.extractpdf.com/<br />
* BoardGameArena Workbench - set of tools to help test and deploy BGA projects - https://github.com/danielholmes/bga-workbench</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Post-release_phase&diff=4048
Post-release phase
2020-04-15T21:21:13Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
Your game is now on BGA: congrats!<br />
<br />
But what happened when there are some bugs to fix or when you want to optimize something?<br />
<br />
Don't be afraid: you're still allowed to modify your game. You just have to pay attention to the points below.<br />
<br />
== Bugs reporting ==<br />
<br />
Bugs are reported in the [http://forum.boardgamearena.com/viewforum.php?f=4 BGA bugs forum].<br />
<br />
During days after your game has been published and from time to time, please have a look at it to check if everything is fine.<br />
<br />
== How to submit changes? ==<br />
<br />
There is 3 (short) steps to make your changes visible on BGA (from your Control Panel):<br />
<br />
* Commit your changes.<br />
* Build a new version (don't forget to do a successful commit BEFORE your build).<br />
* Deploy your new version in production.<br />
<br />
<br />
== What can be modified after release? ==<br />
<br />
Everything can be modified. BUT, some items requires a special attention, and you must inform us in some cases:<br />
<br />
===Changes that breaks the games in progress===<br />
<br />
Some changes will break the games in progress at the moment the release/the hotfix will be performed. Each time you make a change, you should ask you the question "it is safe to make this change in a game in progress", and if the answer is "no" you have to inform us.<br />
<br />
Example of changes that break the games in progress:<br />
* Changes in the database schema of the game (dbmodel.sql).<br />
* New global variable or game option accessed during the game (if it's only used during setup, it should be safe).<br />
* Change ID of existing game states (adding new game states is fine).<br />
<br />
Of course, as a rule of thumb, you should avoid to introduce changes that break a game in progress. Sometimes however, you do not have any other choice. In this case:<br />
* Try to group all your updates in one version, thus we won't have to block your game several times.<br />
* Tell us explicitly that you introduce some update that can break games in progress so we can block the game during a short time.<br />
<br />
Note: in the near future, we will introduce the possibility for you to block/unblock a game directly from your Control Panel in order to perform all the process by yourself.<br />
<br />
=== Updating Statistics ===<br />
<br />
You should be careful when updating a statistics:<br />
<br />
* If you want to add a new statistic, please be aware that for ongoing games this statistic won't always be correct since it has not been counted from the start of that game.<br />
* If you want to update a statistic, please update it and do not remove/create another one. Otherwise, the statistic won't keep the same ID and players will lose all the historical statistics data.<br />
* If your game is published on BGA, please don't remove any statistics (historical data will be lost).<br />
<br />
=== Updating the database schema ===<br />
<br />
If you want to update the database schema of the game (dbmodel.sql), you should inform us before releasing the new version (see "[[#Changes that breaks the games in progress|changes that breaks the games in progress]]").<br />
<br />
Any modification in dbmodel.sql should also appear in your nameofyourgame.game.php, in a function<br />
<br />
function upgradeTableDb( $from_version ){<br />
<br />
if( $from_version <= YYMMDDHHMM ){ // where your CURRENT version in production has number YYMMDD-HHMM<br />
<br />
// You DB schema update request.<br />
// Note: all tables names should be prefixed by "DBPREFIX_" to be compatible with the applyDbUpgradeToAllDB method you should use below<br />
$sql = "CREATE TABLE DBPREFIX_xxxxxxx ....";<br />
<br />
// The method below is applying your DB schema update request to all tables, including the BGA framework utility tables like "zz_replayXXXX" or "zz_savepointXXXX".<br />
// You should really use this request, in conjunction with "DBPREFIX_" in your $sql, so ALL tables are updated. All utility tables MUST have the same schema than the main table, otherwise the game may be blocked.<br />
self::applyDbUpgradeToAllDB( $sql );<br />
<br />
}}<br />
<br />
Note: of course you need to change your dbmodel.sql accordingly, so that new games get your updated scheme.<br />
<br />
Note2: this is always risky to modify the DB scheme, so:<br />
_ it may be worthy to contact us before, so we can stop the realtime games during the update (this way, only turn based games are concerned by the DB live upgrade).<br />
_ if you can avoid it... try to avoid it :)<br />
<br />
=== Updating string to be translated ===<br />
<br />
When you update a string that has been marked to be translatable, please keep in mind that all current translations done by the BGA community will be lost.<br />
<br />
Consequently, when you are about to modify a string to be translated (after release), please ask you the following questions:<br />
* Is it just an English misspelling? In this case, it is better to fix the English translation of the string than the original string to be translated.<br />
* Has the meaning of the string changed? If yes, you HAVE to change the original string in order to invalidate all translations that has been done already.<br />
* Is there a similar string already used elsewhere in my game? In this case, you'd better use it again to enjoy immediately all translations already available.<br />
<br />
===Tell the community about your changes :)===<br />
<br />
The player's community is always happy to know that someone is taking care of their preferred game :)<br />
<br />
If your are the developer of game XXXX, you are also the administrator of player's group "XXXX's players", and you can publish some news in this group newsfeed.<br />
<br />
When you fix a bug or add something, do not hesitate to tell the players about this in this group: you'll get the "thank you" you deserved :)<br />
<br />
See for example Werewolves group:<br />
https://boardgamearena.com/group?id=2465913<br />
<br />
<br />
===Major changes===<br />
<br />
If you do some major changes to your game like:<br />
* Introducing a new expansion.<br />
* Major code rewriting/refactoring.<br />
<br />
... please tell us. In this case, we can:<br />
* Make your game back from "gold" to "public beta", to incite player to report bugs.<br />
* And eventually, publish a news about it :)</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Pre-release_checklist&diff=4047
Pre-release checklist
2020-04-15T21:21:01Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
If you think your game is ready to be reviewed by by BGA admins and/or Publisher please consult this checklist first<br />
<br />
* Metadata and graphics<br />
** [[Game_meta-information: gameinfos.inc.php]] has correct and up to date information about the game<br />
** Game box graphics is 3D version of the game box (if available) and publisher icon is correct (see [[Game art: img directory]]). Space around the box has to be transparent, not white.<br />
** There is no images in img directory which are not needed anymore<br />
** Multiple images (i.e. cards) are compressed in "Sprite" (see [[Game art: img directory]])<br />
** Each image should not exceed 4M<br />
** Total size should not exceed 10M, image compression should be used otherwise<br />
* Server side<br />
** Game progression is implemented (getGameProgression() in php)<br />
** Zombie turn is implemented (zombieTurn() in php). Note: it can only be tested if you explicitly click on the quit button to create a zombie. If you are expelled it does not generated a Zombie.<br />
** You have defined and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)<br />
** Game has meaningful notification messages (but don't overkill it, more user logs will slow down the loading)<br />
** You implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data<br />
* Special testing<br />
** Game is tested with spectator (non player observer)<br />
** Game is tested with in-game replay feature (by clicking on notification log items)<br />
** Game works in Chrome and Firefox browsers at least. Also very recommended to test in IE 11 and Edge.<br />
** Game works on mobile device (if you don't have mobile device to test at least test in Chrome with smaller screen, they have a mode for that)<br />
** Test your game in realtime mode. Usually people will run out of time if you use default times unless you add call giveExtraTime($active_player_id) before each turn<br />
** Test your game in 3D mode<br />
* Cleanup<br />
** Remove all extra console.log from your js code<br />
** Remove all unnecessary debug logging from your php code<br />
** Copyright headers in all source files have your name<br />
* User Interface<br />
** Review BGA UI design Guidelines [[BGA_Studio_Guidelines]]<br />
** Non-self explanatory graphic elements should have tooltips<br />
** If graphic elements appear in notification log they should have titles (i.e. title attribute of div) so can be read in non rendered form (i.e. as text only)<br />
** Strings in your source code are ready for translation. See [[Translations]]<br />
* Finally<br />
** Send e-mail to bga admins asking for review of the game, you cannot post to pre-production yourself using control panel until review is done and they unlock it. If they don't reply post on dev forum.<br />
** If you looking for advise on design and some 3rd party testing you can post a message of developers forum, and ask our developers, there are a lot of people who will gladly do it.</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Studio_FAQ&diff=4046
Studio FAQ
2020-04-15T21:20:46Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This is a place where we will collect and answer frequently asked questions.<br />
<br />
== What should I use to access the files through SFTP? ==<br />
<br />
There is a lot of tools to do that. Use the one you are the most comfortable with.<br />
<br />
On Linux Gnome, you can for example use the 'Connect to server' function of the Nautilus file management system, or use sshfs.<br />
<br />
On Windows, there is for example the [http://winscp.net/ WinSCP client].<br />
<br />
See [[Tools_and_tips_of_BGA_Studio#File_Sync]] for more details.<br />
<br />
== I can't edit the files in my game directory, it looks like they are readonly. What's happening? ==<br />
<br />
You can lose access sometimes if you add another developer as read/write or admin.<br />
<br />
Maybe there is a maintenance operation underway.<br />
<br />
If you don't get access back after some time (say one or two hours), please post on dev forum.<br />
<br />
== What is the working language on BGA studio? ==<br />
<br />
Working language is '''English'''.<br />
<br />
Variables and functions must be named with English words.<br />
<br />
Comments must be written in English.<br />
<br />
Game interface strings and game logs must be written in English.<br />
<br />
== How can I provide translation in my language? == <br />
<br />
The community will translate the game in all language after the game release with the collaborative translation interface can be used to translate into other languages.<br />
<br />
Check [[Translations]] to see how to make your game translatable.<br />
<br />
== I updated the images in the 'img' folder of my game, but they don't show? ==<br />
<br />
'''Concerning game_box.png, game_icon.png and publisher.png''':<br />
You must use "Reload game box image" function from "Control Panel / Manage Games / Your game" to make your change visible.<br />
<br />
'''Concerning other images''':<br />
Other images used during the game are immediately available without any action.<br />
If the images still don't show after that, please try emptying your browser cache and reloading the page.<br />
<br />
== I added some game options / some game statistics / some game infos but they don't show? ==<br />
<br />
When you modify one of these 3 files, you need to use the corresponding update action from "Control Panel / Manage Games / Your Game" in order we can take this information into account.<br />
<br />
== Should I use images free from copyright? ==<br />
<br />
If you are developing a game in the public domain, yes (or you can make your own if you feel it's better). <br />
<br />
If you are developing a game for which we have a licence, we will usually provide art files from the publisher.<br />
<br />
<br />
== I registered on Studio but did not receive email ==<br />
<br />
If you using standard email address (such as gmail, yahoo, outlook) its in junk folder, search for "bga".<br />
<br />
If you use some proprietary email address, it possible that your mail server denies emails from bga, in this case post message on the forum and specify login name your have chosen. Don't attempt to register again with same email, it likely will fail again. But if you have alternative standard email account use it instead.</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Troubleshooting&diff=4045
Troubleshooting
2020-04-15T21:20:05Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
Describing common errors which is hard to understand and debug <br />
<br />
== Game does not start at all ==<br />
<br />
=== Undefined offset: 0 in table/table.game.php on line 830 ===<br />
<br />
You are likely calling self::getActivePlayerName () during setupNewGame()<br />
<br />
=== Unexpected error: Wrong formatted data from BGA gameserver 1 (method: createGame): ... ===<br />
<br />
This is generic message usually followed by exact position in your source code, and usually its syntax error in one of yours php script<br />
<br />
=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Not logged ===<br />
<br />
Calling self::getCurrentPlayerId () or using $g_user from 'args' state function, see also below<br />
<br />
=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Unknow player statistic: ===<br />
<br />
Calling self::incStat() with second parameter which is an empty string<br />
<br />
<br />
=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Error while processing SQL request: INSERT INTO stats ... ===<br />
<br />
Fatal error during yourgame setup: Error while processing SQL request: INSERT INTO stats (stats_type, stats_player_id, stats_value) VALUES ('10','2300663','0'),('10','2300662','0')<br />
Duplicate entry '10-2300663' for key 'stats_table_id'<br />
<br />
Why? In the stats.inc.php you declared two keys with the same integer "id"<br />
<br />
=== Fatal error during creation of database ebd_quoridor_389 Not logged ===<br />
<br />
Check that you didn't use $g_user or getCurrentPlayerId() in setupNewGame() function or in an 'args' function of your state.<br />
<br />
As these functions are not consequences of a user action, there is no current player defined.<br />
<br />
As a general rule, you should use getActivePlayerId() and not getCurrentPlayerId(). See the [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine presentation on the game state machine] for more information.<br />
<br />
=== Warning: Invalid argument supplied for foreach() in table.game.php ===<br />
<br />
Warning: Invalid argument supplied for foreach() in /var/tournoi/release/tournoi-151226-1240-gs/www/game/module/table/table.game.php on line 129 <br />
Fatal error: Cannot unset string offsets in /var/tournoi/release/tournoi-151226-1240-gs/www/game/module/table/table.game.php on line 143<br />
<br />
That appears when your arg* function that suppose to return array of state arguments returns a scalar (a non-array) value<br />
<br />
=== The server reported an error ===<br />
<br />
During table creation: "The server reported an error" error shown and nothing else.<br />
<br />
If you cannot even create a table - there is syntax error in gameinfos.php, check it, reload it from management panel.<br />
If still no luck copy clean version from template https://github.com/elaskavaia/bga-sharedcode/blob/master/gameinfos.inc.php<br />
<br />
== Predefined server errors ==<br />
<br />
=== Unexpected error: Unexpected final game state (XX) ===<br />
<br />
The action function does not transition to any state, i.e.<br />
function selectField($field) {<br />
self::checkAction ( 'selectField' );<br />
if ($field!=0) $this->gamestate->nextState ( 'next' );<br />
}<br />
Here if $field is 0 there is no transition<br />
<br />
=== This game action is impossible right now ===<br />
<br />
Check the game log. Usually your state does not define the action you trying to perform in 'possibeactions' array.<br />
<br />
=== Unexpected error: This transition (playerTurn) is impossible at this state (42) ===<br />
<br />
This is pretty self explanatory. Function nextState() takes transition name not a state name, so you probably did not<br />
define this transition that the given state<br />
<br />
== Game interface hangs during reload or on start ==<br />
<br />
Showing "Application Loading..."<br />
<br />
=== Javascript error: During pageload undefined no_stack_avail Script: ===<br />
<br />
This error usually has no useful data, but it means you called somes API that require a callback and did not define callback function, i.e<br />
in dojo.connect, this.connectClass, dojo.subscribe, etc<br />
<br />
this.connectClass('field', 'onclick', 'onField'); // <-- onField is not defined<br />
<br />
=== Other errors with "Application loading..." ===<br />
<br />
You probably have a syntax error in your Javascript code, and the interface refuses to load.<br />
<br />
To find this error, check if there is an error message in the Javascript console (F12).<br />
<br />
If there is really nothing on the log, it's probably that the system was unable to load your Javascript because of an syntax error that affect the structure of the Javascript file, typically a missing "}" or a missing "," after a method definition.<br />
<br />
If you have "Uncaught ReferenceError: bgagame is not defined" you have major syntax error in your js file, you should see some other clues in the log where the errors is.<br />
<br />
=== Unexpected Syntax Error: ===<br />
<br />
No further details in the log. When log is filling with some social connect errors.<br />
<br />
Possible Reason: Syntax error in of the php script which is loaded before the start, such as gameoptions.inc.php, gameinfos.inc.php and such.<br />
<br />
=== Game interface spins in a loop throwing error ===<br />
<br />
Errors is something like "Cannot read property 'is_ai' of undefined". Cannot restart the game because cannot access UI to stop.<br />
Likely you get in actplayer state with player id == 0. The only way to fix it is to edit database, globals index == 2 set player id to one of your test dudes<br />
(can copy from row 5 for example).<br />
<br />
== Other Errors ==<br />
<br />
<br />
=== When I do a move, I got "Move recorded, waiting for update ..." forever ===<br />
<br />
"Move recorded" means that your ajaxcall request has been sent to the server and returned normally.<br />
<br />
"Waiting for update" means that your client interface is waiting for some notifications from the server that correspond to the move we just did.<br />
<br />
If this message stays forever, it is probably that your PHP code does not send any notification when the move happens, which is abnormal. To fix this: add a notifyAllPlayers or a notifyPlayer call in your PHP code.<br />
<br />
=== When I do a move, I get "Sending move to server..." the nothing and game resets to state before the move ===<br />
<br />
Its possible that server code get into infinite loops or thinks too much, in which case it will timeout and will be aborted without any extra logs (and any db transaction you saw in the log won't be committed). You will usually see "Unable to connect to server" message on console in this case. You have to put more logging into server<br />
to trace where it hangs.<br />
<br />
<br />
=== Some player action is triggered randomly when I click somewhere on the game area ===<br />
<br />
You probably used "dojo.connect" on a null object. In this case, dojo.connect associate the event (ex: "onclick") to the whole game area.<br />
<br />
Most of the time it happens in this situation, when my_object element does not exists:<br />
<pre><br />
dojo.connect( $("my_object"), "onclick", this, function() {<br />
...<br />
}<br />
</pre><br />
<br />
To determine if this is the case, place "alert( $("my_object") )" before the dojo.connect to check if the object exists or not.<br />
<br />
=== Javascript does not know how to sum two numbers ===<br />
<br />
Be careful when you manipulate integers returned by notifications: most of the time, Javascript considers they are Strings and not Integers.<br />
<br />
As a result:<br />
<pre><br />
var i=1;<br />
i += notif.args.increment; // With notif.args.increment='1'<br />
alert( i ); // i=11 instead of 2 !! Javascript concatenate 2 strings !<br />
</pre><br />
<br />
To solve this, you should use the "toint" function:<br />
<pre><br />
var i=1;<br />
i += toint( notif.args.increment ); // With notif.args.increment='1'<br />
alert( i ); // i=2 :)<br />
</pre><br />
<br />
=== Javascript: do not use substr with negative numbers ===<br />
<br />
To get the last characters of a string, use "slice" instead of "substr" which has a bug on IE:<br />
<pre><br />
var three_last_characters = string.substr( -3 ); // Wrong<br />
var three_last_characters = string.slice( -3 ); // Correct<br />
</pre><br />
<br />
=== Game "spontaneously" transition to a new state without user input ===<br />
<br />
Make sure on php side you have no code after $this->gamestate->nextState(...) code.<br />
Because if you do accidentally have code that goes to another state it will cause another state transition without user interaction.<br />
<br />
function selectField($field) {<br />
self::checkAction ( 'selectField' );<br />
if ($field!=0) $this->gamestate->nextState ( 'next' );<br />
$this->gamestate->nextState ( 'last' ); // <-- here is missing else, so it will cause double state transition<br />
}<br />
<br />
=== On php side I get a number instead of string I expect ===<br />
<br />
$num = 3;<br />
$meeple = "meeple_" + $num; // <-- suppose to be "meeple_3"!<br />
<br />
When you switch between JS and PHP it easy to type this and not notice the +. Plus sign (+) in php does not mean string concatenation (in javascript does!),<br />
in php + means integer arithmetic. So change + to . (dot)<br />
<br />
=== On php side my string comparison does not work ===<br />
<br />
if ($color == '4baae2' || $color == '000000') { <br />
}<br />
<br />
Apparently you should not be using '==' in php to compare strings! You should use '==='. The (==) operator will typecast the strings <br />
to numbers then do comparison!<br />
Its not very apparent because usually you can get away with it, but not when strings resemble numbers like hex 'colors'.</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=BGA_Studio_Guidelines&diff=4044
BGA Studio Guidelines
2020-04-15T21:19:53Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
= BGA Studio Guidelines = <br />
<br />
Originally From: https://www.slideshare.net/boardgamearena/bga-studio-guidelines<br />
<br />
<br />
<br />
== Why guidelines? ==<br />
More and mode game publishers are choosing Board Game Arena for their game adaptations because the quality of these adaptations is high.<br />
If we want to continue to have nice games in the future, we have to make sure that every game published in the BGA platform is matching the quality standards of BGA.<br />
These guidelines are here to help you to make your game easy to use by BGA players, and to make sure its going to be validated by the game publisher.<br />
<br />
== General guidelines == <br />
The 3 main important guidelines <br />
* If a player knows the real board game, he should be able to play your adaptation with no learning.<br />
* Fidelity to the original game is an absolute requirement.<br />
* Don't try to create a video game: make your game interface as close as possible to how the original board game looks like.<br />
<br />
== Game layout ==<br />
=== I-1 Don't hide game elements ===<br />
<br />
Many board games have a lot of material to display, and computer screens are sometimes too small.<br />
But you are lucky: your game will be on a webpage with a scrolling functionality. <br />
Basically, you always have some more space available .<br />
Don't hide game elements behind menus, submenus, dialogs, etc, but display them directly on the main page.<br />
<br />
Tips: eventually, you can use HTML anchor link to jump between the different elements of the page if the page height is very big. <br />
<br />
Examples:<br />
<br />
In Amyitis, characters cards are elements you don't have to check all the time. Thus, we placed them at the bottom of the page and you have to scroll to see them.<br />
<br />
In Madeira, additional game board are shown at the bottom, but when player needs to use it it moved up.<br />
<br />
Rule: <br />
* If real game has visible elements on the table it should be visible on the main screen or user mini boards on the right<br />
<br />
Exceptions:<br />
* Showing counts of same elements is sufficient<br />
* For decks which can be inspected it permitted to show them on demand<br />
* If some games you can cut off score track and replace with BGA scoring (stars), but keeping it will look nicer (but you have to keep track of score on it as well)<br />
* Its not necessary to show helper cards such as turn overview or scoring overview but it would be nice if you can incorporate that as well<br />
<br />
=== I-2 Make it fluid ===<br />
<br />
BGA game interface is «fluid». It means the interface width can vary in order to use extra space on the screen when available.<br />
HTML and CSS give us a lot of possibilities to adapt a web content to a given browser width.<br />
You have to use HTML and CSS:<br />
* To allow players owning a big screen to enjoy the game comfortably without scrolling the page.<br />
* To allow players with a screen of just 1024px <br />
<br />
Tips: for each element of the game, answer this question « how many times during a game do I need to check/use this element? ».Less frequently used elements can be placed below.<br />
You can listen on display resize in JS to do more sophisticated layouts.<br />
<br />
Examples:<br />
<br />
Caylus: when we have a 1024px small width to play the game – even if they have to screen, available buildings are placed scroll on the the right and below the board.<br />
On larger screen, these tiles are placed on the right of the board. This is a very basic usage of the others. « float:left » CSS property.<br />
<br />
=== I-3 Use whiteblocks ===<br />
White blocks are '''div''' HTML element with the '''whiteblock''' class (white and transparent background). This is the recommended way to gather game elements together in your game interface when they are not directly on a board. Whiteblocks helps you to organize the space in order it can be easily understood by players.<br />
<br />
If game contains individual player boards with distinct colors or marking you don't need these boards inside the whiteblock.<br />
<br />
''Tips: you can use a '''h3''' title inside the whiteblock to help players to understand what is inside or to who it belongs.''<br />
<br />
In The Year of the Dragon game interface, with whiteblocks and h3 titles /picture here/<br />
<br />
=== I-4 Use player panels ===<br />
<br />
BGA players are used to look at player panels when they need an information about a player.<br />
Using player panels can allow you to save a lot of space on the main game space. In general, the following information is placed in the player panel:<br />
* Players resources (i.e. small game elements the player is keeping in front of him in the real game).<br />
* Summary information about player (i.e. number of cards in hand, number of cards played...).<br />
* « First player » token.<br />
* Score. <br />
<br />
Player panels in Seasons. /picture/ A lot of useful information can fit into these small spaces :)<br />
<br />
Note: for all games, you must always use the standard BGA score counter (with the star). Players are used to check this counter to see who is winning the game.<br />
<br />
=== I-5 Use status bar actions ===<br />
<br />
When some game action is particular to a specific game state, the good practice is to use a status bar action (HTML link).<br />
Don't try to place some icon in your main gameinterface that will be useless 95% of the time: it takes space and makes the interface more complex to understand. <br />
<br />
Status bar actions in Tobago /picture/<br />
<br />
== Game usability ==<br />
<br />
=== II-1 Use tooltips ===<br />
<br />
With BGA Studio its very easy to associate a tooltip on any element of the game. Each time this is possible: add a tooltip to explain to the players:<br />
* What is this game element?<br />
* What happens if I click on it?<br />
However, tooltips should NOT be used to display dynamic information about the current game to save space on the game interface. <br />
Typically, regular players should be able to card tooltip play with no tooltips. <br />
However you can display some dynamic stuff if its available otherwise but just annoying to calculate. For example in Lewis and Clark author asked to put<br />
tooltips of how many river space available ahead of explorer.<br />
If you need to show user why they cannot interact with element show errors instead (when clicking on it).<br />
<br />
Tips: you can place any HTML element in tooltips. So you can make them as rich and beautiful as you need :)<br />
<br />
=== II-2 Use left click only ===<br />
* The whole game should be playable with only simple left button mouse click.<br />
* Context menus should not be used.<br />
* Drag-n-drop should be avoided (if you want to use it anyway, you should make a click based alternative available).<br />
* Mouse icon must change on clickable elements (« cursor:pointer » CSS property). <br />
<br />
=== II-3 Make your interface intuitive ===<br />
If your testers have different opinions about « how to trigger some game action », maybe <br />
the best is to make several options possible for this game action. In the case there is a complex action to do by the player (ex: select some cards, then click on an action button), design your error messages in order they can guide the player(ex : « please select some cards first »).<br />
<br />
''Tips: For complex games, it is simple and useful to highlight the area of the interface where player should focus his attention (using onEnteringState/onLeavingState and CSS class, i.e. 'active_slot').'' <br />
<br />
The Boss: when a player clicks on a card with no selected cubes, the interface tells us to select some cube first.<br />
<br />
=== II-4 Use the gamelog ===<br />
With BGA Studio it is very easy to place sometext (or HTML code) in the gamelog.<br />
Don't hesitate to use the game log.<br />
Players are not always in front of the game page when their opponents are making their moves.<br />
In addition, the computer manipulates game elements faster than you usually do with the real board game and even regular players can get behind of what happened sometimes.<br />
You should be able to understand the « game story » by reading the game log. <br />
<br />
=== II-5 Tell players about automatic actions ===<br />
Very often, during a game you are in a situation where:<br />
* Only one action is possible for the activeplayer, or<br />
* A series of action has to be done (according to the rules) without any players actions.<br />
In these situation, you must or you may trigger these actions automatically.<br />
In any case, you must make sure that players understand what is happening, otherwise they will probably report a bug. <br />
<br />
Stone Age: people are fed automatically at the end of the turn, but players can always see what happened exactly in the gamelog.<br />
<br />
* Use the game log to trace all actions performed automatically. <br />
* Use synchronous notifications handlers to slow down the execution of automatic actions,so that players can understand what is happening.<br />
=== II-6 Avoid move confirmations ===<br />
As a rule of thumb, don't require move confirmation. Confirming a move slows down the user interface and thus, the game flow. You can allow a player to confirm a move if this is a very critical step in a game, and if it is possible to trigger an action by accident. If client interactions are very complex and allow cancellation, the final move can be confirmed with a "Done" button.<br />
<br />
''Hawaii'': Ending a turn is a critical action that happens only 5 times per player in a game. In this case, it is acceptable (and a good idea) to have a confirmation dialog.<br />
<br />
''Hive'': Each move has to be confirmed with click on the location because it is very easy to click by accident.<br />
<br />
''Russian Railroads'': Each move involves multiple interactions and can contains dozens of subactions. When the player is done "planning" he presses a "Done" button to submit the move to the server.<br />
<br />
=== II-7 Translatable interface ===<br />
With BGA Studio its very easy to translate your game in any language, using BGA collaborative translation system. Check the FAQ and the example games to learn how to declare your strings so that every message in your code can be managed by the internationalization system. <br />
<br />
Diams 100 % translated in Polish<br />
<br />
=== II-8 Use interactive elements ===<br />
<br />
Interactive elements are tiles, cubes or board areas user can click on to perform an action. The following guidance apply:<br />
* If user click on interactive element either action happens or user get a error message. Try to process error message of client side and not send to server for simple errors, such as player is not active. Please be very specific why user cannot interact with element, i.e.<br />
** This is not your turn<br />
** You cannot build this building because you don't have enough resources<br />
** To select this card you have to select resource first<br />
If you cannot make errors for all elements at least tooltip should explaining when it interactive vs not<br />
<br />
Rule: Every game element should give an explicit error message if clicked at the wrong moment rather than staying silent<br />
<br />
* When user can click on element during this turn it should be highlighted if possible (i.e. tiles have blue border or dashed or glow)<br />
<br />
* If state prompt replaces the interaction with element but elements are visible its better to do both (i.e. can select a button OR he can move element on the board)<br />
** Example: In Lewis & Clark game offers gain resources via buttons on state prompt, but user can also click on cubes in supply to do the same action<br />
<br />
=== II-9 Animate moving elements ===<br />
If real game have some elements moving during the game it should also animate in your adaptation<br />
* User gets a resource - move a resource from main board to user mini board<br />
* User buys a card - move card from main display to user board<br />
* User draw a card which is revealed on the display - move card from deck to display, maybe add flippy animation to turn it face up (that requires 3d transformations - that is bonus)<br />
<br />
It is also nice to animation points or coin collection from specific region of the board (even points collection is not normally visible), see Terra Mystica for final scoring animation<br />
<br />
Don't need to overdo animation - its not first player shooter<br />
<br />
== Original game representation ==<br />
=== III-1 Use the original art===<br />
The less you are modifying the original art of the game, the better.<br />
Its important for publishers that a board game adaptation looks like the real board game. Sometimes it can be useful to modify some elements of the game to save some space on the screen – but try to avoid it.<br />
Tips: if you have not enough space on the screen, reduce the size of the game elements. <br />
Try to make sure they are recognizable for players who played regularly, and add a tooltip to help beginners to figure out what they are. <br />
Gosu : the original cards are used, with tooltips.<br />
<br />
=== III-2 Be careful about player assistance ===<br />
As a rule of thumb, in order to respect the original board games, you should not introduce any player assistance feature.<br />
An assistance must not be introduced if it directly helps the player to figure out if his move is good or bad.<br />
An assistance may be introduced if it can helps the payer to figure out what moves are available.<br />
<br />
Gygès: the assistance shows you available moves, but is not alerting you about stupid moves (like the upper left one).<br />
<br />
Note: you can however do a singe choice move for a player, i.e passing on a turn if there is nothing user can do, its is quite annoying to wait on a player to pass, while its only action that he can do anyways.<br />
<br />
=== III-3 Cancel a move ===<br />
Most players want to have moved cancel or undo. User the following rules to implement it:<br />
* If any information is revealed which was not known before you cannot cancel it<br />
* If this is the end of active player action - you cannot cancel it<br />
* If during player turn multiple actions are required allow cancel or undo, for example - user pick cubes and drops on a building. Selecting cube and building - are two actions, so user should be able to cancel taking cube.<br />
This can be implement using client side states, so cancelling is easy as restoring last server state.<br />
<br />
=== III-4 Available information ===<br />
Every information visible by players in the real game should be accessible in the adaptation. Pay attention to some information like the number of cards in the opponents hand, or the number of remaining cards in the deck. <br />
If it is explicitly forbidden to count cards in the discard pile, so this information is not available.<br />
<br />
== Game technical quality ==<br />
=== IV-1 Don't use exotic stuff ===<br />
BGA Studio provides a set of useful tools to build board games adaptations (i.e. card management, confirmation dialog, tooltips,…).<br />
Use them, and don't use exotic libraries, plugins or tricks.<br />
Why? Because BGA Framework will evolve in the future to provide new features to players, and it could make your game incompatible with the new version.<br />
On the contrary, if you are using standard Haggis using BGA standard card stuff, you will enjoy these enhancements without any effort.<br />
If you feel that you really need some exotic thing: don't hesitate to ask us.<br />
<br />
=== IV-2 Write in (simple) English ===<br />
Some other person may have to look on your code:<br />
* We (BGA team) are here to help you if you need us<br />
* Some other BGA developer wanting to help you<br />
For all these reasons, your code must be written in English (variables, methods,comments...).<br />
If English is not your mother tongue don't be afraid: the whole idea here is to be understood, not to write an essay :)<br />
<br />
=== IV-3 Page refresh ===<br />
A page refresh (F5) must allow players to reset the game interface to a stable state at any moment of the game.<br />
BGA Studio framework allows you to do this with the « getAllDatas » PHP method and the « setup » Javascript method.<br />
Note: this « refresh » feature is also quite useful during the development process:)<br />
<br />
=== IV-4 Private information ===<br />
A private game element must be visible only to the player owning it. It must not be visible by his opponents, by any means.<br />
In particular: <br />
* getAllDatas PHP method must not return any element that are hidden from current player, even if the Javascript « setup » method ignores them.<br />
* you must not send via the « notifyAllPlayers » function some information that is hidden from one player (use « notifyPlayer » instead). <br />
<br />
<br />
Hearts: each player is alerted about his new cards using notifyPlayer, and cards from the other players remains secret<br />
<br />
=== IV-5 Game progression ===<br />
Game progression should be as accurate as possible.<br />
Of course, its not always easy (or even possible) to compute game progression, but a vague approximation is better than nothing. <br />
Stone Age: there are 2 different end game conditions (building cards and civilization cards). <br />
Both are taken into account to increase the accuracy of the game progression.<br />
<br />
=== IV-6 Game statistics ===<br />
Using BGA Studio you can define a set of statistics for your game. Statistics will be displayed at the end of the game, and help players to figure out why they win/loose a game, <br />
and what they should improve. Try to choose interesting statistics that distinguish the different strategies for your game, in order it can help players to understand their game. <br />
<br />
Seasons : statistics<br />
== Summary ==<br />
These guidelines are here to help you to make sure that the players, the game publisher and the game author are going to enjoy your adaptation of the game. We created these guidelines based on our personal experience (which includes many mistakes along the way) implementing a lot of games on BGA platform. Don't hesitate to contact us if you feel uncomfortable with one of these guidelines in some particular context with your game: these guidelines are here to help and not to prevent you to do smart things, and have fun while programing your game ;)</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=BGA_Studio_Cookbook&diff=4043
BGA Studio Cookbook
2020-04-15T21:16:36Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This page is collection of design and implementation recipes for BGA Studio framework.<br />
For tooling and usage recipes see [[Tools and tips of BGA Studio]].<br />
If you have your own recipes feel free to edit this page.<br />
<br />
== Visual Effects, Layout and Animation ==<br />
<br />
=== Create pieces dynamically (using template) ===<br />
<br />
'''Ingredients:''' ggg_ggg.tpl, ggg.js<br />
<br />
Note: this method is recommended by BGA guildlines<br />
<br />
Declared js template with variables in .tpl file, like this<br />
<pre><br />
<script type="text/javascript"><br />
// Javascript HTML templates<br />
var jstpl_ipiece = '<div class="${type} ${type}_${color} inlineblock" aria-label="${name}" title="${name}"></div>';<br />
</script><br />
</pre><br />
<br />
Use it like this in .js file<br />
div = this.format_block('jstpl_ipiece', {<br />
type : 'meeple',<br />
color : 'ff0000',<br />
name : 'Bob',<br />
});<br />
<br />
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.<br />
<br />
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<br />
it is good to strive for it.<br />
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.<br />
<br />
<br />
=== Create pieces dynamically (using string concatenation) ===<br />
<br />
'''Ingredients:''' ggg.js<br />
<br />
Note: Not recommended<br />
<br />
<pre><br />
div = "<div class='meeple "+color+"'></div>";<br />
</pre><br />
=== Create all pieces statically ===<br />
<br />
'''Ingredients:''' ggg_ggg.tpl, ggg.css, ggg.view.php (optional) <br />
<br />
* Create ALL game pieces in html template (.tpl)<br />
* ALL pieces should have unique id, and it should be meaningful, i.e. meeple_red_1d<br />
* Do not use inline styling<br />
* 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...)<br />
* 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<br />
<br />
in .tpl file:<br />
<pre> <br />
<div id="home_red" class="home red"><br />
<div id="meeple_red_1" class="meeple red n1"></div><br />
<div id="meeple_red_2" class="meeple red n2"></div><br />
</div><br />
</pre><br />
<br />
in .css file:<br />
<br />
<pre><br />
.meeple {<br />
width: 32px;<br />
height: 39px;<br />
background-image: url(img/78_64_stand_meeples.png);<br />
background-size: 352px;<br />
}<br />
<br />
.meeple.red {<br />
background-position: 30% 0%;<br />
}<br />
</pre><br />
<br />
* There should be straight forward mapping between server id and js id (or 1:1)<br />
* You place objects in different zones of the layout, and setup css to take care of layout<br />
<br />
<pre><br />
.home .meeple{<br />
display: inline-block;<br />
}<br />
</pre><br />
* If you need to have a temporary object that look like original you can use dojo.clone (and change id to some temp id)<br />
* 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<br />
<br />
Note:<br />
* If you use this model you cannot use premade js components such as Stock and Zone<br />
* 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<br />
<br />
=== Use thematic fonts ===<br />
<br />
'''Ingredients:''' ggg.css<br />
<br />
Sometime game elements use specific fonts of text, if you want to match it up you can load some specific font (from some free font source).<br />
<br />
[[File:Dragonline_font.png]]<br />
<br />
.css<br />
<pre><br />
/* latin-ext */<br />
@font-face {<br />
font-family: 'Qwigley';<br />
font-style: normal;<br />
font-weight: 400;<br />
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/2Dy1Unur1HJoklbsg4iPJ_Y6323mHUZFJMgTvxaG2iE.woff2) format('woff2');<br />
unicode-range: U+0100-024F, U+1E00-1EFF, U+20A0-20AB, U+20AD-20CF, U+2C60-2C7F, U+A720-A7FF;<br />
}<br />
/* latin */<br />
@font-face {<br />
font-family: 'Qwigley';<br />
font-style: normal;<br />
font-weight: normal;<br />
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/gThgNuQB0o5ITpgpLi4Zpw.woff2) format('woff2');<br />
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;<br />
}<br />
@font-face {<br />
font-family: 'Qwigley';<br />
font-style: normal;<br />
font-weight: normal;<br />
src: local('Qwigley'), local('Qwigley-Regular'), url(http://ff.static.1001fonts.net/q/w/qwigley.regular.ttf) format('ttf');<br />
}<br />
<br />
.zone_title {<br />
display: inline-block;<br />
position: absolute;<br />
font: italic 32px/32px "Qwigley", cursive; <br />
height: 32px;<br />
width: auto;<br />
}<br />
</pre><br />
<br />
<br />
=== Use player color in template ===<br />
<br />
'''Ingredients:''' ggg_ggg.tpl, ggg.view.php<br />
<br />
.view.php:<br />
<pre><br />
function build_page($viewArgs) {<br />
// Get players & players number<br />
$players = $this->game->loadPlayersBasicInfos();<br />
$players_nbr = count($players);<br />
/**<br />
* ********* Place your code below: ***********<br />
*/<br />
<br />
// Set PCOLOR to the current player color hex<br />
global $g_user;<br />
$cplayer = $g_user->get_id();<br />
if (array_key_exists($cplayer, $players)) { // may be not set if spectator<br />
$player_color = $players [$cplayer] ['player_color'];<br />
} else {<br />
$player_color = 'ffffff'; // spectator<br />
}<br />
$this->tpl ['PCOLOR'] = $player_color;<br />
</pre><br />
<br />
=== Scale to fit for big boards ===<br />
<br />
'''Ingredients:''' ggg_ggg.tpl, ggg.js<br />
<br />
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. <br />
My display is 1920 wide so it fits, but there is big chance other people won't have that width. What do you do?<br />
Easiest thing I came up with is to scale whole content to fit (everything you declare in .tpl file). Tested or firefox and chrome.<br />
<br />
ggg_ggg.tpl:<br />
<pre><br />
<div id="thething" class="thething" style="width: 1400px;"><br />
... everything else you declare ...<br />
</div><br />
</pre><br />
<br />
ggg.js:<br />
<pre><br />
setup : function(gamedatas) {<br />
console.log("Starting game setup");<br />
...<br />
this.interface_min_width = 740;<br />
this.interface_max_width = 1400;<br />
dojo.connect(window, "onresize", this, dojo.hitch(this, "adaptViewportSize"));<br />
},<br />
<br />
adaptViewportSize : function() {<br />
var pageid = "page-content";<br />
var nodeid = "thething";<br />
<br />
var bodycoords = dojo.marginBox(pageid);<br />
var contentWidth = bodycoords.w;<br />
<br />
var browserZoomLevel = window.devicePixelRatio; <br />
//console.log("zoom",browserZoomLevel);<br />
if (contentWidth >= this.interface_max_width || browserZoomLevel >1 || this.control3dmode3d) {<br />
dojo.style(nodeid,'transform','');<br />
return;<br />
}<br />
<br />
var percentageOn1 = contentWidth / this.interface_max_width;<br />
dojo.style(nodeid, "transform", "scale(" + percentageOn1 + ")");<br />
},<br />
</pre><br />
<br />
=== Dynamic tooltips ===<br />
<br />
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.)<br />
<br />
new dijit.Tooltip({<br />
connectId: ["divItemId"],<br />
getContent: function(matchedNode){<br />
return "... calculated ..."; <br />
}<br />
});<br />
<br />
<br />
This is an out-of-the-box djit.Tooltip. It has a ''getContent'' method which is called dynamically.<br />
<br />
The string function return becomes the innerHTML of the tooltip, so it can be anything (matchedNode in this case) 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.<br />
<br />
[https://dojotoolkit.org/reference-guide/1.10/dijit/Tooltip.html dijit.Tooltip]<br />
<br />
It's not part of the BGA API so use at your own risk.<br />
<br />
=== Accessing images from js ===<br />
<br />
'''Ingredients:''' ggg.js<br />
ggg.js<br />
<br />
<pre> <br />
// your game resources<br />
<br />
var my_img = '<img src="'+g_gamethemeurl+'img/cards.jpg"/>';<br />
<br />
// shared resources<br />
var my_help_img = "<img class='imgtext' src='" + g_themeurl + "img/layout/help_click.png' alt='action' /> <span class='tooltiptext'>" +<br />
text + "</span>";<br />
</pre> <br />
<br />
=== Inject images and styled html in the log ===<br />
<br />
'''Ingredients:''' ggg.js, ggg.game.php<br />
<br />
So you want nice pictures in the game log, what do you do? First idea that come to mind is to send html from php in notifications. <br />
This is bad idea for many reasons<br />
* Its bad architecture, ui elements leak into server now you have to manage ui in many places<br />
* If you decided to change something in ui in future version, old games reply and tutorials may not work, since they use stored notifications<br />
* When you read log preview for old games its unreadable (this is log before you enter the game reply, useful for troubleshooting or game analysis)<br />
* Its more data to transfer and store in db<br />
* Its nightmare for translators<br />
<br />
So what else can you do? I use this recipe which I is client side log injection. I intercept log arguments and replace them by html on my client side.<br />
<br />
[[File:clientloginjection.png|left]] <br />
<br />
ggg.js<br />
<br />
<pre> <br />
<br />
/** Override this function to inject html for log items */<br />
<br />
/* @Override */<br />
format_string_recursive : function(log, args) {<br />
try {<br />
if (log && args && !args.processed) {<br />
args.processed = true;<br />
<br />
if (!this.isSpectator)<br />
args.You = this.divYou(); // will replace ${You} with colored version<br />
<br />
// list of other known variables<br />
var keys = ['place_name','token_name'];<br />
<br />
<br />
for ( var i in keys) {<br />
var key = keys[i];<br />
if (typeof args[key] == 'string') {<br />
args[key] = this.getTokenDiv(key, args); <br />
}<br />
}<br />
}<br />
} catch (e) {<br />
console.error(log,args,"Exception thrown", e.stack);<br />
}<br />
return this.inherited(arguments);<br />
},<br />
<br />
/* Implementation of proper colored You with background in case of white or light colors */<br />
<br />
divYou : function() {<br />
var color = this.gamedatas.players[this.player_id].color;<br />
var color_bg = "";<br />
if (this.gamedatas.players[this.player_id] && this.gamedatas.players[this.player_id].color_back) {<br />
color_bg = "background-color:#" + this.gamedatas.players[this.player_id].color_back + ";";<br />
}<br />
var you = "<span style=\"font-weight:bold;color:#" + color + ";" + color_bg + "\">" + __("lang_mainsite", "You") + "</span>";<br />
return you;<br />
},<br />
<br />
<br />
</pre><br />
<br />
<br />
<pre><br />
getTokenDiv : function(key, args) {<br />
// ... implement whatever html you want here, example from sharedcode.js<br />
var token_id = args[key];<br />
var item_type = getPart(token_id,0);<br />
var logid = "log" + (this.globalid++) + "_" + token_id;<br />
switch (item_type) {<br />
case 'wcube':<br />
var tokenDiv = this.format_block('jstpl_resource_log', {<br />
"id" : logid,<br />
"type" : "wcube",<br />
"color" : getPart(token_id,1),<br />
});<br />
return tokenDiv;<br />
break;<br />
case 'meeple':<br />
if ($(token_id)) {<br />
var clone = dojo.clone($(token_id));<br />
<br />
dojo.attr(clone, "id", logid);<br />
this.stripPosition(clone);<br />
dojo.addClass(clone, "logitem");<br />
return clone.outerHTML;<br />
}<br />
break;<br />
<br />
default:<br />
break;<br />
}<br />
<br />
return "'" + this.clienttranslate_string(this.getTokenName(token_id)) + "'";<br />
},<br />
getTokenName : function(key) {<br />
return this.gamedatas.token_types[key].name; // get name for the key, from static table for example<br />
},<br />
</pre><br />
<br />
Note in this case server simply injects token_id as name, and client substitutes it for the real translated name or the picture<br />
<br />
ggg.game.php:<br />
<br />
$this->notifyPlayer($player_id,'playerLog',clienttranslate('${You} moved cube'),['You'=>'You']);<br />
<br />
ggg.game.php:<br />
<br />
$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name}'),['token_name'=>$token_id]);<br />
<br />
Now if you don't like raw log containing id instead of name but want name, and want substitution, you can use another parameter as id. The problem with that,<br />
it will work at first, but if you reload game using F5 you will loose your additional parameters, why? Because when game reloads it does not actually send same<br />
notifications, it sends special "hitstorical_log" notification where all parameters not listed in the "log" are removed. There is a hack (feature) to circumvent that,<br />
called recursive parameters. I.e. you can send stuff like this:<br />
<br />
$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name_rec}'),<br />
['token_name_rec'=>['log'=>'${token_name}',<br />
'args'=> ['token_name'=>clienttranslate('Boo'), 'token_id'=>$token_id, 'i18n'=>['token_name'] ]<br />
]<br />
]);<br />
<br />
and in format_log_recursive<br />
var key = 'token_name';<br />
if (typeof args[key] == 'string' && typeof args['token_id'] == 'string') {<br />
args[key] = this.getTokenDiv('token_id', args); <br />
}<br />
<br />
==== Alternative way ====<br />
<br />
Here is an example of what was done for Terra Mystica which is maybe not as good, but is more simple and straightforward:<br />
<br />
<pre><br />
//Define the proper message<br />
$message = clienttranslate('${player_name} gets ${power_income} via Structures');<br />
if ($price > 0) {<br />
self::DbQuery("UPDATE player SET player_score = player_score - $price WHERE player_id = $player_id");<br />
$message = clienttranslate('${player_name} pays ${vp_price} and gets ${power_income} via Structures');<br />
}<br />
<br />
// Notify<br />
self::notifyAllPlayers( "powerViaStructures", $message, array(<br />
'i18n' => array( ),<br />
'player_id' => $player_id,<br />
'player_name' => self::getUniqueValueFromDb( "SELECT player_name FROM player WHERE player_id = $player_id" ),<br />
'power_tokens' => $power_tokens,<br />
'vp_price' => self::getLogsVPAmount($price),<br />
'power_income' => self::getLogsPowerAmount($power_income),<br />
'newScore' => self::getUniqueValueFromDb( "SELECT player_score FROM player WHERE player_id = $player_id" ),<br />
'counters' => $this->getGameCounters(null),<br />
) );<br />
</pre><br />
<br />
With some functions to have the needed html added inside the substitution variable, such as:<br />
<br />
<pre><br />
function getLogsPowerAmount( $amount ) <br />
{<br />
return "<div class='tmlogs_icon' title='Power'><div class='power_amount'>$amount</div></div>";<br />
}<br />
</pre><br />
<br />
== Game Model and Database design ==<br />
<br />
<br />
=== Database for The euro game ===<br />
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.<br />
<br />
[[File:Madeira board.png]]<br />
<br />
<br />
Now lets try to map it, we have<br />
* (meeple,zone)<br />
* (die, zone, sideup)<br />
* (resource cube/money token/vp token,player home zone)<br />
* (token, player home zone, flip state)<br />
We can notice that resource and money are uncountable, and don't need to be track individually so we can replace our mapping to<br />
* (resource type/money,player home zone, count)<br />
And vp stored already for us in player table, so we can remove it from that list.<br />
<br />
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.<br />
<br />
So the piece mapping for non-grid based games can be in most case represented by (string: token_key, string: location, int: 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].<br />
<br />
Variant 1: Minimalistic<br />
<br />
CREATE TABLE IF NOT EXISTS `token` (<br />
`token_key` varchar(32) NOT NULL,<br />
`token_location` varchar(32) NOT NULL,<br />
`token_state` int(10),<br />
PRIMARY KEY (`token_key`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
<br />
<br />
{| class="wikitable"<br />
|+token<br />
! token_key<br />
! token_location<br />
! token_state<br />
|-<br />
|meeple_red_1<br />
|home_red<br />
|0<br />
|-<br />
|dice_black_2<br />
|board_guard<br />
|1<br />
|-<br />
|dice_green_1<br />
|board_action_mayor<br />
|3<br />
|-<br />
|bread<br />
|home_red<br />
|5<br />
|}<br />
<br />
Now how we represent resource counters such as bread?<br />
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.<br />
<br />
{| class="wikitable"<br />
|+token<br />
! token_key<br />
! token_location<br />
! token_state<br />
|-<br />
|bread_ff0000<br />
|tableau_ff0000<br />
|5<br />
|}<br />
<br />
<br />
<br />
Variant 2: Additional resource table, resource count for each player id<br />
<br />
CREATE TABLE IF NOT EXISTS `resource` (<br />
`player_id` int(10) unsigned NOT NULL,<br />
`resource_key` varchar(32) NOT NULL,<br />
`resource_count` int(10) signed NOT NULL,<br />
PRIMARY KEY (`player_id`,`resource_key`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
<br />
ALTER TABLE resource ADD CONSTRAINT fk_player_id FOREIGN KEY (player_id) REFERENCES player(player_id);<br />
<br />
{| class="wikitable"<br />
|+resource<br />
! player_id<br />
! resource_key<br />
! resource_count<br />
|-<br />
|123456<br />
|bread<br />
|5<br />
|}<br />
<br />
<br />
<br />
Variant 3: More normalised<br />
<br />
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). <br />
<br />
CREATE TABLE IF NOT EXISTS `token` (<br />
`token_id` int(10) unsigned NOT NULL AUTO_INCREMENT,<br />
`token_type` varchar(16) NOT NULL,<br />
`token_arg` int(11) NOT NULL,<br />
`token_location` varchar(32) NOT NULL,<br />
`token_state` int(10),<br />
PRIMARY KEY (`token_id`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
<br />
{| class="wikitable"<br />
|+token<br />
! token_id<br />
! token_type<br />
! token_arg<br />
! token_location<br />
! token_state<br />
|-<br />
|22<br />
|meeple<br />
|123456<br />
|home_123456<br />
|0<br />
|-<br />
|23<br />
|dice<br />
|2<br />
|board_guard<br />
|1<br />
|-<br />
|26<br />
|dice<br />
|1<br />
|board_action_mayor<br />
|3<br />
|-<br />
|49<br />
|bread<br />
|0<br />
|home_123456<br />
|5<br />
|}<br />
<br />
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<br />
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 <br />
cheat, the down side of that you cannot understand it either, and handcraft db states for debugging or testing.<br />
<br />
=== Database for The card game ===<br />
<br />
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.<br />
We have to design database for such game.<br />
<br />
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.<br />
<br />
* 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)<br />
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either<br />
* 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.<br />
<br />
Lets see what we have for that:<br />
* The card state is very simple, its usually "face up/face down", "tapped/untapped", "right side up/up side down"<br />
* 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.<br />
* 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<br />
* Now for mapping we should consider what information changes and what information is static, later is always candidate for material file<br />
* For dynamic information we should try to reduce amount of fields we need<br />
** we need at least a field for card, so its one<br />
** we need to know what zone cards belong to, its 2<br />
** 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<br />
* 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<br />
<br />
Variant 1: Minimalistic<br />
<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `card` (<br />
`card_key` varchar(32) unsigned NOT NULL,<br />
`card_location` varchar(32) NOT NULL,<br />
`card_state` int(11) NOT NULL,<br />
PRIMARY KEY (`card_id`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;<br />
</pre><br />
<br />
<br />
Variant 2: More normalised<br />
<br />
This version supported by Deck php class, so unless you want to rewrite db access layer go with this one<br />
<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `card` (<br />
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,<br />
`card_type` varchar(16) NOT NULL,<br />
`card_type_arg` int(11) NOT NULL,<br />
`card_location` varchar(16) NOT NULL,<br />
`card_location_arg` int(11) NOT NULL,<br />
PRIMARY KEY (`card_id`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;<br />
</pre><br />
<br />
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>)<br />
<br />
== Assorted Stuff ==<br />
<br />
=== Multi Step Interactions: Select Worker/Place Worker - Using Client States ===<br />
<br />
'''Ingredients:''' ggg.js<br />
<br />
I don't think its documented feature but there is a way to do client-only states, which is absolutely wonderful for few reasons<br />
* When player iteration is two step process, such as select worker, place worker, or place worker, pick one of two resources of your choice<br />
* When multi-step process can result of impossible situation and has to be undone (by rules)<br />
* 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)<br />
<br />
So lets do Select Worker/Place Worker<br />
<br />
Define your server state as usual, i.e. playerMainTurn -> "You must pick up a worker".<br />
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:<br />
* Have a handler for onUpdateActionButtons for playerMainTurn to activate all possible workers he can pick<br />
* When player clicks workers, remember the worker in one of the members of the main class, I usually use one called this.clientStateArgs.<br />
* Transition to new client state<br />
onWorker: function(e) {<br />
var id = event.currentTarget.id;<br />
dojo.stopEvent(event);<br />
... // do validity checks<br />
this.clientStateArgs.worker_id = id;<br />
this.setClientState("client_playerPicksLocation", {<br />
descriptionmyturn : "${you} must select location",<br />
});<br />
}<br />
* Have a handler for onUpdateActionButtons for client_playerPicksLocation to activate all possible locations this worker can go AND add Cancel button (see below)<br />
* Have a location handler which will eventually send a server request, using stored this.clientStateArgs.worker_id as worker id<br />
* 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<br />
<br />
<br />
if (this.isCurrentPlayerActive()) {<br />
if (this.on_client_state && !$('button_cancel')) {<br />
this.addActionButton('button_cancel', _('Cancel'), dojo.hitch(this, function() {<br />
this.restoreServerGameState();<br />
}));<br />
}<br />
} <br />
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)<br />
<br />
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.<br />
<br />
Code is available here [https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js sharedcode.js] (its using playerTurnPlayCubes and client_selectCubeLocation).<br />
<br />
<br />
=== Multi Step Interactions: Action Stack - Using Client States ===<br />
<br />
'''Ingredients:''' ggg.js, ggg.game.php, material.inc.php<br />
<br />
* We have euro game where game actions consist of series of mini-actions, which can be triggered by multiple sources<br />
* Example: Russian RailRoads have multiple source of actions, such as worker slots, triggered advantages, triggered factory rewards, etc. Each of the consist of series of small action, such as "advance black rail + advance marker", once you start executing it, more mini-actions are triggered and added to the stack (in case of RRR its not a stack but a random access list but whatever)<br />
* Implementing such game with server states is rather difficult because <br />
** it require lots of states<br />
** require stack on the state machine to support return to the state we originated substate from<br />
** series can result in invalid game state (i.e. not allowed by rules), which it hard to roll back over multiple states<br />
** without undo it would be rather frustrating for the player, and undo is hard to implement<br />
<br />
So this is how to implemented it using action stack and client states<br />
<br />
Encode all mini-actions as identifier or a letter, I use letters personally<br />
<br />
For each action, trigger, etc, define a "rules" of that game element using mini-action encoding and store in material.inc.php so both server and client have access to it, no need to store it in database, rules are not going to change<br />
during the game.<br />
<br />
'''material.inc.php:'''<br />
<br />
$this->token_types = array(<br />
...<br />
'slot_action_14' => array(<br />
'name' => clienttranslate("Industry Advancement"),<br />
'rules'=>"i",<br />
),<br />
'slot_action_15' => array(<br />
'name' => clienttranslate("2 Industry Advancements"),<br />
'rules'=>"ii",<br />
),<br />
'slot_action_16' => array(<br />
'name' => clienttranslate("Industry and Black Track Advancement"),<br />
'rules'=>"ib",<br />
),<br />
);<br />
<br />
<br />
In game.php you send this to client<br />
'''ggg.game.php:'''<br />
protected function getAllDatas() {<br />
...<br />
// this is material fields<br />
$result ['token_types'] = $this->token_types;<br />
...<br />
}<br />
<br />
In .js when client selects original action, you read this field and push actions into stack, something like<br />
<br />
this.pushOperations(this.gamedatas.token_types[action_id].rules);<br />
this.processAction();<br />
<br />
And processAction() will allow user to deal with possible actions. If this is truly a stack you could have done something like<br />
processAction: function() {<br />
var op = this.popOperation();<br />
switch (op) {<br />
case 'i': <br />
this.setClientState("client_playerTurnSelectAdvantageToken", {<br />
descriptionmyturn : "${you} must select industry marker to move",<br />
});<br />
break;<br />
...<br />
}<br />
}<br />
In Russian Railroads its unordered list, so it has to offer user all possible choices driven by current unprocessed operations, then determine what operation was that from the list based on what they clicked, i.e.<br />
<br />
onMoveable : function(event) {<br />
...<br />
else if (id.startsWith('ind')) {<br />
if (!this.commitOperation('i', id, place_id)) return;<br />
}<br />
this.gamedatas_local.tokens[id] = place_id; // alter local model<br />
this.placeToken(id, place_id); // client side animation<br />
if (this.checkAchievementMoveable(new_state, old_state, id)) { // that will check if something is triggered, so we can push more stuff on the stack<br />
this.processAction();<br />
}<br />
}<br />
During client states data is collected and pushed into client array of performed operations, we also do client side animation and alter model, since we don't send intermediate steps to server.<br />
<br />
In example above we check if we client on industry marker, we will "commit" "i" operation with selected id of the marker and place_id. The commit is just pushing this data into an array.<br />
<br />
All this operations later are send to server, usually when user clicks Done. <br />
The data will be encoded for server to read into a string, i.e. i__ind2__indslot15, means move industry marker number 2 into slot 15 of industry track. And multiple operations <br />
can be separated by a space for example.<br />
<br />
At anytime during client states user can click Cancel which will restore last server state and undo all client animation back to last stored state.<br />
<br />
The only disadvantage of this method is you have to implement a lot of functionality two times - on server and client.</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Studio_logs&diff=4042
Studio logs
2020-04-15T21:16:18Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
BGA Studio logs are available directly from your game development interface.<br />
<br />
Logs allows you to check out what happened recently on server and to debug your game.<br />
<br />
== BGA request&SQL logs ==<br />
<br />
This log is useful:<br />
* When you want to check what SQL requests has been built during a request.<br />
* When you want to debug your PHP code using "self::trace"<br />
* When you want to know why a request takes too many time.<br />
<br />
<br />
On this log, you can see:<br />
<br />
=== Your requests ===<br />
<br />
Example:<br />
<br />
20/06 21:50:56 [info] [T403] [4/mytest0] /cinco/cinco/exchange4Cards.html?id=4&lock=97d1c7a1-903a-4d1f-8206-de39ce8204fc&table=403&testuser=4&dojo.preventCache=1371757856044<br />
<br />
Note that the best way to check your Ajax request is to read the [[http://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#Input.2FOutput_debugging_section Input/Output section]].<br />
<br />
=== Request responses ===<br />
<br />
Example:<br />
<br />
20/06 21:50:56 [notice] [T403] [4/mytest0] OK-0 169 d141 c8 e0 I9 A158 V0 T0 /cinco/cinco/exchange4Cards.html?id=4&lock=97d1c7a1-903a-4d1f-8206-de39ce8204fc&table=403&testuser=4&dojo.preventCache=1371757856044<br />
<br />
You can recognize a response because it contains [notice]. Usually, there is one response for each request.<br />
<br />
Let's details the beginning of the log:<br />
* 20/06 21:50:56: the date<br />
* [notice]<br />
* [T403]: this is a log from table 403<br />
* [4/mytest0]: this is use "mytest0", with id 4<br />
* OK-0: it means that the request ended up successfully, with no exception (expected or unexpected).<br />
* 169: this is the time taken to process the request (169ms).<br />
* d141: this is the total Database time used to process the request (141ms).<br />
<br />
=== SQL requests ===<br />
<br />
Example:<br />
20/06 21:50:56 [info] [T403] [4/mytest0] 0.26 SELECT player_tokenColor FROM player WHERE player_id ='4'<br />
<br />
All requests to Database are traced in this log. You can see here the time take by the request (0,26ms).<br />
<br />
=== Custom trace ===<br />
<br />
You can use special PHP methods in your PHP code to left some trace in this log:<br />
* self::trace( "your message here" ); // Display "your message here" in the log<br />
* self::dump( "My variable", $variable_to_dump ); // Display the content of $variable_to_dump in the log<br />
<br />
== BGA unexpected exceptions logs ==<br />
<br />
In this log you can check the last Unexpected exceptions from your game.<br />
<br />
Exceptions management on PHP side [[http://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Managing_errors_and_exceptions is described here]].<br />
<br />
The log displayed the complete stacktrace of the exception, so you can debug it.<br />
<br />
The SQL log is very verbose and sometimes it too hard to extract your tracing from it, in this case you can use error log for tracing temporarily.<br />
You can add debug statement using self::warn() which will appear in that the log. Do not leave these tracing method calls after you done debugging unless they<br />
are real warnings or errors (only the error log level will appear in production).</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Practical_debugging&diff=4041
Practical debugging
2020-04-15T21:16:07Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This page gives you practical tips to debug your game during development. Don't hesitate to share your difficulties with us so that we can improve this section.<br />
<br />
== Tools ==<br />
<br />
To work on BGA Studio, we recommend that you use [http://www.google.com/chrome Google Chrome] as it's currently the fastest browser for the BGA platform, and it's available for all OSes.<br />
<br />
Another reason to use Chrome is that it embeds all the tools you need to work on BGA Studio. You can see them by pressing "F12" or from the menu ("Tools > Development tools").<br />
<br />
A good practice is to use a second browser to develop the game, in order to verify that your game is working fine on this browser too.<br />
<br />
To debug with Firefox browser, we advise you to use these 2 extensions:<br />
* [https://addons.mozilla.org/firefox/addon/firebug/ Firebug]<br />
* [https://addons.mozilla.org/firefox/addon/web-developer/ Web developer]<br />
<br />
To debug with other browsers (IE, Edge, Opera), we advise you to use one of the most recent versions. Latest versions of the browser will likely have better development tools than the previous ones...<br />
<br />
== General tip for debugging ==<br />
<br />
In general for debugging, think of using the '[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]] state' functionality. It enables you to save the state of your game just before the issue you are investigating, then come back to that point with one click as many times as needed to understand what is going wrong.<br />
<br />
You can save up to 3 different states.<br />
<br />
== Debugging my game when it cannot start ==<br />
<br />
If your game won't start because of an error, you are probably in one of these situations:<br />
* There is a SQL error in your dbmodel.sql file.<br />
* You have a syntax error in your PHP file.<br />
* Your PHP "setup" - or any method used during the game initial states - generates an exception.<br />
<br />
If the error is not explicitly displayed when you click on "Express start", you should check the "Gameserver error log" as per [[Studio logs]].<br />
More cases of why game can't start are described on the [[Troubleshooting]] page.<br />
<br />
== Debugging my PHP game logic (or my view) ==<br />
<br />
Most of the time, debugging PHP is quite easy. Here's what I do when I want to develop/debug some game logic that is triggered by some game action:<br />
<br />
* At first, I make sure that I can reproduce the needed game situation with one click. To do this, I use the "[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]]" function.<br />
* Another possibility for this is to place a '''die('ok');''' PHP statement right after the PHP I am developing/debugging. This way, I make sure that every request will fail and then nothing will be committed to the database.<br />
* Then, I use the '''var_dump''' function to dump PHP variables and check what's wrong, until it works.<br />
<br />
Example:<br />
<pre><br />
<br />
// (...my code to debug)<br />
<br />
var_dump( $my_variable );<br />
die('ok');<br />
<br />
// (...my code to debug)<br />
<br />
</pre><br />
<br />
=== Add traces to your code ===<br />
<br />
You can use the following functions in your game to add server side logging:<br />
<br />
'''self::dump( 'name_of_variable', $variable );''' // dump variable, like var_dump but in the log debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]<br />
<br />
'''self::debug( $message );''' // debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]<br />
<br />
'''self::trace( $message );''' // info level logging, goes to [[Studio_logs|BGA request&SQL logs]]<br />
<br />
'''self::warn( $message );''' // warning level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]<br />
<br />
'''self::error( $message );''' // error level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]<br />
<br />
Check [[Studio logs]] for more details on how to access your logs.<br />
<br />
This can be useful when you need to follow the flow of your code and not just stop it to see how it goes at some point.<br />
<br />
Only the error log level will appear in production. This level should be used only for critical problems. <br />
Other levels will show only in the development environment and can be used as you see fit.<br />
<br />
== Debugging my HTML/CSS layout ==<br />
<br />
Example situations<br />
<br />
* Why doesn't my game element show up in the interface?<br />
* Why hasn't my CSS property been applied to this element?<br />
* Why is this game element displayed at this position?<br />
<br />
A useful tip when an element does not show up in the interface is to give it a red background:<br />
<pre><br />
#my_element {<br />
... some CSS definitions ...<br />
background-color: red;<br />
}<br />
</pre><br />
<br />
This way, you know if the element is not visible because of some CSS property or because of something else.<br />
<br />
Another tip: sometimes, changing a CSS property has no visible effect on your interface. In that case, add a "display:none" property. If your element does not disappear, the bug probably comes from your CSS selector and not from your CSS property.<br />
<br />
Using Chrome "Elements" tab (the first one), you can:<br />
* See the CURRENT HTML of your page. Remember that the classical "show page source" is inefficient with BGA as you are modifying the page source with your Javascript code.<br />
* Using the "magnifying glass", you can click on any part of your game interface and check its HTML code and associated CSS styles.<br />
* You can even modify directly some CSS properties and see how it looks immediately in the game interface.<br />
<br />
=== Debugging my Javascript game interface logic ===<br />
<br />
Compared to PHP debugging, Javascript debugging can sometimes be painful.<br />
<br />
Here are some tips to make your life easier while developing and debugging Javascript:<br />
<br />
=== Do complex things on the PHP side ===<br />
<br />
The most frequent case is the following: you want to compute possible moves in a game situation. Doing it in Javascript is a nightmare. Do it in PHP, and transfer the results to your client interface using the "args" game state property.<br />
<br />
Note: See the Reversi tutorial for an example.<br />
<br />
=== Add traces in your code ===<br />
<br />
You can use the following:<br />
<br />
'''console.log( variable_to_inspect )'''<br />
<br />
It will give you the object structure of the variable in the Javascript console, without blocking the execution.<br />
<br />
It's often a good idea to precede this call with a console.log( '### HERE ###' ); to find more easily the appropriate line in the console log.<br />
<br />
'''alert( variable_to_inspect )'''<br />
<br />
It will popup what you wish and pause the execution until you click ok.<br />
<br />
This won't be useful for complex structures; only native types will be plainly displayed. But this is sometimes useful just with messages to make sure which way the execution goes.<br />
<br />
=== Use Browser Debugger (e.g. Chrome) ===<br />
<br />
Modern browsers also allow you to put breakpoints in your js code. <br />
<br />
This will stop code execution on that line and will launch the JavaScript debugger.<br />
<br />
In Chrome, to add a breakpoint: add a line to your .js file<br />
<br />
<pre>debugger; </pre><br />
<br />
Refresh the page F5, and make sure you have the Developer tools window open, press F12. <br />
When the break-point is hit you can then step through your code and visualise variables, etc.<br />
<br />
== Online format checkers ==<br />
Copy and paste code for a quick code sanity check like the right number of brackets.<br />
<br />
PHP: [https://phpcodechecker.com/ https://phpcodechecker.com/]<br />
<br />
JS: [http://esprima.org/demo/validate.html http://esprima.org/demo/validate.html]<br />
<br />
== Some frequent errors ==<br />
<br />
See [[Troubleshooting]].<br />
<br />
== Get the database matching a bug report ==<br />
<br />
When a player creates a bug report in production, a snapshot of the game database is taken. You can get access to this snapshot from the studio by following the steps below:<br />
* Create a table in the studio with the same game and number of players as the table for which the report has been written. Launch this table.<br />
* Open another tab on the studio and go to "Manage game" page for your project (you have to be admin for this project)<br />
* In the "Errors in production" section, fill up the fields "Bug report ID" (this is the ID of the bug report in production) and "Studio table ID" (this is the ID of the table you created above) then click the "⇨ Load bug report state into this table save slot #1" button.<br />
* If the snapshot is correctly retrieved, you see a "Done!" message.<br />
* Go back to the tab with your studio table and click "Load 1".<br />
* The page refreshes automatically and is broken. This is normal, as the player ids from the snapshot are the player ids of the production, not those of the studio. We'll need to update them.<br />
** '''Important note:''' if you see a "Done!" message but clicking "Load 1" doesn't bring any change, it's that the snapshot is unfortunately not available (most likely because the bug report was declared too long after the game ended and the database had already been garbage collected to reclaim space).<br />
* Click on the "Go to game database" button<br />
* For each table using player_ids, you'll need to update the player_ids from the production to use the player_ids from the studio. You can see the player_ids from the table page before entering the game by hovering over the player names.<br />
* Tables to update:<br />
** player<br />
** global (value with ID 2 is the active player)<br />
** stats<br />
** tables specific to your schema that use player_ids<br />
* If your changes to player_ids are not taken into account, it may be a cache problem: use the "Clear PHP cache" button on your "Manage game" page.<br />
* Then you should be able to play with the same state of the game as when the report was created in production.<br />
* If the game has ended, you can place it again in the game state you want to debug by setting the value with ID 1 in the global table to the appropriate state value, and the value with ID 2 to the player you want active).<br />
*<br />
* Below is an example php function you may want to make. You can call this function from the chat window: LoadDebug() <br />
* change instances of 2308257, and 2308258 to you own BGA Studio logins YourLogin0 and YourLogin1<br />
* change $id0 and $id1 to the player_ids from the table you want to debug, and have recently imported.<br />
<br />
<pre><br />
public function LoadDebug()<br />
{<br />
<br />
// These are the id's from the BGAtable I need to debug.<br />
$id0 = '85268563';<br />
$id1 = '85278138'; <br />
<br />
//player<br />
self::DbQuery("UPDATE player SET player_id=2308257 WHERE player_id = '" . $id0 . "'" );<br />
self::DbQuery("UPDATE player SET player_id=2308258 WHERE player_id = '" . $id1 . "'" );<br />
<br />
//global <br />
self::DbQuery("UPDATE global SET global_value=2308257 WHERE global_value = '" . $id0 . "'" );<br />
self::DbQuery("UPDATE global SET global_value=2308258 WHERE global_value = '" . $id1 . "'" );<br />
<br />
//stats<br />
self::DbQuery("UPDATE stats SET stats_player_id=2308257 WHERE stats_player_id = '" . $id0 . "'" );<br />
self::DbQuery("UPDATE stats SET stats_player_id=2308258 WHERE stats_player_id = '" . $id1 . "'" ); <br />
<br />
// 'other' game specific tables. example:<br />
// tables specific to your schema that use player_ids<br />
self::DbQuery("UPDATE card SET card_location_arg=2308257 WHERE card_location_arg = '" . $id0 . "'" );<br />
self::DbQuery("UPDATE card SET card_location_arg=2308258 WHERE card_location_arg = '" . $id1 . "'" );<br />
}<br />
</pre></div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Tools_and_tips_of_BGA_Studio&diff=4040
Tools and tips of BGA Studio
2020-04-15T21:15:58Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
== Server Tools and Tips ==<br />
=== Starting a game in one click ===<br />
<br />
To start a game:<br />
* Create a new table with your game.<br />
* If you want to play a game with 3 players, specify that you want a maximum of 3 players at this table.<br />
* Click on "Express Start".<br />
<br />
=== Stopping a game in one click ===<br />
<br />
* Click on the "quit" icon on the top right of the screen.<br />
* Click on "Express Stop".<br />
<br />
=== Switching between users ===<br />
<br />
When running a game on Studio, you can use the little red arrow near each player's name to open a new tab with this player's perspective.<br />
<br />
=== Access to game database and Logs ===<br />
<br />
At the bottom of the game area, there is section without a title containing 3 useful links:<br />
<br />
Go to game database • BGA request&SQL logs • BGA unexpected exceptions logs<br />
<br />
* "Go to game database" link is an immediate access to the PhpMyAdmin tool to view/edit the tables of the current game<br />
* BGA request&SQL logs - link to your studio PHP log - all tables, all severities. Anything you print using debugging and tracing functions from PHP and some framework logs<br />
* BGA unexpected exceptions logs - same log as above but only severity warning and higher<br />
<br />
See [[Practical debugging]] for more info about it.<br />
<br />
=== Save & restore state ===<br />
<br />
Using links of this section, you can save the complete current (database) state of your game, then restore it later.<br />
<br />
This is particularly useful when you want to develop a part of the game that is difficult to reproduce: you just have to save the situation just before, and then restore it until this part works fine.<br />
<br />
We provide you 3 "slots": 1, 2 and 3. This way, you can save 3 different game situations.<br />
<br />
Limits:<br />
* the "restore" function does not work anymore when the game is over.<br />
* a saved situation from a given table cannot be restored in another table.<br />
* when you "restore" a situation, the current browser page is refreshed to reflect the updated game situation, but you have to refresh you other tabs/pages manually.<br />
<br />
=== Input/Output debugging section ===<br />
<br />
This section shows you:<br />
* The AJAX calls made by your game interface to the game server. AJAX calls (outputs) begins with ">"<br />
* The notifications received by your game interface. Notifications (inputs) begins with "<".<br />
<br />
Note: if you click on some notification title, you can resend it immediately to the user interface.<br />
<br />
<br />
=== Run PHP functions from the chat ===<br />
<br />
On BGA Studio, you can directly run a PHP method from the table chat.<br />
<br />
For example, if on your PHP you have this method:<br />
<br />
function giveMoneyToPlayer($player_id, $amount) { ... }<br />
<br />
You can call this method directly from the chat like this: <br />
<br />
giveMoneyToPlayer(2564,2)<br />
<br />
Note: this is not a real php statement, you cannot use self::, you cannot use ";" at the end and you cannot use quotes,<br />
if you need to pass a string skip the quotes, like this<br />
<br />
giveToActivePlayer(money,2)<br />
<br />
=== Stopping Hanging Game ===<br />
<br />
If game is hanging and you cannot enter it to stop you can type this URL (replace 12345 with your table number),<br />
which should bring you to a place where you can stop it without entering:<br />
<br />
<nowiki>http://en.studio.boardgamearena.com/#!table?table=12345</nowiki><br />
<br />
<br />
== Desktop and Web Tools ==<br />
=== Code Editors and IDEs ===<br />
==== Eclipse For PHP Developers ====<br />
<br />
Eclipse PHP package can be starting point for development you need. You may also want to <br />
install Tern JS plugins to understand dojo style JS. All desktops.<br />
https://projects.eclipse.org/projects/tools.pdt<br />
<br />
==== Visual Studio Code ====<br />
<br />
Microsoft Visual Studio Code is light weight IDE/Editor. All desktops.<br />
https://code.visualstudio.com<br />
<br />
==== Gedit (Ubuntu) ====<br />
'''Edit TPL'''<br />
To edit TPL with HTML code highlightings in Gedit under Ubuntu:<br />
<br />
find gtksourceview directory in /usr/share, depending on your version (2.0, 3.0,...).<br />
<br><br />
Here it's 3.0, then type in a terminal window:<br />
<pre><br />
sudo gedit /usr/share/gtksourceview-3.0/language-specs/html.lang<br />
</pre><br />
<br />
then find 'globs' section, and change:<br />
<br />
<pre><br />
<property name="globs">*.html;*.htm;*.tpl</property><br />
</pre><br />
<br />
=== File Sync ===<br />
<br />
==== File Sync on Windows ====<br />
<br />
Install [http://winscp.net/ WinSCP]. Map a remote directory to a local one and enable continuous sync (one way). You need SFTP password you get when you registered dev account.<br />
<br />
==== File Sync on Linux ====<br />
<br />
* Option 1 - Nautilus (file manager)<br />
You can just use Nautilus "connect to a server" function with URL sftp://1.studio.boardgamearena.com<br />
Then you'll get a mounted local folder mapping your studio folder and you can use any editor you like without further need for sync. Downside - if connection goes down you cannot work on source code, no local copy.<br />
<br />
* Option 2 - sftp and rsync<br />
<br />
<pre><br />
<br />
#!/bin/bash<br />
BASEDIR=`dirname $0`<br />
REMOTE=$BASEDIR/remote<br />
LOCAL=$BASEDIR/workspace<br />
GAME=mygamenamehere<br />
<br />
#mount remote<br />
fusermount -u $REMOTE #this unmounts dir<br />
echo LongDevPassword | sshfs -o password_stdin myusernamehere@1.studio.boardgamearena.com: $REMOTE<br />
<br />
<br />
#this starts auto-sync from local to remote mount<br />
killall lsyncd<br />
lsyncd -delay 1 -rsync $LOCAL/$GAME/ $REMOTE/$GAME<br />
<br />
</pre><br />
<br />
This can be able run on startup, so you don't have to do anything manually. However sshfs is not very stable you<br />
have to kill and restart it sometimes. And remote goes away sometimes due to connection issues with studio. <br />
In this case its handy to have a local copy, which is what lsyncd for.<br />
<br />
You can also sync on demand (from a build script or editor command) using<br />
rsync -vlrt $LOCAL/$GAME/ $REMOTE/$GAME<br />
<br />
==== File Sync using VSCode ====<br />
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<br />
<br />
* '''Install this extension''' https://marketplace.visualstudio.com/items?itemName=liximomo.sftp (File->Preferences->Extensions ... type SFTP and Install)<br />
<br />
* '''Open VSCode on an empty folder''' that will be the local root of your project.<br />
<br />
* 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<br />
<br />
* '''Update the json''' as below: <br />
<br />
<pre><br />
{<br />
"name": "BGA",<br />
"host": "1.studio.boardgamearena.com",<br />
"protocol": "sftp",<br />
"port": 22,<br />
"username": "<your SFTP username>",<br />
"password": "<your SFTP password>",<br />
"remotePath": "/<your project name>/",<br />
"uploadOnSave": true,<br />
"ignore": [<br />
".vscode",<br />
".git",<br />
".DS_Store"<br />
]<br />
}<br />
</pre><br />
<br />
- 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"'''.<br />
<br />
This will download all the files locally, and each time you modify/save a file in VSCode, it will upload it to the SFTP Server.<br />
<br />
=== Debuggers ===<br />
<br />
Browser is the best tool for JS/HTML5 debugging, see [[Practical debugging]] for details.<br />
<br />
=== Version Control ===<br />
Studio providers svn for you code on server, there are some limited abilities there to see history and restore. I recommend to keep your code in another repository. I suggest to use git with local repo, which you can sync to cloud or backup.<br />
Other option is to host source code on github, if you do use this convention github.com/<yourname>/bga-<yourgame>. In such case make sure you don't post high-res publisher graphics only web resources, and post a separate license for graphics files.<br />
<br />
=== PHP CLI ===<br />
Its handy to have php cli (command line) tools install to run php locally, so you can test some stuff without deployment cycle, or create some scripts that generate code or markup.<br />
<br />
=== Image Manipulation ===<br />
==== ImageMagick ====<br />
Handy set of image manipulation '''command line''' tools, useful to for example to stitch together bunch of images and re-size, to use as sprite (in Stock component for example). I.e. you got a graphics file from publisher where every tile is 600x600 PNG file in separate file. You want .jpg instead of .png to make it not like 20Mb, and combine all images in one column and re-size to 128x128:<br />
<br />
(Linux example)<br />
/usr/bin/montage `ls Tiles*.png` -tile 1 -geometry 128x128+0+0 out/tiles128.jpg<br />
<br />
https://www.imagemagick.org/script/download.php<br />
<br />
==== Gimp ====<br />
<br />
GUI tool, very complex but will do ALL what you possibly need to do with game graphics<br />
<br />
https://www.gimp.org/<br />
<br />
==== Shrinking ====<br />
<br />
Shrink images without loss of quality https://tinypng.com/ or http://www.iloveimg.com/ <br />
<br />
==== PDF Scrabber ====<br />
<br />
PDF Scraper - extract images from PDF file (i.e. game rulebook) - http://www.extractpdf.com/<br />
<br />
==== Rename/Copy project ====<br />
<br />
There is a script available in sharedcode project to do the renaming which can be called in command line if you have php command line installed.<br />
You need to have php clt (command line interface) installed, then you can download script and run it.<br />
<br />
https://github.com/elaskavaia/bga-sharedcode/blob/master/tools/bgaprojectrename.php<br />
<br />
Usage:<br />
php bgaprojectrename.php <originalProjectPath> <copyOfProjectRenamedPath><br />
<br />
Example on how to call it in command line if you project name is "heartsmyproject"<br />
<br />
php7.0 git/bga-sharedcode/tools/bgaprojectrename.php remote/hearts/ remote/heartsmyproject/<br />
<br />
==== BGA Workbench ====<br />
<br />
PHP library providing tools to help manage BGA Studio projects including deployment and test utilities. https://github.com/danielholmes/bga-workbench<br />
<br />
== Client Tips ==<br />
<br />
=== Speed up game re-loading by disabling Input/Output debug section ===<br />
<br />
Development UI have few sections for debugging only, such as 'Input/Output debugging section'. Loading this data will significantly slow down<br />
your reload. I did some profiling and my reloading (i.e. F5) took 14 seconds, 12 of which it was dealing with loading this section. <br />
If you not using it you can disable it. In your JavaScript code, in the begging of 'setup' method add this code<br />
<br />
dojo.destroy('debug_output');<br />
<br />
That should get rid of this section and overhead associated with loading it (it may have some other side-effects, I have not explored all of them)<br />
<br />
=== Speed up CSS development and layout ===<br />
<br />
Syncing files to server and refreshing is relative fast but still can take up to 20 seconds which is annoying.<br />
If you working<br />
a lot on css/images/layout you can speed it up by coping html in some state of the game to your local folder.<br />
I.e. in your project folder create directory misc/ and save your html as misc/test.html and changing path to css to load from local disk (and it will load your images to from local disk as well). <br />
I.e. find something like<br />
<br />
<link rel="stylesheet" type="text/css" href="http://1.studio.boardgamearena.com:8081/data/themereleases/151226-1240/games/mygame/999999-9999/mygame.css"/><br />
<br />
and replace with<br />
<link rel="stylesheet" type="text/css" href="../mygame.css"/><br />
<br />
You project structure will look like this<br />
<br />
mygame<br />
img/ <-- your images<br />
mygame.css <-- your original css<br />
...<br />
misc/<br />
test.html <-- your test html<br />
<br />
It is a bit tricky to save html exact state, if you do save as it also pulls all resources sometimes.</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Create_a_game_in_BGA_Studio:_Complete_Walkthrough&diff=4039
Create a game in BGA Studio: Complete Walkthrough
2020-04-15T21:15:46Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
== Introduction ==<br />
<br />
This document is not a tutorial, but step by step instructions on how to build your own first game adaptation using BGA Studio framework.<br />
<br />
Before you read this material, you must:<br />
* Read the overall presentations of the BGA [[Studio]].<br />
* Some-what know the languages used by BGA Studio: PHP, SQL, HTML, CSS, Javascript<br />
* Setup you development environment [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]<br />
* Create a game using one of the available tutorials. Don't bother with a new game if you have not completed at least one of the tutorials.<br />
<br />
<br />
If you stuck or have questions about this page post on [https://forum.boardgamearena.com/viewforum.php?f=12 BGA Developers forum].<br />
If you uncomfortable posting on public forum you can send message directly to developers who post answers on that forum but NOT the BGA admins.<br />
If you find typos in this wiki - fix it.<br />
<br />
== Select a First Game ==<br />
<br />
For your first '''real''' game you must either<br />
* Select a game from [http://en.studio.boardgamearena.com/#!page/availablelicences Available Licenses]<br />
* Or from the Public Domain<br />
<br />
But what if the game you want is not there? If you are able to successfully publish your first game, you would gain the trust of the BGA admins and they will be happy to assist you in obtaining a license for game you really want to do or you can request a license yourself. You can read more about game licenses on [[BGA Game licences]] page.<br />
<br />
Once you selected the game but before creating a new project, please takes few seconds to check that someone is not already developing this game. If it is the case, maybe you can propose to join the project?<br />
<br />
[http://en.studio.boardgamearena.com/#!projects Check the list of current projects]<br />
<br />
Even if you see few projects with name of the game they may not be active. There are a lot abandoned game projects. If its not clear by the status, post to Developers forum as ask if anybody actively working on the project, and at the same time ask admins on the same forum post to send you graphics for that game if they have it (yeah on the forum, there is better chance of them seeing your post on the forum then in email).<br />
<br />
If you goal was to fix bugs in existing project, you have to ask on forum to get access to it, projects developed by bga admins are not in the studio.<br />
<br />
If you want to take over existing project first ask on forum to see if project is abandoned, then get read only access (via project list) and see if this worth using it, if it has no code or graphics just start from the scratch, don't worry about project name it can be renamed later<br />
<br />
== Create a project ==<br />
<br />
If you have not already, you have to create a project in BGA Studio for this game. If the original game name is taken use gamenameYOURINITIALS<br />
template, i.e."heartsla". Don't worry too much about the name, if game would be good enough to be publish it will be renamed to original name. <br />
<br />
Find and start the game in turn based mode, make sure it works.<br />
<br />
Second, modify the text in .tpl file, reload the page in the browser and make sure your ftp sync works as expected.<br />
Note: if you have not setup [http://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#File_Sync FTP auto-sync] yet, do it now, manually copying files is a no-starter.<br />
<br />
Update your project status in [http://en.studio.boardgamearena.com/#!studio Control Panel > Manage games] page, you can say "development started" or "waiting for license" or "waiting for graphics" or combination of those.<br />
<br />
<br />
<br />
== Development Tools ==<br />
<br />
At some point you need to setup your development environment which consist of multiple tools, such as<br />
* Editor or IDE<br />
* Browser with dev tools<br />
* File sync tools<br />
* BGA Web tools<br />
* Image manipulation tools<br />
* Version control tools<br />
<br />
Please scan though articles from [[Studio#BGA_Studio_user_guide]] especially related to debugging and tools, there is a lot of useful info there.<br />
<br />
== Hook version control system ==<br />
<br />
If its a real game I would commit the code to version control right at start. You going to find yourself in the situation<br />
when game does not even start anymore and no way of debugging it unless you have a way to revert. That is where version control becomes very handy.<br />
If you don't know what I am talking about then at least back-up your files after each of major steps. Starting now.<br />
You can also create a project on github, but make sure you don't commit original publisher graphics files.<br />
You can (and should) also commit your modification periodically via studio's control panel.<br />
<br />
== Obtain game graphics ==<br />
<br />
If you developing a game from Available Licenses games, ask the admins to send you graphics, but don't rely on that. It will likely fail. But if you posted on forum and waiting for an answer you can proceed to next step - project creation.<br />
<br />
If you don't get original graphics you go to '''Scavenger Hunt'''<br />
<br />
* If you developing a public domain card game you can borrow standard cards graphics from hearts project (see [[Tutorial hearts]]).<br />
* Standard game pieces - meeples, cubes, dice can be found here https://github.com/elaskavaia/bga-sharedcode/tree/master/img<br />
* Go to boardgamegeek.com find your game and obtain 3D game box image, 2D box image, and if you lucky they also sometime have boards and token scans in "Game Pieces" section of Images<br />
* If that fail google "boardgame <name>" and check Images section<br />
* Get the rules PDF as well, there tools that allows you to extract graphics from PDF, which usually good for meeples, cubes and such<br />
<br />
Once you get the graphics one way or another you have to massage it to fit in the BGA criteria, which usually involves<br />
* If publisher sends graphics in one token/card per file mode, you have to stitch them in sprite and scale down<br />
* For non square tiles and game pieces you need transparency<br />
* Usually you chop off scoring "ring" around the board of the game since scoring track not needed for online adaptation<br />
<br />
More details about graphics requirements can be found here [[Game art: img directory]].<br />
<br />
[[File:Rrr_search.png]]<br />
<br />
== Obtain game documentation ==<br />
<br />
Also at this time obtain a electronic copy of rules, such as PDF (English version). <br />
<br />
Also grab any other documents you may find on boardgamegeek such as FAQ, additional Reference books, and user created assistant documents, such<br />
as cheat-sheets (may be easier to get a data from these then trying to scrub pdf). You create and place them in the doc/ folder of the project then<br />
exclude them from version control. There is also a misc/ folder now but it will hold up to 1 Mb of data files which would be checked in, so rules pdf's may not fit there.<br />
<br />
<br />
== Update game infos and box graphics ==<br />
<br />
Even it does not nothing yet start with making sure game looks descent in the game selector, meaning it has nice box graphics and information is correct. <br />
<br />
For that we need to edit [[Game_meta-information: gameinfos.inc.php|gameinfos.inc.php]].<br />
What you would do for real game you would go to http://boardgamegeek.com find the game and use the information from web-site to fill the gameinfos.<br />
<br />
<br />
The next step is to replace game_box.png with proper images, usually you can find all images including publisher logo on boardgamegeek website.<br />
<br />
Details about images can be found here: [[Game art: img directory]].<br />
<br />
Now important step. You have to LOAD these files in studio website through control panel. So go to Control Panel -> Manager Games -> YOURPROJECT<br />
and press Reload for 'Reload game informations' and 'Reload game box image'<br />
<br />
[[File:Gamepanel_sharedcode.png]]<br />
<br />
Now try to start the game again. If you some-how introduced a syntax error in gameinfos file it may not actually work (game won't start).<br />
Always use "Express Start" button to start the game. You should see a standard state prompt from template. You should see X players on the right, testdude0 .. testdudeX-1.<br />
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!<br />
<br />
== Fix source copyright ==<br />
<br />
Now since you have your own project, you want put your name in the copyright header, so replace<br />
<br />
© <Your name here> <Your email address here><br />
with<br />
© John Snow <jsnow@gameofthrones.com><br />
<br />
Well not exactly this but whatever your real name is. For all files in project directory, its about 10 files. Make sure project still starts after that :)<br />
<br />
== Create Initial Layout and Game Graphics ==<br />
<br />
Mentally it is easier to start with game layout and graphics pieces. Even when nothing is working its give your moral satisfaction!<br />
<br />
There are few ways of how html could have been generated, you could have started with nothing and generate<br />
all by java script. Or you could have started with complete game markup in html and make java script just hide and move pieces around. BGA framework provides also a third way which is mix of both plus template engine to generate HTML using php. The only thing is really annoying about template engine is<br />
that you cannot put any translatable strings in the template (which means any visible text at all), if you using template approach all stings have to extracted as variables and injected through php (.view.php). This page explains template engine in great details:[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl|Template Engine]].<br />
<br />
The other disadvantages of template engine is you cannot run and debug it locally, in the begging of development its a lot faster run off local pages, <br />
you can do it with some trickery described here [[Tools_and_tips_of_BGA_Studio#Speed_up_CSS_development_and_layout|Tools and Tips for BGA Studio]]<br />
<br />
During this step you have to decide what technical solutions you will be using, such as<br />
* Use inline positioning of all moving pieces, controlled by JS. There are few classes already exists in Studio to help with that (see [[Studio#Game_interface_.28Client_side.29|Game Interface - Client Side]]). OR use html/css layout engine to position pieces (my personal choice).<br />
* Use BGA template engine OR create all ui elements by JS OR manually write or generate complete html markup. The game usually contain 200-300 pieces, it seems wrong but actually its faster to type all of this up in html/css then trying write then debug code for page generator.<br />
Static HTML markup also means you have to use players color or abstracted player number (such as red is 1, blue is 2) not player id's anywhere in JS, since player id is dynamic by nature.<br />
<br />
So at this stage you should complete the following:<br />
* Create an layout of the game, with positioning of main board, player areas, zones, other supporting areas, etc<br />
* Create css and html snippets for all game pieces: boards, tokens, meeples, etc. Place them all in initial template (even if they not suppose to be visible at start). I.e. create fake player's hand with cards, put meeples on the board<br />
* Hook layout to number of players and colors picked by the game and test with multiple players<br />
* Figure out what you want to display in mini-player boards and hook it up<br />
<br />
If at this time you don't have graphics yet create pieces with just css, you can use shape, background color and object text using css ::after construct to fake the pieces.<br />
<br />
One of the greatest part about the web is all client side code can be viewed in your browser, so if you wondering how something is done in another BGA game just load the page and spy on it! In Chrome that would be right click "Inspect Element". That would immediately show html of the given element alongside with css used for it (on the right). Another great way to learn was introduced recently is you can add yourself to any BGA project as read only from the project page!<br />
<br />
[[File:Injected_text.png]]<br />
<br />
== Hook Input and Animation ==<br />
<br />
This step can be done before or after some of the server steps, or you go in iterations switching back and forward until you get it done, up to you.<br />
<br />
At this time you want to hook clicking on pieces and buttons and provide some reaction, such of moving a piece. The handler code will be replaced later by the server hook, but at the begging you want you game to be alive as early as possible. <br />
<br />
Usually all pieces will be hooked to onclick during JS "setup" method, in addition if you create elements during server notification they have to be hooked up at that time.<br />
<br />
You can play with animation effects you want put in place, in general all the pieces that move in real game should be moving, such as meeples, resources tokens/cubes, cards, vp tokens. <br />
Regular piece animation is provided by BGA framework, but if you use html layout positioning not inline positioning you have to remove absolute positions (inline position styling) after each move. The set of functions for relative position token animation can found in https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js <br />
<br />
Also its a good idea to give player a visual cues on what game elements are clickable now, usually it will be a style, such as "active_slot", with visual effect of white dashed outline (outline is better then border, because border changes will make piece slightly move since it changes the size) or box-shadow (i.e. neon glow)<br />
<br />
If you read [http://www.slideshare.net/boardgamearena/bga-studio-guidelines BGA developers guidelines] you know that you should not get carried away with animation, you creating a board game not a video game... That also applies to sound effects (you should not use any sounds effects beside already provided by framework).<br />
<br />
See [[Game_interface_logic:_yourgamename.js#Players_input|Player's Input]] and [[Game_interface_logic:_yourgamename.js#Access_and_manipulate_the_DOM|Animation and DOM Manipulation]] for JS reference.<br />
<br />
== Create Database Schema ==<br />
<br />
At some point you have to design your game database. Do it sooner then later since it would be harder to change it later, since some<br />
code decisions would be based on that.<br />
<br />
If you have grid-based abstract game use template from reversi, if you have a card game use template from hearts (the cards one also commented out in generated template for your project). The cards database goes with php class called [[Deck]].<br />
<br />
In general make it as simple as possible. <br />
Think about it, your game has 300 pieces (likely less). Using database to store this amount of data is like shooting a mosquito with a tank.<br />
Anything more complex then one table with 5 columns or two tables will only going to make it harder to develop and not improve performance.<br />
You can forget about normalising and any fancy stuff you learn about databases in school. String field for a primary key would be as fast as integer when we talking about this size of data. So don't over-optimize with trying to have integers field that have state based on bitmask!<br />
<br />
Also remember that static (non dynamic) information about the game does not need to be stored in the database, that all include everything that does not change, i.e<br />
all token/card properties such as name, tooltips, "strength", color, etc. This is stored in material.inc.php and server has access to it from anywhere, as well as client<br />
if you send it with getAllDatas(). The only reason store some of it in database if it can affect your queries (i.e. type of token).<br />
<br />
Usually design process will contain the following steps:<br />
* Design game model - model that represent your game in progress, such as at any given step you can restore the game from that model<br />
* Mapping - now map real game to that model<br />
* Encoding - now represent this model in database and material file with reasonable amount of fields<br />
<br />
Example: '''The card game'''<br />
<br />
* 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<br />
* 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 as part of state machine step)<br />
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either<br />
* The only thing you need in your database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.<br />
* The card state is very simple, its usually "face up/face down", "tapped/untapped", "right side up/up side down"<br />
* As position go we never need real 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 itself usually static or irrelevant.<br />
* 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<br />
* Now for mapping we should consider what info changes and what info is static, static info is always candidate for material file or html<br />
* For dynamic stuff we should try to reduce amount of fields we need, i.e. we need a field for card, so its one, we need to know what zone cards belong to, its 2, and we have possible few other fields, but 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<br />
* 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<br />
<br />
You can also use cards database schema and [[Deck]] implementation for most purposes (even you not dealing with cards).<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `card` (<br />
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,<br />
`card_type` varchar(16) NOT NULL,<br />
`card_type_arg` int(11) NOT NULL,<br />
`card_location` varchar(16) NOT NULL,<br />
`card_location_arg` int(11) NOT NULL,<br />
PRIMARY KEY (`card_id`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;<br />
</pre><br />
<br />
Another Example: '''The euro game'''<br />
<br />
See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]<br />
<br />
<br />
So the piece mapping for non-grid based <br />
games can be in most case represented by (string: token_key, string: location, int: state), example of such database schema can be found here:<br />
[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 tokens.php].<br />
<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `token` (<br />
`token_key` varchar(32) NOT NULL,<br />
`token_location` varchar(32) NOT NULL,<br />
`token_state` int(10),<br />
PRIMARY KEY (`token_key`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
</pre><br />
<br />
<br />
<br />
See [[Game database model: dbmodel.sql]] for details about editing the file.<br />
<br />
== Implement Game Setup ==<br />
<br />
Once you have your database schema you can do a proper game setup. Usually you open rulebook on the "Game Setup" page<br />
and implement these step by step populating the database (using db access API).<br />
Game initialization is performed in php method setupNewGame, this method is called once when game table is created.<br />
Game notifications cannot be sent during this time.<br />
<br />
== Implement One time game model synchronisation ==<br />
<br />
<br />
Now at any point in the game we need to make sure that database information can be reflected back in UI, so we fix getAllDatas function<br />
to return all possible data we need to reconstruct the game. The template for getAllDatas already taking care of player info, but you <br />
have to alter it to return all other data from database visible to the "current" player.<br />
<br />
After that on the client side we should display this data, so in your .js file in setup function (which is the receiver of getAllDatas) you add calls that handle data send by server, usually by calling animation function such as "placeToken" or "placeCard".<br />
<br />
== Create State Machine ==<br />
<br />
Now you need to create a game state machine. <br />
<br />
The state handling spread across 4 files, so you have to make sure all pieces are connected together.<br />
The state machine states.php defines all the states, and function handlers on php side in a form of string,<br />
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.<br />
<br />
Please fist watch this again [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine BGA game state machine]<br />
and then please read [[Your game state machine: states.inc.php]]<br />
<br />
Now the state machine should be relatively simple, if you find yourself with machine with more than 10 states its probably not the way to go.<br />
Not all the player interactions need separate states, a lot of things can be implemented directly on client, i.e. if your player need to select<br />
a reward token, which offers choice of resource, instead of two states on server just have one state on server and possible few states on client (client side states)<br />
to collect this info.<br />
<br />
== Implement Notification handling ==<br />
<br />
Now to implement things for real we have hook UI actions to ajax calls, and process notifications send by server.<br />
So previously we hooked onclick js handler right to client animation, in real game its a two<br />
step operation. When user clicks on something, client sends an ajax call to server, server processes it and updates database, server sends<br />
notification in response, client hooks animations to server notification. See [[Game_interface_logic:_yourgamename.js#Notifications|JS Notifications]].<br />
<br />
Exception to this is client states, if you need to process two step user interaction such as select meeple, place meeple, you may want <br />
to avoid sending data to server until step is complete (which may involve direct client side animation).<br />
<br />
Part of the sending notifications would be to update player's scoring, BGA uses standard control for score (on JS side), see [[Game_interface_logic:_yourgamename.js#Update_players_score|Update Player's Score]].<br />
<br />
<br />
== Wrap Up ==<br />
<br />
<br />
* Implement game progression (getGameProgression() in php)<br />
* Implement Zombie turn (zombieTurn() in php)<br />
* Define and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)<br />
* The games logs should explain what happened if player was not looking<br />
* You need to implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data<br />
* Make sure all UI strings are marked for translation<br />
* UI elements which are images (i.e. tokens, cards) should have tooltips<br />
<br />
<br />
When you think you game is completely working there is still bunch of stuff you have to do/check before telling admin that game is ready, please go though this [[Pre-release checklist]].</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Tutorial_hearts&diff=4038
Tutorial hearts
2020-04-15T21:15:23Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
== Introduction ==<br />
<br />
Using this tutorial, you can build a complete working game on the BGA environment: Hearts.<br />
<br />
Before you read this tutorial, you must:<br />
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).<br />
* Know the rules for Hearts<br />
* Some-what know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript<br />
* Setup you development environment [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]<br />
* As part of setup you have to have access to your ftp home folder in studio, which would have 'hearts' game source code. We will be using some resources of this game in this tutorial, so copy it over to local disk if you have not done so.<br />
<br />
If you stuck of have question about this tutorial post on [https://forum.boardgamearena.com/viewforum.php?f=12 BGA Developers forum]<br />
<br />
== Create your first game ==<br />
<br />
If you have not already, you have to create a project in BGA Studio. For this tutorial you can create a project heartsYOURNAME where<br />
YOURNAME is your developer login name. You can also re-use the project you have created for the "First Steps" tutorial above.<br />
With the initial skeleton of code provided, you can already start a game from the BGA Studio. <br />
<br />
1. Find and start the game in turn-based mode with 4 players. Make sure it works. <br />
<br />
2. Modify the text in heartsYOURNAME_heartsYOURNAME.tpl, reload the page in the browser and make sure your ftp sync works as expected.<br />
Note: if you have not setup auto-sync do it now, manually copying files is a no-starter.<br />
<br />
3. Express stop from settings menu (the gear icon).<br />
<br />
<i>Note: please do '''not''' use the hearts project code as a base. This tutorial assumes you started with a TEMPLATE project with no prior modifications. Using the hearts project as a base will be very confusing and you won't be able to follow all the steps.<br />
</i><br />
<br />
== Hook version control system ==<br />
<br />
For a real game, or even for this tutorial, we recommend committing the code to version control right from the start. You are going to find yourself in a situation where the game doesn't even start anymore and no way of debugging it, unless you have a way to revert. That is where version control becomes very handy. If you are not familiar with version control (e.g. [https://git-scm.com/docs/gittutorial git]) then at least back up your files after each major change. Start now.<br />
<br />
Code for this tutorial available is on github: https://github.com/elaskavaia/bga-heartsla<br />
<br />
Different revisions represent different steps along the process, starting from original template to a complete game.<br />
<br />
== Update game infos and box graphics ==<br />
<br />
Even it does not nothing yet, always start by making sure the game looks decent in the game selector, meaning it has nice box graphics and its information is correct. For that we need to edit [[Game_meta-information: gameinfos.inc.php|gameinfos.inc.php]].<br />
<br />
For a real game, you would go to [http://boardgamegeek.com BoardGameGeek], find the game, and use the information from BGG to fill in the gameinfos.<br />
<br />
So let's do that. Find "hearts" on BoardGameGeek. (Hint: Original release 1850 :))<br />
<br />
You can fill in the year of publishing and bgg id, put ''Public Domain'' under publisher, and a publisher id of 171 for public domain. And as designer and author you can just put your own name just for fun. Set number of players to 4.<br />
<br />
// Players configuration that can be played (ex: 2 to 4 players)<br />
'players' => array( 4 ), <br />
<br />
<br />
The next step is to replace '''game_box.png''' with nicer images. For this tutorial, just copy all the files from the img/ folder of the hearts/ template into the img/ directory of your project. Replace publisher.png with a nicer image: for example https://github.com/elaskavaia/bga-sharedcode/blob/master/img/publisher.png.<br />
<br />
Details about images can be found here: [[Game art: img directory]].<br />
<br />
Now an important step: you have to LOAD these files into the Studio website through the control panel. So go to Control Panel -> Manage Games -> heartsYOURNAME<br />
and press Reload for 'Reload game informations' and 'Reload game box image'<br />
<br />
Now try to start the game again. If you somehow introduced a syntax error in the gameinfos file it may not work (the game won't start).<br />
Always use the "Express Start" button to start the game. You should see a standard state prompt from the template. You should see 4 players on the right: testdude0 .. testdude3.<br />
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!<br />
<br />
<br />
<i>Note: if you had run the game before with less than 4 players there is a bug that will prevent you from running it with 4 only (if you did not run it before or run it with 4 players as instructed stop reading this note), to workaround revert back to original players array (i.e. 1,2,3,4), reload game options, then create a table with 4 players, exit that game table, then change gameoptions to 4 only as above, reload game options, create table again.</i><br />
<br />
Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/4b3a73eeb5acae961ade18473af119e8ce8d1a8f]<br />
<br />
== Layout and Graphics ==<br />
<br />
In this section we will do graphics of the game, and main layout of the game.<br />
<br />
First copy a sprite with cards image from hearts img/cards.jpg into img/ folder of your project. Project hearts is mounted to your home directory on bga server.<br />
<br />
Edit .tpl to add some divs to represent player table and hand area<br />
<br />
<pre><br />
<div id="myhand_wrap" class="whiteblock"><br />
<h3>My Hand</h3><br />
<div id="myhand"><br />
</div><br />
</div><br />
</pre><br />
<br />
If you refresh you should see now white area with My Hand title.<br />
<br />
<br />
[[File:Heartsla-tpl2.png]]<br />
<br />
Now lets add a card into the hand, just so you can feel it. Edit .tpl and a playertablecard div inside a hand div<br />
<pre><br />
...<br />
<div id="myhand"><br />
<div class="playertablecard"></div><br />
</div><br />
...<br />
</pre><br />
<br />
Edit .css file<br />
<pre><br />
.playertablecard {<br />
display: inline-block;<br />
position: relative;<br />
margin-top: 5px;<br />
width: 72px;<br />
height: 96px;<br />
background-image: url('img/cards.jpg'); /* temp hack to see it */<br />
}<br />
</pre><br />
<br />
When you edit CSS remember that you have to FORCE-reload page, i.e. Ctrl-F5, otherwise its cached.<br />
<i>Same when you change existing graphics files</i>.<br />
<br />
You should see this:<br />
<br />
[[File:Heartsla-tpl3.png]]<br />
<br />
Awesome! Now lets do the rest of layout.<br />
<br />
There are few ways of how html could have been generated, you could have start with nothing and generate<br />
all by java script. Or you could have started with complete game markup in html and make java script just hide and move pieces around. BGA framework provides also a third way which is mix of both plus template engine to generate HTML using php. So lets do that.<br />
<br />
Change .tpl file to have this inside<br />
<pre><br />
<div id="playertables"><br />
<br />
<!-- BEGIN player --><br />
<div class="playertable whiteblock playertable_{DIR}"><br />
<div class="playertablename" style="color:#{PLAYER_COLOR}"><br />
{PLAYER_NAME}<br />
</div><br />
<div class="playertablecard" id="playertablecard_{PLAYER_ID}"><br />
</div><br />
</div><br />
<!-- END player --><br />
<br />
</div><br />
<br />
<div id="myhand_wrap" class="whiteblock"><br />
<h3>{MY_HAND}</h3><br />
<div id="myhand"><br />
</div><br />
</div><br />
</pre><br />
<br />
What we did is we added "block" player, it is marked up using html comments. {VAR} notation is used<br />
to inject variables and <br />
<pre><br />
<!-- BEGIN xxx --> <br />
inside <br />
<!-- END xxx --> <br />
</pre><br />
effectively allows us to do template loops.<br />
<br />
In .view.php insert this code after 'Place your code below' comment<br />
<br />
<br />
<pre><br />
$template = self::getGameName() . "_" . self::getGameName();<br />
<br />
$directions = array( 'S', 'W', 'N', 'E' );<br />
<br />
// this will inflate our player block with actual players data<br />
$this->page->begin_block($template, "player");<br />
foreach ( $players as $player_id => $info ) {<br />
$dir = array_shift($directions);<br />
$this->page->insert_block("player", array ("PLAYER_ID" => $player_id,<br />
"PLAYER_NAME" => $players [$player_id] ['player_name'],<br />
"PLAYER_COLOR" => $players [$player_id] ['player_color'],<br />
"DIR" => $dir ));<br />
}<br />
// this will make our My Hand text translatable<br />
$this->tpl['MY_HAND'] = self::_("My hand");<br />
</pre><br />
<br />
What it does is for each player we have it will replicate the html between <!-- BEGIN player --> and <!-- END player --> tags, substituting the variable denoted by {XXX}<br />
with the values you provide. The DIR variable in this case we pulling from directions array (where array_shift will take first element and remove it from the array).<br />
<br />
Reload. If everything went well you should see this:<br />
<br />
[[File:Heartsla-tpl4.png]]<br />
<br />
These are "tableau" areas for 4 players plus My hand visible only to one player.<br />
They not exactly how we wanted them to be because we did not edit .css yet.<br />
<br />
Now edit .css, add these lines after import before our previous definition<br />
<br />
<pre><br />
/** Table layout **/<br />
<br />
#playertables {<br />
position: relative;<br />
width: 710px;<br />
height: 340px;<br />
}<br />
<br />
.playertablename {<br />
font-weight: bold;<br />
}<br />
<br />
.playertable {<br />
position: absolute;<br />
text-align: center;<br />
width: 180px;<br />
height: 130px;<br />
}<br />
<br />
.playertable_N {<br />
left: 50%;<br />
top: 0px;<br />
margin-left: -90px; /* half of 180 */<br />
}<br />
.playertable_S {<br />
left: 50%;<br />
bottom: 0px;<br />
margin-left: -90px; /* half of 180 */<br />
}<br />
.playertable_W {<br />
left: 0px;<br />
top: 50%;<br />
margin-top: -55px; /* half of 130 */<br />
}<br />
.playertable_E {<br />
right: 0px;<br />
top: 50%;<br />
margin-top: -55px; /* half of 130 */<br />
}<br />
</pre><br />
<br />
<br />
Now you force Reload and you should see this:<br />
[[File:Heartsla-tpl5.png]]<br />
<br />
This is almost all we need for graphics and layout, there are few tweaks left there but lets do some more heavy lifting now.<br />
<br />
<i>Note: if you did not see changes you may have not force reloaded, force means you use Ctrl+F5 or Cltr+Shift-R, if you don't "force" browser will use cached version of .css and images! Which is not what you just changed</i><br />
<br />
<br />
<i>Another Note: In general if you have auto-sync you don't need to reload if you change game.php file, you need normal reload if you change js, and force reload for css and images. If you changed state machine or database you likely need to restart the game.</i><br />
<br />
== Game Interface JS Stock ==<br />
<br />
The BGA framework provides a few out of the box classes to deal with cards. The client side<br />
contains a class called [[Stock]] and it can be used for any dynamic html "pieces" management that uses<br />
common sprite images. On the server side we will use the [[Deck]] class which we discuss later.<br />
<br />
If you open cards.jpg in an image viewer you will see that it is a "sprite" image - a 13x4 grid of images stitched together,<br />
which is a very efficient way to transport images. So we will use the Stock class to mark up these images and create<br />
"card" divs for us.<br />
<br />
First, we need to add '''ebg/stock''' as a dependency in the hearts.js file:<br />
<pre><br />
define([<br />
"dojo","dojo/_base/declare",<br />
"ebg/core/gamegui",<br />
"ebg/counter",<br />
"ebg/stock" /// <==== HERE<br />
],<br />
</pre><br />
<br />
Then add this to the Javascript contructor, this will define size of our cards<br />
<pre><br />
console.log('hearts constructor');<br />
this.cardwidth = 72;<br />
this.cardheight = 96;<br />
</pre><br />
<br />
The stock is initialized in the Javascript "setup" method like this:<br />
<pre><br />
// TODO: Set up your game interface here, according to "gamedatas"<br />
<br />
// Player hand<br />
this.playerHand = new ebg.stock(); // new stock object for hand<br />
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );<br />
</pre><br />
<br />
As parameters of the "create" method, we provided the width/height of an item (a card), and the container div "myhand" - which is an id of "div" element from our .tpl file representing a player hand.<br />
<br />
<br />
Then, we must tell the stock what items it is going to display during its life: the 52 cards of a standard card game from a CSS sprite image named "cards.jpg" with all the cards arranged in 4 rows and 13 columns.<br />
<br />
Here's how we tell stock what item types to display:<br />
<pre><br />
this.playerHand.image_items_per_row = 13; // 13 images per row<br />
<br />
<br />
// Create cards types:<br />
for (var color = 1; color <= 4; color++) {<br />
for (var value = 2; value <= 14; value++) {<br />
// Build card type id<br />
var card_type_id = this.getCardUniqueId(color, value);<br />
this.playerHand.addItemType(card_type_id, card_type_id, g_gamethemeurl + 'img/cards.jpg', card_type_id);<br />
}<br />
}<br />
</pre><br />
<br />
And add this function to the utilities section<br />
<pre><br />
// Get card unique identifier based on its color and value<br />
getCardUniqueId : function(color, value) {<br />
return (color - 1) * 13 + (value - 2);<br />
},<br />
</pre><br />
<br />
Explanations:<br />
* At first, we tell the stock component that our CSS sprite contains 13 items per row. This way, it can find the correct image for each card type id.<br />
* Then for the 4x13 cards, we call the '''addItemType''' method that creates the type. The arguments are the type id, the weight of the card (for sorting purpose), the URL of our CSS sprite, and the position of our card image in the CSS sprite. It happens to be the same number in our case.<br />
<br />
Note: we need to generate a unique ID for each type of card based on its color and value. For that we create a function '''getCardUniqueId'''. The type is the unique identifier of the TYPE of the card, e.g., the queen of spades encoded as an integer. If our deck had 2 standard card decks we would have had 2 queens of spades; they would share the same type and the same image but would have different ids. NOTE: It's unfortunate that they named this '''getCardUniqueId'''; it should have been '''getCardUniqueType''', because it really isn't an id, but a TYPE of card. The type of the item should either be a reversible function of its properties (i.e., kind of suite * 13 + value) or just an enumerator described in material.inc.php. In this specific case it's a synthetic type id, which also the same as the number of the card in the sprite image (i.e., if you enumerate each image in sprite going left to right, then top to bottom).<br />
<br />
Now let's add the 5 of Hearts to the player's hand just for fun (this code will go in setup method after types initialization):<br />
<br />
<pre><br />
// 2 = hearts, 5 is 5, and 42 is the card id, which normally would come from db<br />
this.playerHand.addToStockWithId( this.getCardUniqueId( 2, 5 ), 42 );<br />
</pre><br />
<br />
This will add the card with id 42 and type 16 ( (2-1)*13+(5-2)=16 ). <br />
<br />
Note that number 16 would not be something you can see in database, Deck database will have separate field for type and type_arg where type is suite and type_arg is number, so its not the same thing, but you can use same formula to convert. Number 42 on the other hand would be id field in database. But we get to database in the later section.<br />
<br />
If you reload now you should see the 5 of hearts in "your hand".<br />
<br />
Stock control can handle clicking on items and forms the selection. yyou can immediately react to selection<br />
or you can query it later; for example when user presses some other button.<br />
<br />
Lets hook it up. Add this in the setup method in .js file, after this.playerHand is initialised:<br />
<br />
dojo.connect( this.playerHand, 'onChangeSelection', this, 'onPlayerHandSelectionChanged' );<br />
<br />
<br />
Then find the Player's action comment section and add a handler after the comment:<br />
<br />
<pre><br />
onPlayerHandSelectionChanged : function() {<br />
var items = this.playerHand.getSelectedItems();<br />
<br />
if (items.length > 0) {<br />
if (this.checkAction('playCard', true)) {<br />
// Can play a card<br />
<br />
var card_id = items[0].id;<br />
console.log("on playCard "+card_id);<br />
<br />
this.playerHand.unselectAll();<br />
} else if (this.checkAction('giveCards')) {<br />
// Can give cards => let the player select some cards<br />
} else {<br />
this.playerHand.unselectAll();<br />
}<br />
}<br />
},<br />
</pre><br />
<br />
The function name of the handler is 4th parameter of the dojo.connect function. Make sure you spell it correctly or there will be unpredictable effects.<br />
<br />
Now if you reload, open the Javascript Console (F12), and then click on the card in My Hand, you should see:<br />
on playCard 42<br />
printed on the console<br />
<br />
== Game Database and Game Initialisation ==<br />
<br />
Next step, you want to design a game database and setup a new game (on the server side).<br />
For that we need to a) modify the database schema to add our cards data b) add some global variables into<br />
the existing globals table.<br />
<br />
To modify the schema, first exit your existing game(s). Open '''dbmodel.sql''' file and uncomment the card table creation.<br />
<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `card` (<br />
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,<br />
`card_type` varchar(16) NOT NULL,<br />
`card_type_arg` int(11) NOT NULL,<br />
`card_location` varchar(16) NOT NULL,<br />
`card_location_arg` int(11) NOT NULL,<br />
PRIMARY KEY (`card_id`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;<br />
</pre><br />
<br />
This is the "card" table which will be managed by the Deck php class.<br />
<br />
In addition we want a little piece of information in the players table:<br />
<br />
-- add info about first player<br />
ALTER TABLE `player` ADD `player_first` BOOLEAN NOT NULL DEFAULT '0';<br />
<br />
Not sure why they put this into the player table, as we could use a global db variable to hold first player as easily.<br />
But I am just following the existing code more-or-less.<br />
<br />
Next we finally get into .game.php class, where the main logic and db interaction would be. Find php constructor which should be <br />
function __construct( )<br />
This is first function in a file. Add this code to constructor.<br />
<pre><br />
parent::__construct();<br />
self::initGameStateLabels( array( <br />
"currentHandType" => 10, <br />
"trickColor" => 11, <br />
"alreadyPlayedHearts" => 12,<br />
) );<br />
<br />
$this->cards = self::getNew( "module.common.deck" );<br />
$this->cards->init( "card" );<br />
</pre><br />
<br />
Here we are initializing three "Game State Variables" which are variables stored in the database. They are integers.<br />
It must start with no values lower then 10 since values lower than 10 are reserved. These values are stored by numeric ids<br />
in the database, but in the php we associate them with string labels for convenience of access. The variables are "trickColor": numbers from 1 to 4 that map to card suit (not sure why it's called color; maybe it's a translation from French); "alreadyPlayedHearts": a boolean flag (0 or 1) indicating hether somebody used hearts on the trick; "currentHandType": stores the value to indicate who to give cards to during exchange.<br />
<br />
The next 2 lines are creating $this->cards object and associating it with "card" table in the the database.<br />
<br />
<i>If we called db table 'foo' instead of 'card' the last statement would have been $this->cards->init( "foo" )</i><br />
<br />
<br />
At this point I would start a new game and make sure it starts, then exit. <br />
<br />
<i><br />
If you made a mistake<br />
in the .sql or php constructor the game won't start, and good luck debugging it. (That is why it's important to check<br />
once in a while to make sure it still starts while you remember what you have changed.)<br />
</i><br />
<br />
Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/e3a049257b592ff6167688d4d344f8a83d349b08]<br />
<br />
Now we can go to game initialization '''setupNewGame''' in game.php. This method is called once when the table is created.<br />
<br />
In your template project you should have code that deals with player table, just leave it as is. Start inserting the<br />
other code after "Start the game initialization" comment.<br />
<pre><br />
// Init global values with their initial values<br />
<br />
// Note: hand types: 0 = give 3 cards to player on the left<br />
// 1 = give 3 cards to player on the right<br />
// 2 = give 3 cards to player opposite<br />
// 3 = keep cards<br />
self::setGameStateInitialValue( 'currentHandType', 0 );<br />
<br />
// Set current trick color to zero (= no trick color)<br />
self::setGameStateInitialValue( 'trickColor', 0 );<br />
<br />
// Mark if we already played hearts during this hand<br />
self::setGameStateInitialValue( 'alreadyPlayedHearts', 0 );<br />
</pre><br />
<br />
Here we initialize all the globals to 0.<br />
<br />
Next is to create our cards in the database. We have one deck of cards so it's pretty simple.<br />
<pre><br />
// Create cards<br />
$cards = array ();<br />
foreach ( $this->colors as $color_id => $color ) {<br />
// spade, heart, diamond, club<br />
for ($value = 2; $value <= 14; $value ++) {<br />
// 2, 3, 4, ... K, A<br />
$cards [] = array ('type' => $color_id,'type_arg' => $value,'nbr' => 1 );<br />
}<br />
}<br />
<br />
$this->cards->createCards( $cards, 'deck' );<br />
</pre><br />
<br />
This code that will create one of each card. But don't run it yet, because we missing $this->colors.<br />
So we have state of the game in the database, but there is some static game information which never changes.<br />
This information should be stored in material.inc.php and this way it can be accessed from all .php files.<br />
We will edit this file now by adding these lines<br />
<br />
<pre><br />
$this->colors = array(<br />
1 => array( 'name' => clienttranslate('spade'),<br />
'nametr' => self::_('spade') ),<br />
2 => array( 'name' => clienttranslate('heart'),<br />
'nametr' => self::_('heart') ),<br />
3 => array( 'name' => clienttranslate('club'),<br />
'nametr' => self::_('club') ),<br />
4 => array( 'name' => clienttranslate('diamond'),<br />
'nametr' => self::_('diamond') )<br />
);<br />
<br />
$this->values_label = array(<br />
2 =>'2',<br />
3 => '3',<br />
4 => '4',<br />
5 => '5',<br />
6 => '6',<br />
7 => '7',<br />
8 => '8',<br />
9 => '9',<br />
10 => '10',<br />
11 => clienttranslate('J'),<br />
12 => clienttranslate('Q'),<br />
13 => clienttranslate('K'),<br />
14 => clienttranslate('A')<br />
);<br />
</pre><br />
<br />
Where $this->colors will define Suit labels and $this->values_label will define value labels.<br />
If you noticed, we have two of each label for suits. This is because sometimes we need translated values on the php<br />
side and sometimes we don't. In this case '''nametr''' will return a translated value in php, which is only useful when you throw exceptions to show the right strings. If you pass a value to the client via notification you should always use untranslated strings, and the client will translate it. 'clienttranslate' marks the value for translation but does not actually change it for php. For more about this wonderful translation stuff see [[Translations]].<br />
<br />
== Full game model synchronisation ==<br />
<br />
Now at any point in the game we need to make sure that database information can be reflected back in the UI, so we must fix the '''getAllDatas''' function<br />
to return all possible data we need to reconstruct the game. This is in the game.php file. The template for getAllDatas() already takes care of player info. Let's just<br />
add hand and tableau data before we return a result.<br />
<br />
<pre><br />
// Cards in player hand<br />
$result['hand'] = $this->cards->getCardsInLocation( 'hand', $current_player_id );<br />
<br />
// Cards played on the table<br />
$result['cardsontable'] = $this->cards->getCardsInLocation( 'cardsontable' );<br />
</pre><br />
<br />
Now on the client side we should display this data, so in your .js file in the setup function (which is the receiver of getAllDatas) replace our hack of putting 5 of Hearts directly into the hand with:<br />
<br />
<pre><br />
// Cards in player's hand<br />
for ( var i in this.gamedatas.hand) {<br />
var card = this.gamedatas.hand[i];<br />
var color = card.type;<br />
var value = card.type_arg;<br />
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);<br />
}<br />
<br />
// Cards played on table<br />
for (i in this.gamedatas.cardsontable) {<br />
var card = this.gamedatas.cardsontable[i];<br />
var color = card.type;<br />
var value = card.type_arg;<br />
var player_id = card.location_arg;<br />
this.playCardOnTable(player_id, color, value, card.id);<br />
}<br />
</pre><br />
<br />
This should show hand and tableau cards now, except we are missing the '''playCardOnTable''' function. So find the '''getCardUniqueId''' function which<br />
should be in the utilities section and add this after it:<br />
<br />
<pre><br />
playCardOnTable : function(player_id, color, value, card_id) {<br />
// player_id => direction<br />
dojo.place(this.format_block('jstpl_cardontable', {<br />
x : this.cardwidth * (value - 2),<br />
y : this.cardheight * (color - 1),<br />
player_id : player_id<br />
}), 'playertablecard_' + player_id);<br />
<br />
if (player_id != this.player_id) {<br />
// Some opponent played a card<br />
// Move card from player panel<br />
this.placeOnObject('cardontable_' + player_id, 'overall_player_board_' + player_id);<br />
} else {<br />
// You played a card. If it exists in your hand, move card from there and remove<br />
// corresponding item<br />
<br />
if ($('myhand_item_' + card_id)) {<br />
this.placeOnObject('cardontable_' + player_id, 'myhand_item_' + card_id);<br />
this.playerHand.removeFromStockById(card_id);<br />
}<br />
}<br />
<br />
// In any case: move it to its final destination<br />
this.slideToObject('cardontable_' + player_id, 'playertablecard_' + player_id).play();<br />
},<br />
</pre><br />
<br />
For this to work we also need to add a card template in the .tpl file<br />
<pre><br />
// Javascript HTML templates<br />
<br />
var jstpl_cardontable = '<div class="cardontable" id="cardontable_${player_id}" style="background-position:-${x}px -${y}px">\<br />
</div>';<br />
</pre><br />
<br />
<br />
What this does is basically create another card object, because if it is not our card it's not in our hand (Stock) so<br />
we have to create it out of thin air. The technique to do that is to implement a Javascript template object defined in the .tpl file with some<br />
parameters, which will basically create a "div" string (yes you could have used string concatenation but it would not be fancy).<br />
Now dojo.place places it (the div) on top of a placeholder. Now we have an object with an id of 'cardontable_' + player_id. Depending<br />
on who is playing it we either place it on the player miniboard or in hand (and remove it from hand stock). Then we animate the card move.<br />
<br />
We also should fix our .css file now to add style for cardontable and REMOVE background for playertablecard which really is a placeholder div and not a card. (Don't miss the remove step; it will be all screwy if you do!)<br />
<br />
<pre><br />
.playertablecard {<br />
display: inline-block;<br />
position: relative;<br />
margin-top: 5px;<br />
width: 72px;<br />
height: 96px;<br />
/* we remove background-image here */<br />
}<br />
<br />
/*** cards on table ***/<br />
<br />
.cardontable {<br />
position: absolute;<br />
width: 72px;<br />
height: 96px;<br />
background-image: url('img/cards.jpg'); <br />
}<br />
</pre><br />
<br />
Now to test that it actually works let's deal cards to players during game initialization:<br />
<br />
Add this after createCards in setupNewGame function in the game.php file<br />
<pre><br />
// Shuffle deck<br />
$this->cards->shuffle('deck');<br />
// Deal 13 cards to each players<br />
$players = self::loadPlayersBasicInfos();<br />
foreach ( $players as $player_id => $player ) {<br />
$cards = $this->cards->pickCards(13, 'deck', $player_id);<br />
} <br />
</pre><br />
<br />
Now when you start the game you should see 13 cards in your hand!<br />
<br />
We just need to hook-up clicking on card and test if our playCardOnTable works.<br />
<br />
Find onPlayerHandSelectionChanged function in the JS file, we should have logging there like console.log("on playCard "+card_id);<br />
So after that insert this:<br />
<pre><br />
console.log("on playCard "+card_id);<br />
// type is (color - 1) * 13 + (value - 2)<br />
var type = items[0].type;<br />
var color = Math.floor(type / 13) + 1;<br />
var value = type % 13 + 2;<br />
<br />
this.playCardOnTable(this.player_id,color,value,card_id);<br />
</pre><br />
Note: this code is for testing we will replace it with server interaction after we test it.<br />
<br />
Now if you force reload (because we changed .css before) you should be able to click on card from you have and see it moving,<br />
you can click on few cards this way. When you done enjoying the animation, press F5 to get your hand back.<br />
<br />
[[File:Heartsla-sync.png]]<br />
<br />
Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/01d4e2f595fd14c2adcc97a957d21bb2766f78a8]<br />
<br />
== State Machine ==<br />
<br />
Now we need to create a game state machine. So the states are:<br />
<br />
* Cards are dealt to all players (lets call it "newHand")<br />
* Player is selected who will start a new trick ("newTrick")<br />
* Player start or respond to played card ("playerTurn")<br />
* Game control is passed to next player or trick is ended ("nextPlayer")<br />
* End of hand processing (scoring and check for end of game) ("nextHand")<br />
<br />
In addition players can exchange cards so we need two more states for that but we will skip it for now.<br />
<br />
<br />
The state handling spread across 4 files, so you have to make sure all pieces are connected together.<br />
The state machine states.php defines all the states, and function handlers on php side in a form of string,<br />
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.<br />
<br />
So .states.php<br />
<br />
<pre><br />
$machinestates = array(<br />
<br />
// The initial state. Please do not modify.<br />
1 => array(<br />
"name" => "gameSetup",<br />
"description" => clienttranslate("Game setup"),<br />
"type" => "manager",<br />
"action" => "stGameSetup",<br />
"transitions" => array( "" => 20 )<br />
),<br />
<br />
<br />
/// New hand<br />
20 => array(<br />
"name" => "newHand",<br />
"description" => "",<br />
"type" => "game",<br />
"action" => "stNewHand",<br />
"updateGameProgression" => true, <br />
"transitions" => array( "" => 30 )<br />
), <br />
<br />
<br />
<br />
// Trick<br />
<br />
30 => array(<br />
"name" => "newTrick",<br />
"description" => "",<br />
"type" => "game",<br />
"action" => "stNewTrick",<br />
"transitions" => array( "" => 31 )<br />
), <br />
31 => array(<br />
"name" => "playerTurn",<br />
"description" => clienttranslate('${actplayer} must play a card'),<br />
"descriptionmyturn" => clienttranslate('${you} must play a card'),<br />
"type" => "activeplayer",<br />
"possibleactions" => array( "playCard" ),<br />
"transitions" => array( "playCard" => 32 )<br />
), <br />
32 => array(<br />
"name" => "nextPlayer",<br />
"description" => "",<br />
"type" => "game",<br />
"action" => "stNextPlayer",<br />
"transitions" => array( "nextPlayer" => 31, "nextTrick" => 30, "endHand" => 40 )<br />
), <br />
<br />
<br />
// End of the hand (scoring, etc...)<br />
40 => array(<br />
"name" => "endHand",<br />
"description" => "",<br />
"type" => "game",<br />
"action" => "stEndHand",<br />
"transitions" => array( "nextHand" => 20, "endGame" => 99 )<br />
), <br />
<br />
// Final state.<br />
// Please do not modify.<br />
99 => array(<br />
"name" => "gameEnd",<br />
"description" => clienttranslate("End of game"),<br />
"type" => "manager",<br />
"action" => "stGameEnd",<br />
"args" => "argGameEnd"<br />
)<br />
<br />
);<br />
</pre><br />
<br />
The full details about what these fields are you can find in [[Your_game_state_machine:_states.inc.php]].<br />
<br />
But basically we have Player states, in which human player has to perform an "action" by pressing some button in UI or selecting some game item, which will trigger js handler, which will do ajax call to server into API define <br />
by .action.php file. All functions in this file are API between client and server and has very simple<br />
and repetitive structure. In this case there is only two action player can do - play a card or pass cards to other player. So these 2 functions go into .action.php file, we will only define one now since we not implementing card passing states yet:<br />
<br />
<pre><br />
public function playCard() {<br />
self::setAjaxMode();<br />
$card_id = self::getArg("id", AT_posint, true);<br />
$this->game->playCard($card_id);<br />
self::ajaxResponse();<br />
}<br />
</pre><br />
<br />
<br />
Now to make it run we have define all handler functions that we referenced in states, which are - one function for state arguments argGiveCards, 4 functions for robot states (where game performs some action)<br />
and 1 function for player actions handling.<br />
Find 'Game state arguments' section and paste this in:<br />
<pre><br />
function argGiveCards() {<br />
return array ();<br />
}<br />
</pre><br />
<br />
This normally pass some parameters to states, but we don't need anything yet. It good to have placeholder there anyway, so we can fix it later.<br />
Important: even when its a stub this function must return array not scalar.<br />
<br />
Lets do stubs for other functions, find game state actions section in .game.php file and insert these<br />
<pre><br />
function stNewHand() {<br />
// Take back all cards (from any location => null) to deck<br />
$this->cards->moveAllCardsInLocation(null, "deck");<br />
$this->cards->shuffle('deck');<br />
// Deal 13 cards to each players<br />
// Create deck, shuffle it and give 13 initial cards<br />
$players = self::loadPlayersBasicInfos();<br />
foreach ( $players as $player_id => $player ) {<br />
$cards = $this->cards->pickCards(13, 'deck', $player_id);<br />
// Notify player about his cards<br />
self::notifyPlayer($player_id, 'newHand', '', array ('cards' => $cards ));<br />
}<br />
self::setGameStateValue('alreadyPlayedHearts', 0);<br />
$this->gamestate->nextState("");<br />
}<br />
<br />
function stNewTrick() {<br />
// New trick: active the player who wins the last trick, or the player who own the club-2 card<br />
// Reset trick color to 0 (= no color)<br />
self::setGameStateInitialValue('trickColor', 0);<br />
$this->gamestate->nextState();<br />
}<br />
<br />
function stNextPlayer() {<br />
// Active next player OR end the trick and go to the next trick OR end the hand<br />
if ($this->cards->countCardInLocation('cardsontable') == 4) {<br />
// This is the end of the trick<br />
// Move all cards to "cardswon" of the given player<br />
$best_value_player_id = self::activeNextPlayer(); // TODO figure out winner of trick<br />
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);<br />
<br />
if ($this->cards->countCardInLocation('hand') == 0) {<br />
// End of the hand<br />
$this->gamestate->nextState("endHand");<br />
} else {<br />
// End of the trick<br />
$this->gamestate->nextState("nextTrick");<br />
}<br />
} else {<br />
// Standard case (not the end of the trick)<br />
// => just active the next player<br />
$player_id = self::activeNextPlayer();<br />
self::giveExtraTime($player_id);<br />
$this->gamestate->nextState('nextPlayer');<br />
}<br />
}<br />
<br />
function stEndHand() {<br />
$this->gamestate->nextState("nextHand");<br />
}<br />
<br />
</pre><br />
Important: All state actions game or player must end with state transition (or thrown exception). Also make sure its ONLY one state transition,<br />
if you accidentally fall though after state transition and do another one it will be a real mess and head scratching for long time.<br />
<br />
Now find 'player actions' section and paste this code there<br />
<pre><br />
function playCard($card_id) {<br />
self::checkAction("playCard");<br />
$player_id = self::getActivePlayerId();<br />
throw new BgaUserException(self::_("Not implemented: ") . "$player_id plays $card_id");<br />
}<br />
</pre><br />
We won't implement it yet but throw an exception which we will see if interaction is working properly<br />
<br />
Now the game should start but it would not be any different then before because we have to implement actual interactions.<br />
Its good to check if it still working though (and if it was running before you have to exit because we changed state machine and normally it will break stuff)<br />
<br />
== Client - Server interactions ==<br />
<br />
Now to implement things for real we have hook UI actions to ajax calls, and process notifications send by server.<br />
So previously we hooked playCardOnTable right into js handler which caused client animation, in real game its a two<br />
step operation. When user clicks on game element js client sends an ajax call to server, server processes it and updates database, server sends<br />
notification in response, client hooks animations to server notification.<br />
<br />
So in .js code replace onPlayerHandSelectionChanged with<br />
<pre><br />
onPlayerHandSelectionChanged : function() {<br />
var items = this.playerHand.getSelectedItems();<br />
<br />
if (items.length > 0) {<br />
var action = 'playCard';<br />
if (this.checkAction(action, true)) {<br />
// Can play a card<br />
var card_id = items[0].id; <br />
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", {<br />
id : card_id,<br />
lock : true<br />
}, this, function(result) {<br />
}, function(is_error) {<br />
});<br />
<br />
this.playerHand.unselectAll();<br />
} else if (this.checkAction('giveCards')) {<br />
// Can give cards => let the player select some cards<br />
} else {<br />
this.playerHand.unselectAll();<br />
}<br />
}<br />
},<br />
</pre><br />
<br />
<br />
Now when you click on card you should get a server response: Not implemented...<br />
<br />
Lets implement it, in .game.php<br />
<pre><br />
function playCard($card_id) {<br />
self::checkAction("playCard");<br />
$player_id = self::getActivePlayerId();<br />
$this->cards->moveCard($card_id, 'cardsontable', $player_id);<br />
// XXX check rules here<br />
$currentCard = $this->cards->getCard($card_id);<br />
// And notify<br />
self::notifyAllPlayers('playCard', clienttranslate('${player_name} plays ${value_displayed} ${color_displayed}'), array (<br />
'i18n' => array ('color_displayed','value_displayed' ),'card_id' => $card_id,'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),'value' => $currentCard ['type_arg'],<br />
'value_displayed' => $this->values_label [$currentCard ['type_arg']],'color' => $currentCard ['type'],<br />
'color_displayed' => $this->colors [$currentCard ['type']] ['name'] ));<br />
// Next player<br />
$this->gamestate->nextState('playCard');<br />
}<br />
</pre><br />
<br />
We get the card from client, we move it to the tableau (moveCard is hooked to database directly, its part of deck class),<br />
we notify all players and we change state. What we missing here is bunch of checks (rule enforcements), we will add it later.<br />
<br />
Interesting part about this notify is that we use i18n array for string that needs to be translated by client, so<br />
they sent as English text in notification, then client has to know which parameters needs translating.<br />
<br />
On the client side .js we have to implement a notification handler to do the animation<br />
<br />
<pre><br />
setupNotifications : function() {<br />
console.log('notifications subscriptions setup');<br />
<br />
dojo.subscribe('newHand', this, "notif_newHand");<br />
dojo.subscribe('playCard', this, "notif_playCard");<br />
<br />
},<br />
<br />
notif_newHand : function(notif) {<br />
// We received a new full hand of 13 cards.<br />
this.playerHand.removeAll();<br />
<br />
for ( var i in notif.args.cards) {<br />
var card = notif.args.cards[i];<br />
var color = card.type;<br />
var value = card.type_arg;<br />
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);<br />
}<br />
},<br />
<br />
notif_playCard : function(notif) {<br />
// Play a card on the table<br />
this.playCardOnTable(notif.args.player_id, notif.args.color, notif.args.value, notif.args.card_id);<br />
},<br />
</pre><br />
<br />
Now it actually works through the server when you click on card - the move is recorded. If you testing it now you will notice<br />
after trick is done all cards remains on the table, but if you press F5 they would disappear, this is because<br />
we updated database to pick-up the cards but did not send notification about it, so we need to send notification about it<br />
and have a handler for it<br />
<br />
So in .game.php file add notification in stNextPlayer function after moveAllCardsInLocation call:<br />
<br />
<pre><br />
// Notify<br />
// Note: we use 2 notifications here in order we can pause the display during the first notification<br />
// before we move all cards to the winner (during the second)<br />
$players = self::loadPlayersBasicInfos();<br />
self::notifyAllPlayers( 'trickWin', clienttranslate('${player_name} wins the trick'), array(<br />
'player_id' => $best_value_player_id,<br />
'player_name' => $players[ $best_value_player_id ]['player_name']<br />
) ); <br />
self::notifyAllPlayers( 'giveAllCardsToPlayer','', array(<br />
'player_id' => $best_value_player_id<br />
) );<br />
</pre><br />
<br />
And in .js file add 2 more notification handlers.<br />
<br />
This is to subscribe in setupNotifications function<br />
<pre><br />
dojo.subscribe( 'trickWin', this, "notif_trickWin" );<br />
this.notifqueue.setSynchronous( 'trickWin', 1000 );<br />
dojo.subscribe( 'giveAllCardsToPlayer', this, "notif_giveAllCardsToPlayer" );<br />
</pre><br />
<br />
And this are handlers<br />
<pre><br />
notif_trickWin : function(notif) {<br />
// We do nothing here (just wait in order players can view the 4 cards played before they're gone.<br />
},<br />
notif_giveAllCardsToPlayer : function(notif) {<br />
// Move all cards on table to given table, then destroy them<br />
var winner_id = notif.args.player_id;<br />
for ( var player_id in this.gamedatas.players) {<br />
var anim = this.slideToObject('cardontable_' + player_id, 'overall_player_board_' + winner_id);<br />
dojo.connect(anim, 'onEnd', function(node) {<br />
dojo.destroy(node);<br />
});<br />
anim.play();<br />
}<br />
},<br />
</pre><br />
<br />
So 'trickWin' notification does not do much except it will delay the processing of next notification by 1 second (1000 ms)<br />
and it will log the message (that happens independent of what handler does).<br />
<i>Note: if on the other hand you don't want to log but what what to do something else send empty message</i><br />
<br />
Now after the trick you see all cards move the "player's stash".<br />
<br />
== Scoring and End of game handling ==<br />
<br />
Now we should calculate scoring and for that we need to actually track who wins the trick.<br />
Trick is won by the player with highest card (no trump). We just need to remember what is trick suite.<br />
For which we will use state variable 'trickColor' which we already conveniently created.<br />
<br />
In .game.php file find playCard function and add this before notify functions<br />
$currentTrickColor = self::getGameStateValue( 'trickColor' ) ;<br />
if( $currentTrickColor == 0 )<br />
self::setGameStateValue( 'trickColor', $currentCard['type'] );<br />
<br />
This will make sure we remember first suit being played, now to use it modify stNextPlayer function to fix our TODO comment<br />
<pre><br />
function stNextPlayer() {<br />
// Active next player OR end the trick and go to the next trick OR end the hand<br />
if ($this->cards->countCardInLocation('cardsontable') == 4) {<br />
// This is the end of the trick<br />
$cards_on_table = $this->cards->getCardsInLocation('cardsontable');<br />
$best_value = 0;<br />
$best_value_player_id = null;<br />
$currentTrickColor = self::getGameStateValue('trickColor');<br />
foreach ( $cards_on_table as $card ) {<br />
// Note: type = card color<br />
if ($card ['type'] == $currentTrickColor) {<br />
if ($best_value_player_id === null || $card ['type_arg'] > $best_value) {<br />
$best_value_player_id = $card ['location_arg']; // Note: location_arg = player who played this card on table<br />
$best_value = $card ['type_arg']; // Note: type_arg = value of the card<br />
}<br />
}<br />
}<br />
<br />
// Active this player => he's the one who starts the next trick<br />
$this->gamestate->changeActivePlayer( $best_value_player_id );<br />
<br />
// Move all cards to "cardswon" of the given player<br />
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);<br />
<br />
// Notify<br />
// ... same code here as before<br />
</pre><br />
<br />
The scoring rule in the studio example code is huge multi-page function, for this tutorial we will make simplier.<br />
Lets score -1 point per heart and call it a day. And game will end when somebody goes -100 or below.<br />
<br />
As UI goes for scoring, the main thing to update is the scoring on the mini boards represented by stars, also<br />
we want to show that in the log. <br />
In addition scoring can be shown in [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialog]] using tableWindow notification, but it is a tutorial on its own and you can do it as homework (it is part of original heart game).<br />
<br />
In .js file we need to add one more subscription and notification handler:<br />
dojo.subscribe( 'newScores', this, "notif_newScores" );<br />
in setupNotifications<br />
<br />
and <br />
notif_newScores : function(notif) {<br />
// Update players' scores<br />
for ( var player_id in notif.args.newScores) {<br />
this.scoreCtrl[player_id].toValue(notif.args.newScores[player_id]);<br />
}<br />
},<br />
somewhere after. this.scoreCtrl is pre-existing object that shows the scoring and this function will update score values per player from notification argument<br />
<br />
so in .game.php our stEndHand function will look like<br />
<br />
<pre><br />
function stEndHand() {<br />
// Count and score points, then end the game or go to the next hand.<br />
$players = self::loadPlayersBasicInfos();<br />
// Gets all "hearts" + queen of spades<br />
<br />
$player_to_points = array ();<br />
foreach ( $players as $player_id => $player ) {<br />
$player_to_points [$player_id] = 0;<br />
}<br />
$cards = $this->cards->getCardsInLocation("cardswon");<br />
foreach ( $cards as $card ) {<br />
$player_id = $card ['location_arg'];<br />
// Note: 2 = heart<br />
if ($card ['type'] == 2) {<br />
$player_to_points [$player_id] ++;<br />
}<br />
}<br />
// Apply scores to player<br />
foreach ( $player_to_points as $player_id => $points ) {<br />
if ($points != 0) {<br />
$sql = "UPDATE player SET player_score=player_score-$points WHERE player_id='$player_id'";<br />
self::DbQuery($sql);<br />
$heart_number = $player_to_points [$player_id];<br />
self::notifyAllPlayers("points", clienttranslate('${player_name} gets ${nbr} hearts and looses ${nbr} points'), array (<br />
'player_id' => $player_id,'player_name' => $players [$player_id] ['player_name'],<br />
'nbr' => $heart_number ));<br />
} else {<br />
// No point lost (just notify)<br />
self::notifyAllPlayers("points", clienttranslate('${player_name} did not get any hearts'), array (<br />
'player_id' => $player_id,'player_name' => $players [$player_id] ['player_name'] ));<br />
}<br />
}<br />
$newScores = self::getCollectionFromDb("SELECT player_id, player_score FROM player", true );<br />
self::notifyAllPlayers( "newScores", '', array( 'newScores' => $newScores ) );<br />
<br />
///// Test if this is the end of the game<br />
foreach ( $newScores as $player_id => $score ) {<br />
if ($score <= -100) {<br />
// Trigger the end of the game !<br />
$this->gamestate->nextState("endGame");<br />
return;<br />
}<br />
}<br />
<br />
<br />
$this->gamestate->nextState("nextHand");<br />
}<br />
</pre><br />
<br />
<br />
So it should more less work now, including end of game condition. Try to play it!<br />
<br />
== Additional stuff ==<br />
<br />
The following things were not implemented and can add them yourself by looking at the code of original hearts game:<br />
<br />
* Remove debug code from setupNewGame to deal cards, cards are now dealt in stNewHand state handler<br />
* Rule checking and rule enforcements in playCard function<br />
* Start scoring with 100 points each and end when <= 0<br />
* Fix scoring rules with Q of spades and 26 point reverse scoring<br />
* First player one with 2 club<br />
* Add progress handling<br />
* Add statistics<br />
* Add card exchange states<br />
* Add game option to start with 75 points instead of 100</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Tutorial_gomoku&diff=4037
Tutorial gomoku
2020-04-15T21:14:49Z
<p>Tutchek: Removed navigation - too wide images on this page make problems..</p>
<hr />
<div><br />
This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).<br />
<br />
== You will start from our 'empty game' template ==<br />
<br />
Here is how your games looks by default when it has just been created:<br />
<br />
[[File:Gomoku tuto1.png]]<br />
<br />
== Setup the board ==<br />
<br />
Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.<br />
<br />
Edit .tpl to add some divs for the board in the HTML. For example:<br />
<br />
<pre><br />
<div id="gmk_game_area"><br />
<div id="gmk_background"><br />
<div id="gmk_goban"><br />
</div><br />
</div> <br />
</div><br />
</pre><br />
<br />
Edit .css to set the div sizes and positions and show the image of the board as background.<br />
<br />
<pre><br />
#gmk_game_area {<br />
text-align: center;<br />
position: relative;<br />
}<br />
<br />
#gmk_background {<br />
width: 620px;<br />
height: 620px; <br />
position: relative;<br />
display: inline-block;<br />
}<br />
<br />
#gmk_goban { <br />
background-image: url( 'img/goban.jpg');<br />
width: 620px;<br />
height: 620px;<br />
position: absolute; <br />
}<br />
</pre><br />
<br />
[[File:Gomoku tuto2.png]]<br />
<br />
== Setup the backbone of your game ==<br />
<br />
Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).<br />
<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `intersection` (<br />
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,<br />
`coord_x` tinyint(2) unsigned NOT NULL,<br />
`coord_y` tinyint(2) unsigned NOT NULL,<br />
`stone_color` varchar(8) NULL,<br />
PRIMARY KEY (`id`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;<br />
</pre><br />
<br />
Edit .game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.<br />
<br />
<pre><br />
// Insert (empty) intersections into database<br />
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";<br />
$values = array();<br />
for ($x = 0; $x < 19; $x++) {<br />
for ($y = 0; $y < 19; $y++) {<br />
<br />
$values[] = "($x, $y)"; <br />
}<br />
}<br />
$sql .= implode( $values, ',' );<br />
self::DbQuery( $sql );<br />
</pre><br />
<br />
Edit .game.php->getAllDatas() to retrieve the state of the intersections from the database.<br />
<br />
<pre><br />
// Intersections<br />
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";<br />
$result['intersections'] = self::getCollectionFromDb( $sql );<br />
</pre><br />
<br />
Edit .tpl to create a template for intersections.<br />
<br />
<pre><br />
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';<br />
</pre><br />
<br />
Define the styles for the intersection divs.<br />
<br />
<pre><br />
.gmk_intersection {<br />
width: 30px;<br />
height: 30px;<br />
position: relative;<br />
}<br />
</pre><br />
<br />
Edit .js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in .game.php->getAllDatas() is now available in your .js->setup() in gamedatas.intersections.<br />
<br />
<pre><br />
// Setup intersections<br />
for( var id in gamedatas.intersections )<br />
{<br />
var intersection = gamedatas.intersections[id];<br />
<br />
dojo.place( this.format_block('jstpl_intersection', {<br />
x:intersection.coord_x,<br />
y:intersection.coord_y,<br />
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)<br />
} ), $ ( 'gmk_background' ) );<br />
<br />
var x_pix = this.getXPixelCoordinates(intersection.coord_x);<br />
var y_pix = this.getYPixelCoordinates(intersection.coord_y);<br />
<br />
this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();<br />
<br />
if (intersection.stone_color != null) {<br />
// This intersection is taken, it shouldn't appear as clickable anymore<br />
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );<br />
}<br />
} <br />
</pre><br />
<br />
Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right. <br />
<br />
<pre><br />
.gmk_intersection {<br />
width: 30px;<br />
height: 30px;<br />
position: relative;<br />
background-color: blue;<br />
opacity: 0.3;<br />
}<br />
</pre><br />
<br />
You can declare some constants in material.inc.php and pass them to your .js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.<br />
<br />
* Declare your constants in material.inc.php (this will be automatically included in your .game.php)<br />
<br />
<pre><br />
$this->gameConstants = array(<br />
"INTERSECTION_WIDTH" => 30,<br />
"INTERSECTION_HEIGHT" => 30, <br />
"INTERSECTION_X_SPACER" => 2.8, // Float<br />
"INTERSECTION_Y_SPACER" => 2.8, // Float<br />
"X_ORIGIN" => 0,<br />
"Y_ORIGIN" => 0,<br />
);<br />
</pre><br />
<br />
* In .game.php->getAllDatas(), add the constants to the result array<br />
<br />
// Constants<br />
$result['constants'] = $this->gameConstants;<br />
<br />
* In .js constructor, define a class variable for constants<br />
<br />
// Game constants<br />
this.gameConstants = null;<br />
<br />
* In .js->setup() assign the constants to this variable<br />
<br />
this.gameConstants = gamedatas.constants;<br />
<br />
* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions<br />
<br />
getXPixelCoordinates: function( intersection_x )<br />
{<br />
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']); <br />
},<br />
<br />
getYPixelCoordinates: function( intersection_y )<br />
{<br />
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']); <br />
},<br />
<br />
Here is what you should get:<br />
<br />
[[File:Gomoku tuto3.png]]<br />
<br />
== Manage states and events ==<br />
<br />
Define your game states in states.inc.php. For gomoku we will use 3 states in addition of the predefined states 1 (gameSetup) and 99 (gameEnd). One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.<br />
<br />
The first state requires an action from the player, so its type is 'activeplayer'.<br />
<br />
The two others are automatic actions for the game, so their type is 'game'.<br />
<br />
We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.<br />
<br />
<pre><br />
2 => array(<br />
"name" => "playerTurn",<br />
"description" => clienttranslate('${actplayer} must play a stone'),<br />
"descriptionmyturn" => clienttranslate('${you} must play a stone'),<br />
"type" => "activeplayer",<br />
"possibleactions" => array( "playStone" ),<br />
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )<br />
),<br />
<br />
3 => array(<br />
"name" => "checkEndOfGame",<br />
"description" => '',<br />
"type" => "game",<br />
"action" => "stCheckEndOfGame",<br />
"updateGameProgression" => true,<br />
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )<br />
),<br />
<br />
4 => array(<br />
"name" => "nextPlayer",<br />
"description" => '',<br />
"type" => "game",<br />
"action" => "stNextPlayer",<br />
"transitions" => array( "" => 2 )<br />
),<br />
</pre><br />
<br />
Implement the 'stNextPlayer()' function in .game.php to manage turn rotation. Except if there are special rules for the game turn depending on context, this is really easy:<br />
<br />
<pre><br />
function stNextPlayer()<br />
{<br />
self::trace( "stNextPlayer" );<br />
<br />
// Go to next player<br />
$active_player = self::activeNextPlayer();<br />
self::giveExtraTime( $active_player ); <br />
<br />
$this->gamestate->nextState();<br />
}<br />
</pre><br />
<br />
Add onclick events on intersections in .js->setup()<br />
<br />
// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)<br />
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");<br />
<br />
Declare the corresponding .js->onClickIntersection() function, which calls an action function on the server with appropriate parameters<br />
<br />
<pre><br />
onClickIntersection: function( evt )<br />
{<br />
console.log( '$$$$ Event : onClickIntersection' );<br />
dojo.stopEvent( evt );<br />
<br />
if( ! this.checkAction( 'playStone' ) )<br />
{ return; }<br />
<br />
var node = evt.currentTarget.id;<br />
var coord_x = node.split('_')[1];<br />
var coord_y = node.split('_')[2];<br />
<br />
console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );<br />
<br />
if ( this.isCurrentPlayerActive() ) {<br />
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );<br />
}<br />
},<br />
</pre><br />
<br />
Add this action function in .action.php, retrieving parameters and calling the appropriate game action<br />
<br />
<pre><br />
public function playStone()<br />
{<br />
self::setAjaxMode(); <br />
<br />
// Retrieve arguments<br />
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method<br />
$coord_x = self::getArg( "coord_x", AT_posint, true );<br />
$coord_y = self::getArg( "coord_y", AT_posint, true );<br />
<br />
// Then, call the appropriate method in your game logic, like "playCard" or "myAction"<br />
$this->game->playStone( $coord_x, $coord_y );<br />
<br />
self::ajaxResponse( );<br />
}<br />
</pre><br />
<br />
Add game action in .game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.<br />
<br />
<pre><br />
function playStone( $coord_x, $coord_y )<br />
{<br />
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)<br />
self::checkAction( 'playStone' ); <br />
<br />
$player_id = self::getActivePlayerId();<br />
<br />
// Check that this intersection is free<br />
$sql = "SELECT<br />
id, coord_x, coord_y, stone_color<br />
FROM<br />
intersection <br />
WHERE <br />
coord_x = $coord_x <br />
AND coord_y = $coord_y<br />
AND stone_color is null<br />
";<br />
$intersection = self::getObjectFromDb( $sql );<br />
<br />
if ($intersection == null) {<br />
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );<br />
}<br />
<br />
// Get player color<br />
$sql = "SELECT<br />
player_id, player_color<br />
FROM<br />
player <br />
WHERE <br />
player_id = $player_id<br />
";<br />
$player = self::getNonEmptyObjectFromDb( $sql );<br />
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');<br />
<br />
// Update the intersection with a stone of the appropriate color<br />
$intersection_id = $intersection['id'];<br />
$sql = "UPDATE<br />
intersection<br />
SET<br />
stone_color = '$color'<br />
WHERE <br />
id = $intersection_id<br />
";<br />
self::DbQuery($sql);<br />
<br />
// Notify all players<br />
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone on ${coord_x},${coord_y}' ), array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'coord_x' => $coord_x,<br />
'coord_y' => $coord_y,<br />
'color' => $color<br />
) );<br />
<br />
// Go to next game state<br />
$this->gamestate->nextState( "stonePlayed" );<br />
}<br />
</pre><br />
<br />
Catch the notification in .js->setupNotifications() and link it to a javascript function to execute when the notification is received.<br />
<br />
<pre><br />
setupNotifications: function()<br />
{<br />
console.log( 'notifications subscriptions setup' );<br />
<br />
dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );<br />
}<br />
</pre><br />
<br />
Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.<br />
<br />
<pre><br />
notif_stonePlayed: function( notif )<br />
{<br />
console.log( '**** Notification : stonePlayed' );<br />
console.log( notif );<br />
<br />
// Create a stone<br />
dojo.place( this.format_block('jstpl_stone', {<br />
stone_type:'stone_' + notif.args.color,<br />
x:notif.args.coord_x,<br />
y:notif.args.coord_y<br />
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );<br />
<br />
// Place it on the player panel<br />
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );<br />
<br />
// Animate a slide from the player panel to the intersection<br />
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1 );<br />
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );<br />
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {<br />
// At the end of the slide, update the intersection <br />
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'no_stone' );<br />
dojo.addClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'stone_' + notif.args.color );<br />
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );<br />
<br />
// We can now destroy the stone since it is now visible through the change in style of the intersection<br />
dojo.destroy( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y );<br />
}));<br />
slide.play();<br />
},<br />
</pre><br />
<br />
For this function to work properly, you also need: <br />
<br />
* to declare a stone javascript template in your .tpl file.<br />
<br />
<pre><br />
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';<br />
</pre><br />
<br />
* to define the css styles for the stones<br />
<br />
<pre><br />
.gmk_intersection {<br />
width: 30px;<br />
height: 30px;<br />
position: relative;<br />
background-image: url( 'img/stones.png' );<br />
}<br />
<br />
.gmk_stone {<br />
width: 30px;<br />
height: 30px;<br />
position: absolute;<br />
background-image: url( 'img/stones.png' );<br />
}<br />
<br />
.no_stone { background-position: -60px 0px; }<br />
<br />
.stone_black { background-position: 0px 0px; }<br />
.stone_white { background-position: -30px 0px; }<br />
</pre><br />
<br />
These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:<br />
<br />
[[File:Gomoku stones.png]]<br />
<br />
The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:<br />
<br />
* we define in the css file the 'clickable' css class<br />
<br />
<pre><br />
.clickable {<br />
cursor: pointer;<br />
}<br />
.clickable:hover { background-position: -90px 0px; }<br />
</pre><br />
<br />
* in .js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone<br />
<br />
<pre><br />
onEnteringState: function( stateName, args )<br />
{<br />
console.log( 'Entering state: '+stateName );<br />
<br />
switch( stateName )<br />
{<br />
<br />
case 'playerTurn':<br />
if( this.isCurrentPlayerActive() )<br />
{<br />
var queueEntries = dojo.query( '.no_stone' );<br />
for(var i=0; i<queueEntries.length; i++) { <br />
dojo.addClass( queueEntries[i], 'clickable' );<br />
}<br />
} <br />
}<br />
},<br />
</pre><br />
<br />
Finally, make sure to modify the default colors for players to white and black<br />
<br />
$default_colors = array( "000000", "ffffff", );<br />
<br />
The basic game turn is implemented: you can now drop some stones!<br />
<br />
[[File:Gomoku tuto4.png]]<br />
<br />
== Cleanup your styles ==<br />
<br />
Remove temporary css visualisation helpers : looks good!<br />
<br />
[[File:Gomoku tuto5.png]]<br />
<br />
== Add some counters in the player panels ==<br />
<br />
Edit .tpl to create a template for your counters.<br />
<br />
<pre><br />
var jstpl_player_board = '\<div class="cp_board">\<br />
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\<br />
</div>';<br />
</pre><br />
<br />
Edit .js->setup() to setup the player panels with this extra information<br />
<br />
<pre><br />
// Setting up player boards<br />
for( var player_id in gamedatas.players )<br />
{<br />
var player = gamedatas.players[player_id];<br />
<br />
// Setting up players boards if needed<br />
var player_board_div = $('player_board_'+player_id);<br />
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );<br />
}<br />
</pre><br />
<br />
Add some styles in your .css<br />
<br />
<pre><br />
.gmk_stoneicon {<br />
width: 14px;<br />
height: 14px;<br />
display: inline-block;<br />
position: relative;<br />
background-repeat: no-repeat;<br />
background-image: url( 'img/stone_icons.png');<br />
background-position: -28px 0px;<br />
margin-top: 4px;<br />
margin-right: 3px;<br />
}<br />
<br />
.gmk_stoneicon_000000 {<br />
background-position:0px 0px<br />
}<br />
<br />
.gmk_stoneicon_ffffff {<br />
background-position:-14px 0px<br />
}<br />
<br />
.cp_board {<br />
clear: both;<br />
}<br />
</pre><br />
<br />
In your .game.php, create a function to return your game counters<br />
<br />
<pre><br />
/*<br />
getGameCounters:<br />
<br />
Gather all relevant counters about current game situation (visible by the current player).<br />
*/<br />
function getGameCounters($player_id) {<br />
$sql = "<br />
SELECT<br />
concat('stonecount_p', cast(p.player_id as char)) counter_name,<br />
case when p.player_color = 'white' then 180 - count(id) else 181 - count(id) end counter_value<br />
FROM (select player_id, case when player_color = 'ffffff' then 'white' else 'black' end player_color FROM player) p<br />
LEFT JOIN intersection i on i.stone_color = p.player_color<br />
GROUP BY p.player_color, p.player_id<br />
";<br />
if ($player_id != null) {<br />
// Player private counters: concatenate extra SQL request with UNION using the $player_id parameter<br />
}<br />
<br />
return self::getNonEmptyCollectionFromDB( $sql );<br />
}<br />
</pre><br />
<br />
Return your game counters in your .game.php->getAllDatas()<br />
<br />
<pre><br />
// Counters<br />
$result['counters'] = $this->getGameCounters($current_player_id);<br />
</pre><br />
<br />
And pass them in any notification that needs to update them<br />
<br />
<pre><br />
// Notify all players<br />
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),<br />
'coord_x' => $coord_x,<br />
'coord_y' => $coord_y,<br />
'color' => $color,<br />
'counters' => $this->getGameCounters(self::getCurrentPlayerId())<br />
) );<br />
</pre><br />
<br />
Finally, in your .js->setup() and notification handler function call respectively<br />
<br />
<pre><br />
this.updateCounters(gamedatas.counters);<br />
</pre><br />
<br />
and<br />
<br />
<pre><br />
this.updateCounters(notif.args.counters);<br />
</pre><br />
<br />
You now have a working counter!<br />
<br />
[[File:Gomoku tuto7.png]]<br />
<br />
== Implement rules and end of game conditions ==<br />
<br />
Implement specific rules for the game. For example in Gomoku, black plays first. So in .game.php->setupNewGame(), at the end of the setup make the black player active:<br />
<br />
<pre><br />
// Black plays first<br />
$sql = "SELECT player_id, player_name FROM player WHERE player_color = '000000' ";<br />
$black_player = self::getNonEmptyObjectFromDb( $sql );<br />
<br />
$this->gamestate->changeActivePlayer( $black_player['player_id'] );<br />
</pre><br />
<br />
Implement rule for computing game progression in .game.php->getGameProgression(). For Gomoku we will use the rate of occupied intersections over the total number of intersections. This will often be wildly inaccurate as the game can end pretty quickly, but it's about the best we can do (the game can drag to a stalemate with all intersections occupied and no winner).<br />
<br />
<pre><br />
function getGameProgression()<br />
{<br />
// Compute and return the game progression<br />
<br />
// Number of stones laid down on the goban over the total number of intersections * 100<br />
$sql = "<br />
SELECT round(100 * count(id) / (19*19) ) as value from intersection WHERE stone_color is not null<br />
";<br />
$counter = self::getNonEmptyObjectFromDB( $sql );<br />
<br />
return $counter['value'];<br />
}<br />
</pre><br />
<br />
Implement end of game detection and update the score according to who is the winner. It is easier to check for a win directly after setting the stone, so: <br />
<br />
* declare a global 'end_of_game' variable in .game.php->Gomoku()<br />
<br />
self::initGameStateLabels( array(<br />
"end_of_game" => 10,<br />
) );<br />
<br />
* init that global variable to 0 in .game.php->setupNewGame()<br />
<br />
self::setGameStateInitialValue( 'end_of_game', 0 );<br />
<br />
* add the appropriate code in .game.php before proceeding to the next state, using a checkForWin() function implemented separately for clarity. If the game has been won, we set the score, send a score update notification to the client side, and set the 'end_of_game' global variable to 1 as a flag signaling that the game has ended.<br />
<br />
<pre><br />
// Check if end of game has been met<br />
if ($this->checkForWin( $coord_x, $coord_y, $color )) {<br />
<br />
// Set active player score to 1 (he is the winner)<br />
$sql = "UPDATE player SET player_score = 1 WHERE player_id = $player_id";<br />
self::DbQuery($sql);<br />
<br />
// Notify final score<br />
$this->notifyAllPlayers( "finalScore",<br />
clienttranslate( '${player_name} wins the game!' ),<br />
array(<br />
"player_name" => self::getActivePlayerName(),<br />
"player_id" => $player_id,<br />
"score_delta" => 1,<br />
)<br />
);<br />
<br />
// Set global variable flag to pass on the information that the game has ended<br />
self::setGameStateValue('end_of_game', 1);<br />
<br />
// End of game message<br />
$this->notifyAllPlayers( "message",<br />
clienttranslate('Thanks for playing!'),<br />
array(<br />
)<br />
);<br />
<br />
}<br />
</pre><br />
<br />
* Then in the gomoku->stCheckEndOfGame() function which is called when your state machine goes to the 'checkEndOfGame' state, check for this variable and for other possible 'end of game' conditions (draw).<br />
<br />
<pre><br />
function stCheckEndOfGame()<br />
{<br />
self::trace( "stCheckEndOfGame" );<br />
<br />
$transition = "notEndedYet";<br />
<br />
// If there is no more free intersections, the game ends<br />
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection WHERE stone_color is null";<br />
$free = self::getCollectionFromDb( $sql );<br />
<br />
if (count($free) == 0) {<br />
$transition = "gameEnded";<br />
} <br />
<br />
// If the 'end of game' flag has been set, end the game<br />
if (self::getGameStateValue('end_of_game') == 1) {<br />
$transition = "gameEnded";<br />
}<br />
<br />
$this->gamestate->nextState( $transition );<br />
}<br />
</pre><br />
<br />
* Catch the score notification on the client side in .js->setupNotifications(). It is advised to set up a small delay after that so that end of game popup doesn't show too quickly.<br />
<br />
<pre><br />
dojo.subscribe( 'finalScore', this, "notif_finalScore" );<br />
this.notifqueue.setSynchronous( 'finalScore', 1500 );<br />
</pre><br />
<br />
* Implement the function declared to handle the notification.<br />
<br />
<pre><br />
notif_finalScore: function( notif )<br />
{<br />
console.log( '**** Notification : finalScore' );<br />
console.log( notif );<br />
<br />
// Update score<br />
this.scoreCtrl[ notif.args.player_id ].incValue( notif.args.score_delta );<br />
},<br />
</pre><br />
<br />
'''Test everything thoroughly... you are done!'''<br />
<br />
[[File:Gomoku tuto6.png]]</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Tutorial_gomoku&diff=4036
Tutorial gomoku
2020-04-15T21:13:57Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of [http://en.wikipedia.org/wiki/Gomoku '''Gomoku'''] (also known as Gobang or Five in a Row).<br />
<br />
== You will start from our 'empty game' template ==<br />
<br />
Here is how your games looks by default when it has just been created:<br />
<br />
[[File:Gomoku tuto1.png]]<br />
<br />
== Setup the board ==<br />
<br />
Gather useful images for the game and edit them as needed. Upload them in the 'img' folder of your SFTP access.<br />
<br />
Edit .tpl to add some divs for the board in the HTML. For example:<br />
<br />
<pre><br />
<div id="gmk_game_area"><br />
<div id="gmk_background"><br />
<div id="gmk_goban"><br />
</div><br />
</div> <br />
</div><br />
</pre><br />
<br />
Edit .css to set the div sizes and positions and show the image of the board as background.<br />
<br />
<pre><br />
#gmk_game_area {<br />
text-align: center;<br />
position: relative;<br />
}<br />
<br />
#gmk_background {<br />
width: 620px;<br />
height: 620px; <br />
position: relative;<br />
display: inline-block;<br />
}<br />
<br />
#gmk_goban { <br />
background-image: url( 'img/goban.jpg');<br />
width: 620px;<br />
height: 620px;<br />
position: absolute; <br />
}<br />
</pre><br />
<br />
[[File:Gomoku tuto2.png]]<br />
<br />
== Setup the backbone of your game ==<br />
<br />
Edit dbmodel.sql to create a table for intersections. We need coordinates for each intersection and a field to store the color of the stone on this intersection (if any).<br />
<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `intersection` (<br />
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,<br />
`coord_x` tinyint(2) unsigned NOT NULL,<br />
`coord_y` tinyint(2) unsigned NOT NULL,<br />
`stone_color` varchar(8) NULL,<br />
PRIMARY KEY (`id`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;<br />
</pre><br />
<br />
Edit .game.php->setupNewGame() to insert the empty intersections (19x19) with coordinates into the database.<br />
<br />
<pre><br />
// Insert (empty) intersections into database<br />
$sql = "INSERT INTO intersection (coord_x, coord_y) VALUES ";<br />
$values = array();<br />
for ($x = 0; $x < 19; $x++) {<br />
for ($y = 0; $y < 19; $y++) {<br />
<br />
$values[] = "($x, $y)"; <br />
}<br />
}<br />
$sql .= implode( $values, ',' );<br />
self::DbQuery( $sql );<br />
</pre><br />
<br />
Edit .game.php->getAllDatas() to retrieve the state of the intersections from the database.<br />
<br />
<pre><br />
// Intersections<br />
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection ";<br />
$result['intersections'] = self::getCollectionFromDb( $sql );<br />
</pre><br />
<br />
Edit .tpl to create a template for intersections.<br />
<br />
<pre><br />
var jstpl_intersection='<div class="gmk_intersection ${stone_type}" id="intersection_${x}_${y}"></div>';<br />
</pre><br />
<br />
Define the styles for the intersection divs.<br />
<br />
<pre><br />
.gmk_intersection {<br />
width: 30px;<br />
height: 30px;<br />
position: relative;<br />
}<br />
</pre><br />
<br />
Edit .js->setup() to setup the intersections layer that will be used to get click events and to display the stones. The data you returned in $result['intersections'] in .game.php->getAllDatas() is now available in your .js->setup() in gamedatas.intersections.<br />
<br />
<pre><br />
// Setup intersections<br />
for( var id in gamedatas.intersections )<br />
{<br />
var intersection = gamedatas.intersections[id];<br />
<br />
dojo.place( this.format_block('jstpl_intersection', {<br />
x:intersection.coord_x,<br />
y:intersection.coord_y,<br />
stone_type:(intersection.stone_color == null ? "no_stone" : 'stone_' + intersection.stone_color)<br />
} ), $ ( 'gmk_background' ) );<br />
<br />
var x_pix = this.getXPixelCoordinates(intersection.coord_x);<br />
var y_pix = this.getYPixelCoordinates(intersection.coord_y);<br />
<br />
this.slideToObjectPos( $('intersection_'+intersection.coord_x+'_'+intersection.coord_y), $('gmk_background'), x_pix, y_pix, 10 ).play();<br />
<br />
if (intersection.stone_color != null) {<br />
// This intersection is taken, it shouldn't appear as clickable anymore<br />
dojo.removeClass( 'intersection_' + intersection.coord_x + '_' + intersection.coord_y, 'clickable' );<br />
}<br />
} <br />
</pre><br />
<br />
Use some temporary css border-color or background-color and opacity to see the divs and make sure you have them positioned right. <br />
<br />
<pre><br />
.gmk_intersection {<br />
width: 30px;<br />
height: 30px;<br />
position: relative;<br />
background-color: blue;<br />
opacity: 0.3;<br />
}<br />
</pre><br />
<br />
You can declare some constants in material.inc.php and pass them to your .js for easy repositioning (modify constant, refresh). This is especially useful if the same constants have to be used on the server and on the client.<br />
<br />
* Declare your constants in material.inc.php (this will be automatically included in your .game.php)<br />
<br />
<pre><br />
$this->gameConstants = array(<br />
"INTERSECTION_WIDTH" => 30,<br />
"INTERSECTION_HEIGHT" => 30, <br />
"INTERSECTION_X_SPACER" => 2.8, // Float<br />
"INTERSECTION_Y_SPACER" => 2.8, // Float<br />
"X_ORIGIN" => 0,<br />
"Y_ORIGIN" => 0,<br />
);<br />
</pre><br />
<br />
* In .game.php->getAllDatas(), add the constants to the result array<br />
<br />
// Constants<br />
$result['constants'] = $this->gameConstants;<br />
<br />
* In .js constructor, define a class variable for constants<br />
<br />
// Game constants<br />
this.gameConstants = null;<br />
<br />
* In .js->setup() assign the constants to this variable<br />
<br />
this.gameConstants = gamedatas.constants;<br />
<br />
* Then use it in your getXPixelCoordinates and getYPixelCoordinates functions<br />
<br />
getXPixelCoordinates: function( intersection_x )<br />
{<br />
return this.gameConstants['X_ORIGIN'] + intersection_x * (this.gameConstants['INTERSECTION_WIDTH'] + this.gameConstants['INTERSECTION_X_SPACER']); <br />
},<br />
<br />
getYPixelCoordinates: function( intersection_y )<br />
{<br />
return this.gameConstants['Y_ORIGIN'] + intersection_y * (this.gameConstants['INTERSECTION_HEIGHT'] + this.gameConstants['INTERSECTION_Y_SPACER']); <br />
},<br />
<br />
Here is what you should get:<br />
<br />
[[File:Gomoku tuto3.png]]<br />
<br />
== Manage states and events ==<br />
<br />
Define your game states in states.inc.php. For gomoku we will use 3 states in addition of the predefined states 1 (gameSetup) and 99 (gameEnd). One to play, one to check the end game condition, one to give his turn to the other player if the game is not over.<br />
<br />
The first state requires an action from the player, so its type is 'activeplayer'.<br />
<br />
The two others are automatic actions for the game, so their type is 'game'.<br />
<br />
We will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.<br />
<br />
<pre><br />
2 => array(<br />
"name" => "playerTurn",<br />
"description" => clienttranslate('${actplayer} must play a stone'),<br />
"descriptionmyturn" => clienttranslate('${you} must play a stone'),<br />
"type" => "activeplayer",<br />
"possibleactions" => array( "playStone" ),<br />
"transitions" => array( "stonePlayed" => 3, "zombiePass" => 3 )<br />
),<br />
<br />
3 => array(<br />
"name" => "checkEndOfGame",<br />
"description" => '',<br />
"type" => "game",<br />
"action" => "stCheckEndOfGame",<br />
"updateGameProgression" => true,<br />
"transitions" => array( "gameEnded" => 99, "notEndedYet" => 4 )<br />
),<br />
<br />
4 => array(<br />
"name" => "nextPlayer",<br />
"description" => '',<br />
"type" => "game",<br />
"action" => "stNextPlayer",<br />
"transitions" => array( "" => 2 )<br />
),<br />
</pre><br />
<br />
Implement the 'stNextPlayer()' function in .game.php to manage turn rotation. Except if there are special rules for the game turn depending on context, this is really easy:<br />
<br />
<pre><br />
function stNextPlayer()<br />
{<br />
self::trace( "stNextPlayer" );<br />
<br />
// Go to next player<br />
$active_player = self::activeNextPlayer();<br />
self::giveExtraTime( $active_player ); <br />
<br />
$this->gamestate->nextState();<br />
}<br />
</pre><br />
<br />
Add onclick events on intersections in .js->setup()<br />
<br />
// Add events on active elements (the third parameter is the method that will be called when the event defined by the second parameter happens - this method must be declared beforehand)<br />
this.addEventToClass( "gmk_intersection", "onclick", "onClickIntersection");<br />
<br />
Declare the corresponding .js->onClickIntersection() function, which calls an action function on the server with appropriate parameters<br />
<br />
<pre><br />
onClickIntersection: function( evt )<br />
{<br />
console.log( '$$$$ Event : onClickIntersection' );<br />
dojo.stopEvent( evt );<br />
<br />
if( ! this.checkAction( 'playStone' ) )<br />
{ return; }<br />
<br />
var node = evt.currentTarget.id;<br />
var coord_x = node.split('_')[1];<br />
var coord_y = node.split('_')[2];<br />
<br />
console.log( '$$$$ Selected intersection : (' + coord_x + ', ' + coord_y + ')' );<br />
<br />
if ( this.isCurrentPlayerActive() ) {<br />
this.ajaxcall( "/gomoku/gomoku/playStone.html", { lock: true, coord_x: coord_x, coord_y: coord_y }, this, function( result ) {}, function( is_error ) {} );<br />
}<br />
},<br />
</pre><br />
<br />
Add this action function in .action.php, retrieving parameters and calling the appropriate game action<br />
<br />
<pre><br />
public function playStone()<br />
{<br />
self::setAjaxMode(); <br />
<br />
// Retrieve arguments<br />
// Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method<br />
$coord_x = self::getArg( "coord_x", AT_posint, true );<br />
$coord_y = self::getArg( "coord_y", AT_posint, true );<br />
<br />
// Then, call the appropriate method in your game logic, like "playCard" or "myAction"<br />
$this->game->playStone( $coord_x, $coord_y );<br />
<br />
self::ajaxResponse( );<br />
}<br />
</pre><br />
<br />
Add game action in .game.php to update the database, send a notification to the client providing the event notified (‘stonePlayed’) and its parameters, and proceed to the next state.<br />
<br />
<pre><br />
function playStone( $coord_x, $coord_y )<br />
{<br />
// Check that this is player's turn and that it is a "possible action" at this game state (see states.inc.php)<br />
self::checkAction( 'playStone' ); <br />
<br />
$player_id = self::getActivePlayerId();<br />
<br />
// Check that this intersection is free<br />
$sql = "SELECT<br />
id, coord_x, coord_y, stone_color<br />
FROM<br />
intersection <br />
WHERE <br />
coord_x = $coord_x <br />
AND coord_y = $coord_y<br />
AND stone_color is null<br />
";<br />
$intersection = self::getObjectFromDb( $sql );<br />
<br />
if ($intersection == null) {<br />
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );<br />
}<br />
<br />
// Get player color<br />
$sql = "SELECT<br />
player_id, player_color<br />
FROM<br />
player <br />
WHERE <br />
player_id = $player_id<br />
";<br />
$player = self::getNonEmptyObjectFromDb( $sql );<br />
$color = ($player['player_color'] == 'ffffff' ? 'white' : 'black');<br />
<br />
// Update the intersection with a stone of the appropriate color<br />
$intersection_id = $intersection['id'];<br />
$sql = "UPDATE<br />
intersection<br />
SET<br />
stone_color = '$color'<br />
WHERE <br />
id = $intersection_id<br />
";<br />
self::DbQuery($sql);<br />
<br />
// Notify all players<br />
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone on ${coord_x},${coord_y}' ), array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'coord_x' => $coord_x,<br />
'coord_y' => $coord_y,<br />
'color' => $color<br />
) );<br />
<br />
// Go to next game state<br />
$this->gamestate->nextState( "stonePlayed" );<br />
}<br />
</pre><br />
<br />
Catch the notification in .js->setupNotifications() and link it to a javascript function to execute when the notification is received.<br />
<br />
<pre><br />
setupNotifications: function()<br />
{<br />
console.log( 'notifications subscriptions setup' );<br />
<br />
dojo.subscribe( 'stonePlayed', this, "notif_stonePlayed" );<br />
}<br />
</pre><br />
<br />
Implement this function in javascript to update the intersection to show the stone, and register it inside the setNotifications function.<br />
<br />
<pre><br />
notif_stonePlayed: function( notif )<br />
{<br />
console.log( '**** Notification : stonePlayed' );<br />
console.log( notif );<br />
<br />
// Create a stone<br />
dojo.place( this.format_block('jstpl_stone', {<br />
stone_type:'stone_' + notif.args.color,<br />
x:notif.args.coord_x,<br />
y:notif.args.coord_y<br />
} ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ) );<br />
<br />
// Place it on the player panel<br />
this.placeOnObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'player_board_' + notif.args.player_id ) );<br />
<br />
// Animate a slide from the player panel to the intersection<br />
dojo.style( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y, 'zIndex', 1 );<br />
var slide = this.slideToObject( $( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y ), $( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y ), 1000 );<br />
dojo.connect( slide, 'onEnd', this, dojo.hitch( this, function() {<br />
// At the end of the slide, update the intersection <br />
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'no_stone' );<br />
dojo.addClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'stone_' + notif.args.color );<br />
dojo.removeClass( 'intersection_' + notif.args.coord_x + '_' + notif.args.coord_y, 'clickable' );<br />
<br />
// We can now destroy the stone since it is now visible through the change in style of the intersection<br />
dojo.destroy( 'stone_' + notif.args.coord_x + '_' + notif.args.coord_y );<br />
}));<br />
slide.play();<br />
},<br />
</pre><br />
<br />
For this function to work properly, you also need: <br />
<br />
* to declare a stone javascript template in your .tpl file.<br />
<br />
<pre><br />
var jstpl_stone='<div class="gmk_stone ${stone_type}" id="stone_${x}_${y}"></div>';<br />
</pre><br />
<br />
* to define the css styles for the stones<br />
<br />
<pre><br />
.gmk_intersection {<br />
width: 30px;<br />
height: 30px;<br />
position: relative;<br />
background-image: url( 'img/stones.png' );<br />
}<br />
<br />
.gmk_stone {<br />
width: 30px;<br />
height: 30px;<br />
position: absolute;<br />
background-image: url( 'img/stones.png' );<br />
}<br />
<br />
.no_stone { background-position: -60px 0px; }<br />
<br />
.stone_black { background-position: 0px 0px; }<br />
.stone_white { background-position: -30px 0px; }<br />
</pre><br />
<br />
These styles rely on an PNG image (with transparent background) of both the white and black stones, and positions the background appropriately to show only the part of the background image matching the appropriate stone (or the transparent space if there is no stone). Here is what the image looks like:<br />
<br />
[[File:Gomoku stones.png]]<br />
<br />
The red circle is used to highlight intersections where you can drop a stone when the player's cursor hovers over them (we also change the cursor to a hand). To do this:<br />
<br />
* we define in the css file the 'clickable' css class<br />
<br />
<pre><br />
.clickable {<br />
cursor: pointer;<br />
}<br />
.clickable:hover { background-position: -90px 0px; }<br />
</pre><br />
<br />
* in .js, when we enter the 'playerTurn' state, we add the 'clickable' style to the intersections where there is no stone<br />
<br />
<pre><br />
onEnteringState: function( stateName, args )<br />
{<br />
console.log( 'Entering state: '+stateName );<br />
<br />
switch( stateName )<br />
{<br />
<br />
case 'playerTurn':<br />
if( this.isCurrentPlayerActive() )<br />
{<br />
var queueEntries = dojo.query( '.no_stone' );<br />
for(var i=0; i<queueEntries.length; i++) { <br />
dojo.addClass( queueEntries[i], 'clickable' );<br />
}<br />
} <br />
}<br />
},<br />
</pre><br />
<br />
Finally, make sure to modify the default colors for players to white and black<br />
<br />
$default_colors = array( "000000", "ffffff", );<br />
<br />
The basic game turn is implemented: you can now drop some stones!<br />
<br />
[[File:Gomoku tuto4.png]]<br />
<br />
== Cleanup your styles ==<br />
<br />
Remove temporary css visualisation helpers : looks good!<br />
<br />
[[File:Gomoku tuto5.png]]<br />
<br />
== Add some counters in the player panels ==<br />
<br />
Edit .tpl to create a template for your counters.<br />
<br />
<pre><br />
var jstpl_player_board = '\<div class="cp_board">\<br />
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\<br />
</div>';<br />
</pre><br />
<br />
Edit .js->setup() to setup the player panels with this extra information<br />
<br />
<pre><br />
// Setting up player boards<br />
for( var player_id in gamedatas.players )<br />
{<br />
var player = gamedatas.players[player_id];<br />
<br />
// Setting up players boards if needed<br />
var player_board_div = $('player_board_'+player_id);<br />
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );<br />
}<br />
</pre><br />
<br />
Add some styles in your .css<br />
<br />
<pre><br />
.gmk_stoneicon {<br />
width: 14px;<br />
height: 14px;<br />
display: inline-block;<br />
position: relative;<br />
background-repeat: no-repeat;<br />
background-image: url( 'img/stone_icons.png');<br />
background-position: -28px 0px;<br />
margin-top: 4px;<br />
margin-right: 3px;<br />
}<br />
<br />
.gmk_stoneicon_000000 {<br />
background-position:0px 0px<br />
}<br />
<br />
.gmk_stoneicon_ffffff {<br />
background-position:-14px 0px<br />
}<br />
<br />
.cp_board {<br />
clear: both;<br />
}<br />
</pre><br />
<br />
In your .game.php, create a function to return your game counters<br />
<br />
<pre><br />
/*<br />
getGameCounters:<br />
<br />
Gather all relevant counters about current game situation (visible by the current player).<br />
*/<br />
function getGameCounters($player_id) {<br />
$sql = "<br />
SELECT<br />
concat('stonecount_p', cast(p.player_id as char)) counter_name,<br />
case when p.player_color = 'white' then 180 - count(id) else 181 - count(id) end counter_value<br />
FROM (select player_id, case when player_color = 'ffffff' then 'white' else 'black' end player_color FROM player) p<br />
LEFT JOIN intersection i on i.stone_color = p.player_color<br />
GROUP BY p.player_color, p.player_id<br />
";<br />
if ($player_id != null) {<br />
// Player private counters: concatenate extra SQL request with UNION using the $player_id parameter<br />
}<br />
<br />
return self::getNonEmptyCollectionFromDB( $sql );<br />
}<br />
</pre><br />
<br />
Return your game counters in your .game.php->getAllDatas()<br />
<br />
<pre><br />
// Counters<br />
$result['counters'] = $this->getGameCounters($current_player_id);<br />
</pre><br />
<br />
And pass them in any notification that needs to update them<br />
<br />
<pre><br />
// Notify all players<br />
self::notifyAllPlayers( "stonePlayed", clienttranslate( '${player_name} dropped a stone ${coordinates}' ), array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'coordinates' => $this->getFormattedCoordinates($coord_x, $coord_y),<br />
'coord_x' => $coord_x,<br />
'coord_y' => $coord_y,<br />
'color' => $color,<br />
'counters' => $this->getGameCounters(self::getCurrentPlayerId())<br />
) );<br />
</pre><br />
<br />
Finally, in your .js->setup() and notification handler function call respectively<br />
<br />
<pre><br />
this.updateCounters(gamedatas.counters);<br />
</pre><br />
<br />
and<br />
<br />
<pre><br />
this.updateCounters(notif.args.counters);<br />
</pre><br />
<br />
You now have a working counter!<br />
<br />
[[File:Gomoku tuto7.png]]<br />
<br />
== Implement rules and end of game conditions ==<br />
<br />
Implement specific rules for the game. For example in Gomoku, black plays first. So in .game.php->setupNewGame(), at the end of the setup make the black player active:<br />
<br />
<pre><br />
// Black plays first<br />
$sql = "SELECT player_id, player_name FROM player WHERE player_color = '000000' ";<br />
$black_player = self::getNonEmptyObjectFromDb( $sql );<br />
<br />
$this->gamestate->changeActivePlayer( $black_player['player_id'] );<br />
</pre><br />
<br />
Implement rule for computing game progression in .game.php->getGameProgression(). For Gomoku we will use the rate of occupied intersections over the total number of intersections. This will often be wildly inaccurate as the game can end pretty quickly, but it's about the best we can do (the game can drag to a stalemate with all intersections occupied and no winner).<br />
<br />
<pre><br />
function getGameProgression()<br />
{<br />
// Compute and return the game progression<br />
<br />
// Number of stones laid down on the goban over the total number of intersections * 100<br />
$sql = "<br />
SELECT round(100 * count(id) / (19*19) ) as value from intersection WHERE stone_color is not null<br />
";<br />
$counter = self::getNonEmptyObjectFromDB( $sql );<br />
<br />
return $counter['value'];<br />
}<br />
</pre><br />
<br />
Implement end of game detection and update the score according to who is the winner. It is easier to check for a win directly after setting the stone, so: <br />
<br />
* declare a global 'end_of_game' variable in .game.php->Gomoku()<br />
<br />
self::initGameStateLabels( array(<br />
"end_of_game" => 10,<br />
) );<br />
<br />
* init that global variable to 0 in .game.php->setupNewGame()<br />
<br />
self::setGameStateInitialValue( 'end_of_game', 0 );<br />
<br />
* add the appropriate code in .game.php before proceeding to the next state, using a checkForWin() function implemented separately for clarity. If the game has been won, we set the score, send a score update notification to the client side, and set the 'end_of_game' global variable to 1 as a flag signaling that the game has ended.<br />
<br />
<pre><br />
// Check if end of game has been met<br />
if ($this->checkForWin( $coord_x, $coord_y, $color )) {<br />
<br />
// Set active player score to 1 (he is the winner)<br />
$sql = "UPDATE player SET player_score = 1 WHERE player_id = $player_id";<br />
self::DbQuery($sql);<br />
<br />
// Notify final score<br />
$this->notifyAllPlayers( "finalScore",<br />
clienttranslate( '${player_name} wins the game!' ),<br />
array(<br />
"player_name" => self::getActivePlayerName(),<br />
"player_id" => $player_id,<br />
"score_delta" => 1,<br />
)<br />
);<br />
<br />
// Set global variable flag to pass on the information that the game has ended<br />
self::setGameStateValue('end_of_game', 1);<br />
<br />
// End of game message<br />
$this->notifyAllPlayers( "message",<br />
clienttranslate('Thanks for playing!'),<br />
array(<br />
)<br />
);<br />
<br />
}<br />
</pre><br />
<br />
* Then in the gomoku->stCheckEndOfGame() function which is called when your state machine goes to the 'checkEndOfGame' state, check for this variable and for other possible 'end of game' conditions (draw).<br />
<br />
<pre><br />
function stCheckEndOfGame()<br />
{<br />
self::trace( "stCheckEndOfGame" );<br />
<br />
$transition = "notEndedYet";<br />
<br />
// If there is no more free intersections, the game ends<br />
$sql = "SELECT id, coord_x, coord_y, stone_color FROM intersection WHERE stone_color is null";<br />
$free = self::getCollectionFromDb( $sql );<br />
<br />
if (count($free) == 0) {<br />
$transition = "gameEnded";<br />
} <br />
<br />
// If the 'end of game' flag has been set, end the game<br />
if (self::getGameStateValue('end_of_game') == 1) {<br />
$transition = "gameEnded";<br />
}<br />
<br />
$this->gamestate->nextState( $transition );<br />
}<br />
</pre><br />
<br />
* Catch the score notification on the client side in .js->setupNotifications(). It is advised to set up a small delay after that so that end of game popup doesn't show too quickly.<br />
<br />
<pre><br />
dojo.subscribe( 'finalScore', this, "notif_finalScore" );<br />
this.notifqueue.setSynchronous( 'finalScore', 1500 );<br />
</pre><br />
<br />
* Implement the function declared to handle the notification.<br />
<br />
<pre><br />
notif_finalScore: function( notif )<br />
{<br />
console.log( '**** Notification : finalScore' );<br />
console.log( notif );<br />
<br />
// Update score<br />
this.scoreCtrl[ notif.args.player_id ].incValue( notif.args.score_delta );<br />
},<br />
</pre><br />
<br />
'''Test everything thoroughly... you are done!'''<br />
<br />
[[File:Gomoku tuto6.png]]</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Tutorial_reversi&diff=4035
Tutorial reversi
2020-04-15T21:13:45Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
== Introduction ==<br />
<br />
Using this tutorial, you can build a complete working game on the BGA environment: Reversi.<br />
<br />
Before you read this tutorial, you must:<br />
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).<br />
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].<br />
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript<br />
* Setup your development environment [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]<br />
<br />
== Create your first game ==<br />
<br />
With the initial skeleton of code provided initially, you can already start a game from the BGA Studio. For now, we are going to work with 1 player only. 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.<br />
<br />
Thus, you can start a "Reversi" game, and arrive on a void, empty game. Yeah.<br />
<br />
== Let it look like Reversi ==<br />
<br />
It's always a good idea to start with a little bit of graphic work. Why? Because this helps to figure out how the final game will be, and issues that may appear later.<br />
<br />
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).<br />
<br />
For Reversi, it's useless to have a 750x750px board - much too big, so we choose this one which fit perfectly (536x528):<br />
<br />
[[File:Board.jpg]]<br />
<br />
Note that we are using a jpg file. Jpg are lighter than png, so faster to load. Later we are going to use PNGs for discs for transparency purpose.<br />
<br />
Now, let's make it appears on our game:<br />
* upload board.jpg in your "img/" directory.<br />
* edit "reversi_reversi.tpl" to add a 'div' for your board:<br />
<br />
<pre><br />
<div id="board"><br />
</div><br />
</pre><br />
<br />
* edit your reversi.css file to transform it into a visible board:<br />
<br />
#board {<br />
width: 536px;<br />
height: 528px;<br />
background-image: url('img/board.jpg');<br />
}<br />
<br />
Refresh your page. Here's your board:<br />
<br />
[[File:reversi1.jpg]]<br />
<br />
== Make the squares appears ==<br />
<br />
Now, what we need is to create some invisible HTML elements where squares are. These elements will be used as position references for white and black discs. <br />
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.<br />
<br />
Let's modify our template like this:<br />
<br />
<pre><br />
<div id="board"><br />
<!-- BEGIN square --><br />
<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div><br />
<!-- END square --><br />
</div><br />
</pre><br />
<br />
As you can see, we created a "square" block, with 4 variable elements: X, Y, LEFT and TOP. Obviously, we are going to use this block 64 times during page load.<br />
<br />
Let's do it in our "reversi.view.php" file:<br />
<br />
<pre><br />
$this->page->begin_block( "reversi_reversi", "square" );<br />
<br />
$hor_scale = 64.8;<br />
$ver_scale = 64.4;<br />
for( $x=1; $x<=8; $x++ )<br />
{<br />
for( $y=1; $y<=8; $y++ )<br />
{<br />
$this->page->insert_block( "square", array(<br />
'X' => $x,<br />
'Y' => $y,<br />
'LEFT' => round( ($x-1)*$hor_scale+10 ),<br />
'TOP' => round( ($y-1)*$ver_scale+7 )<br />
) );<br />
} <br />
}<br />
</pre><br />
<br />
Note: as you can see, squares in our "board.jpg" files does not have an exact width/height in pixel, and that's the reason we are using floating point numbers here.<br />
<br />
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:<br />
<br />
<pre><br />
#board {<br />
width: 536px;<br />
height: 528px;<br />
background-image: url('img/board.jpg');<br />
position: relative;<br />
}<br />
<br />
.square {<br />
width: 62px;<br />
height: 62px;<br />
position: absolute;<br />
background-color: red;<br />
}<br />
</pre><br />
<br />
Explanations:<br />
* With "position: relative" on board, we ensure square elements are positioned relatively to board.<br />
* For the test, we use a red background color for the square. This is a useful tip to figure out if everything is fine with invisible elements.<br />
<br />
Let's refresh and check our our (beautiful) squares:<br />
<br />
[[File:reversi2.jpg]]<br />
<br />
== The discs ==<br />
<br />
Now, our board is ready to receive some disc tokens!<br />
<br />
[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.]<br />
<br />
At first, we introduce a new 'div' element as a child of "board" to host all these tokens (in our template):<br />
<br />
<pre><br />
<!-- END square --><br />
<br />
<div id="tokens"><br />
</div><br />
</div><br />
</pre><br />
<br />
Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:<br />
<br />
[[File:tokens.png]]<br />
<br />
Upload this image file "tokens.png" in your "img/" directory.<br />
<br />
Important: we are using ONE file for both discs. It's really important that you use a minimum number of graphic files for your game with this "CSS sprite" technique, because it makes the game loading faster and more reliable. [http://www.w3schools.com/css/css_image_sprites.asp Read more about CSS sprites].<br />
<br />
Now, let's separate the disc with some CSS stuff:<br />
<br />
<pre><br />
.token {<br />
width: 56px;<br />
height: 56px;<br />
position: absolute;<br />
background-image: url('img/tokens.png');<br />
}<br />
.tokencolor_ffffff { background-position: 0px 0px; }<br />
.tokencolor_000000 { background-position: -56px 0px; }<br />
</pre><br />
<br />
With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.<br />
<br />
Note the "position: absolute" which allows us to position tokens on the board and make them "slide" to their positions.<br />
<br />
Now, let's make a first token appear on our board. Disc 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".<br />
<br />
In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:<br />
<br />
<pre><br />
<script type="text/javascript"><br />
<br />
// Templates<br />
<br />
var jstpl_token='<div class="token tokencolor_${color}" id="token_${x_y}"></div>';<br />
<br />
</script><br />
</pre><br />
<br />
Note: we already created the "templates" section for you in the game skeleton.<br />
<br />
As you can see, we defined a JS template named "jstpl_token" 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 (brackets) and JS template variables (dollar and brackets).<br />
<br />
Now, let's create a method in our Javascript code (in the "reversi.js" file) that will make a token appear on the board, using this template:<br />
<br />
<pre><br />
addTokenOnBoard: function( x, y, player )<br />
{<br />
dojo.place( this.format_block( 'jstpl_token', {<br />
x_y: x+'_'+y,<br />
color: this.gamedatas.players[ player ].color<br />
} ) , 'tokens' );<br />
<br />
this.placeOnObject( 'token_'+x+'_'+y, 'overall_player_board_'+player );<br />
this.slideToObject( 'token_'+x+'_'+y, 'square_'+x+'_'+y ).play();<br />
},<br />
</pre><br />
<br />
At first, with "dojo.place" and "this.format_block" methods, we create a HTML piece of code and insert it as a new child of "tokens" div element.<br />
<br />
Then, with BGA "this.placeOnObject" method, we place this element over the panel of some player. Immediately after, using BGA "this.slideToObject" method, we make the disc slide to the "square" element, its final destination.<br />
<br />
Note: don't forget to call the "play()", otherwise the token remains at its original location.<br />
<br />
Note: note that during all the process, the parent of the new disc HTML element will remain "tokens". placeOnObject and slideToObject methods are only moving the position of elements on screen, and they are not modifying the HTML tree.<br />
<br />
Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:<br />
<pre><br />
$default_colors = array( "ffffff", "000000" );<br />
</pre><br />
<br />
Now, to test if everything works fine, just add "this.addTokenOnBoard( 2, 2, [player_id] )" in the "setup" Javascript method in reversi.js, and reload the page.<br />
<br />
<br />
A token should appear and slide immediately to its position, like this:<br />
<br />
[[File:reversi3.jpg]]<br />
<br />
== The database ==<br />
<br />
We did most of the client-side programming, so let's have a look on the other side now.<br />
<br />
To design the database model of our game, the best thing to do is to follow the "Go to game database" link at the bottom of our game, to access the database directly with a [http://www.phpmyadmin.net/ PhpMyAdmin] instance.<br />
<br />
Then, you can create the tables you need for your table (do not remove existing tables!), and report every SQL command used in your "dbmodel.sql" file.<br />
<br />
[[File:reversi4.jpg]]<br />
<br />
The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:<br />
<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `board` (<br />
`board_x` smallint(5) unsigned NOT NULL,<br />
`board_y` smallint(5) unsigned NOT NULL,<br />
`board_player` int(10) unsigned DEFAULT NULL,<br />
PRIMARY KEY (`board_x`,`board_y`)<br />
) ENGINE=InnoDB;<br />
</pre><br />
<br />
Now, a new database with a "board" table will be created each time we start a Reversi game. This is why after modifying our dbmodel.sql it's a good time to stop & start again our game.<br />
<br />
== Setup the initial game position ==<br />
<br />
The "setupNewGame" method of our reversi.game.php is called during initial setup: this is the place to initialize our data and to place the initial tokens on the board (initially, there are 4 tokens on the board).<br />
<br />
Let's do this:<br />
<br />
<pre><br />
// Init the board<br />
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";<br />
$sql_values = array();<br />
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );<br />
for( $x=1; $x<=8; $x++ )<br />
{<br />
for( $y=1; $y<=8; $y++ )<br />
{<br />
$token_value = "NULL";<br />
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player<br />
$token_value = "'$whiteplayer_id'";<br />
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player<br />
$token_value = "'$blackplayer_id'";<br />
<br />
$sql_values[] = "('$x','$y',$token_value)";<br />
}<br />
}<br />
$sql .= implode( $sql_values, ',' );<br />
self::DbQuery( $sql );<br />
<br />
<br />
// Active first player<br />
self::activeNextPlayer(); <br />
</pre><br />
<br />
As you can see, we create one table entry for each square, with a "NULL" value which means "empty square". Of course, for 4 specific squares, we place an initial token.<br />
<br />
At the end, we call activeNextPlayer to make the first player active at the beginning of the game.<br />
<br />
Now, we need to make these tokens appear on the client side. To achieve this, the first step is to return the token positions with our "getAllDatas" PHP method (called during each page reload):<br />
<br />
<pre><br />
// Get reversi board token<br />
$result['board'] = self::getObjectListFromDB( "SELECT board_x x, board_y y, board_player player<br />
FROM board<br />
WHERE board_player IS NOT NULL" );<br />
</pre><br />
<br />
As you can see, we are using the BGA framework "getObjectListFromDB" method that formats the result of this SQL query in a PHP array with x, y and player attributes.<br />
<br />
The last thing we need to do is to process this array client side, and place a disc token on the board for each array item. Of course, we are doing this is our Javascript "setup" method:<br />
<br />
<pre><br />
for( var i in gamedatas.board )<br />
{<br />
var square = gamedatas.board[i];<br />
<br />
if( square.player !== null )<br />
{<br />
this.addTokenOnBoard( square.x, square.y, square.player );<br />
}<br />
}<br />
</pre><br />
<br />
As you can see, our "board" entry created in "getAllDatas" can be used here as "gamedatas.board" in our Javascript. We are using our previously developed "addTokenOnBoard" method.<br />
<br />
Reload... and here we are:<br />
<br />
[[File:reversi5.jpg]]<br />
<br />
It starts to smell Reversi here...<br />
<br />
== The game state machine ==<br />
<br />
Now, let's stop our game again, because we are going to start the core game logic.<br />
<br />
You already read the "Focus on BGA game state machine", so you know that this is the heart of your game logic. For reversi, it's very simple. Here's a diagram of our game state machine:<br />
<br />
[[File:reversi6.jpg]]<br />
<br />
And here's our "states.inc.php", according to this diagram:<br />
<br />
<pre><br />
$machinestates = array(<br />
<br />
1 => array(<br />
"name" => "gameSetup",<br />
"description" => clienttranslate("Game setup"),<br />
"type" => "manager",<br />
"action" => "stGameSetup",<br />
"transitions" => array( "" => 10 )<br />
),<br />
<br />
10 => array(<br />
"name" => "playerTurn",<br />
"description" => clienttranslate('${actplayer} must play a disc'),<br />
"descriptionmyturn" => clienttranslate('${you} must play a disc'),<br />
"type" => "activeplayer",<br />
"args" => "argPlayerTurn",<br />
"possibleactions" => array( 'playDisc' ),<br />
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )<br />
),<br />
<br />
11 => array(<br />
"name" => "nextPlayer",<br />
"type" => "game",<br />
"action" => "stNextPlayer",<br />
"updateGameProgression" => true, <br />
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )<br />
),<br />
<br />
99 => array(<br />
"name" => "gameEnd",<br />
"description" => clienttranslate("End of game"),<br />
"type" => "manager",<br />
"action" => "stGameEnd",<br />
"args" => "argGameEnd"<br />
)<br />
<br />
);<br />
</pre><br />
<br />
Now, let's create in reversi.game.php the methods that are declared in this game states description file:<br />
* argPlayerTurn<br />
* stNextPlayer<br />
<br />
... and start a new Reversi game.<br />
<br />
As you can see on the screen capture below, the BGA framework makes the game jump to our first game state "playerTurn" right after the initial setup. That's why the status bar contains the description of playerTurn state ("XXXX must play a disc"):<br />
<br />
[[File:reversi7.jpg]]<br />
<br />
== The rules ==<br />
<br />
Now, what we would like to do is to indicate to the current player where she is allowed to play. The idea is to build a "getPossibleMoves" PHP method that return a list of coordinates where she is allowed to play. This method will be used in particular:<br />
* As we just said, to help the player to see where she can play.<br />
* When the player plays, to check if she has the right to play here.<br />
<br />
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:<br />
* Create a "getTurnedOverDiscs(x,y)" method that return coordinates of discs that would be turned over if a token would be played at x,y.<br />
* Loop through all free squares of the board, call the "getTurnedOverDiscs" method on each of them. If at least 1 token is turned over, this is a valid move.<br />
<br />
One important thing to keep in mind is the following: making a database query is slow, so please don't load the entire game board with a SQL query multiple time. In our implementation, we load the entire board once at the beginning of "getPossibleMoves", and then pass the board as an argument to all methods.<br />
<br />
If you want to look into details, please look at the "utility method" sections of reversi.game.php.<br />
<br />
== Display allowed moves ==<br />
<br />
Now, what we want to do is highlight the squares where the player can place a disc.<br />
<br />
To do this, we are using the "argPlayerTurn" method. This method is called each time we enter into "playerTurn" game state, and its result is transfered automatically to the client-side:<br />
<br />
<pre><br />
<br />
function argPlayerTurn()<br />
{<br />
return array(<br />
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )<br />
);<br />
}<br />
</pre><br />
<br />
We are of course using the "getPossibleMoves" method we just developed.<br />
<br />
Now, let's go to the client side to use the data returned by the method above. We are using the "onEnteringState" Javascript method that is called each time we enter into a new game state:<br />
<br />
<pre><br />
onEnteringState: function( stateName, args )<br />
{<br />
console.log( 'Entering state: '+stateName );<br />
<br />
switch( stateName )<br />
{<br />
case 'playerTurn':<br />
this.updatePossibleMoves( args.args.possibleMoves );<br />
break;<br />
}<br />
},<br />
</pre><br />
<br />
So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:<br />
<br />
<pre><br />
updatePossibleMoves: function( possibleMoves )<br />
{<br />
// Remove current possible moves<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );<br />
<br />
for( var x in possibleMoves )<br />
{<br />
for( var y in possibleMoves[ x ] )<br />
{<br />
// x,y is a possible move<br />
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );<br />
} <br />
}<br />
<br />
this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );<br />
},<br />
</pre><br />
<br />
The idea here is that we've created a CSS class ("possibleMove") that can be applied to a "square" element to highlight it:<br />
<pre><br />
.possibleMove {<br />
background-color: white;<br />
opacity: 0.2;<br />
filter:alpha(opacity=20); /* For IE8 and earlier */ <br />
cursor: pointer; <br />
}<br />
</pre><br />
<br />
At first, we remove all "possibleMove" classes currently applied with the very useful combination of "dojo.query" and "removeClass" method.<br />
<br />
Then we loop through all possible moves our PHP "updatePossibleMoves" function created for us, and add the "possibleMove" class to each corresponding square.<br />
<br />
Finally, we use the BGA framework "addTooltipToClass" method to associate a tooltip to all those highlighted squares so that players can understand their meaning.<br />
<br />
And here we are:<br />
<br />
[[File:reversi8.jpg.jpg]]<br />
<br />
== Let's play ==<br />
<br />
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:<br />
* When we click on a "possibleMoves" square, send the move to the server.<br />
* Server side, check the move is correct, apply Reversi rules and jump to next player.<br />
* Client side, change the disc position to reflect the move.<br />
<br />
Thus, what we do first is associate each click on a square to one of our method. We are doing this in our Javascript "setup" method:<br />
<br />
<pre><br />
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );<br />
</pre><br />
<br />
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.<br />
<br />
Here's our "onPlayDisc" method below:<br />
<br />
<pre><br />
onPlayDisc: function( evt )<br />
{<br />
// Stop this event propagation<br />
dojo.stopEvent( evt );<br />
<br />
// Get the cliqued square x and y<br />
// Note: square id format is "square_X_Y"<br />
var coords = evt.currentTarget.id.split('_');<br />
var x = coords[1];<br />
var y = coords[2];<br />
<br />
if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMoves' ) )<br />
{<br />
// This is not a possible move => the click does nothing<br />
return ;<br />
}<br />
<br />
if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment<br />
{ <br />
this.ajaxcall( "/reversi/reversi/playDisc.html", {<br />
x:x,<br />
y:y<br />
}, this, function( result ) {} );<br />
} <br />
},<br />
</pre><br />
<br />
What we do here is:<br />
* We stop the propagation of the Javascript "onclick" event. Otherwise, it can lead to random behavior so it's always a good idea.<br />
* We get the x/y coordinates of the square by using "evt.currentTarget.id".<br />
* We check that clicked square has the "possibleMoves" class, otherwise we know for sure that we can't play there.<br />
* We check that "playDisc" action is possible, according to current game state (see "possibleactions" entry in our "playerTurn" game state defined above). This check is important to avoid issues if a player double clicks on a square.<br />
* Finally, we make a call to the server using BGA "ajaxcall" method with argument x and y.<br />
<br />
Now, we have to manage this "playDisc" action on the server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":<br />
<br />
<pre><br />
public function playDisc()<br />
{<br />
self::setAjaxMode(); <br />
$x = self::getArg( "x", AT_posint, true );<br />
$y = self::getArg( "y", AT_posint, true );<br />
$result = $this->game->playDisc( $x, $y );<br />
self::ajaxResponse( );<br />
}<br />
</pre><br />
<br />
As you can see, we get the 2 arguments x and y from the javascript call, and call a corresponding "playDisc" method in our game logic.<br />
<br />
Now, let's have a look of this playDisc method:<br />
<br />
<pre><br />
function playDisc( $x, $y )<br />
{<br />
// Check that this player is active and that this action is possible at this moment<br />
self::checkAction( 'playDisc' ); <br />
</pre><br />
<br />
... 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).<br />
<br />
<pre><br />
// Now, check if this is a possible move<br />
$board = self::getBoard();<br />
$player_id = self::getActivePlayerId();<br />
$turnedOverDiscs = self::getTurnedOverDiscs( $x, $y, $player_id, $board );<br />
<br />
if( count( $turnedOverDiscs ) > 0 )<br />
{<br />
// This move is possible!<br />
</pre><br />
<br />
...now, we are using the "getTurnedOverDiscs" method again to check that this move is possible.<br />
<br />
<pre><br />
// Let's place a disc at x,y and return all "$returned" discs to the active player<br />
<br />
$sql = "UPDATE board SET board_player='$player_id'<br />
WHERE ( board_x, board_y) IN ( ";<br />
<br />
foreach( $turnedOverDiscs as $turnedOver )<br />
{<br />
$sql .= "('".$turnedOver['x']."','".$turnedOver['y']."'),";<br />
}<br />
$sql .= "('$x','$y') ) ";<br />
<br />
self::DbQuery( $sql );<br />
<br />
</pre><br />
<br />
... we update the database to change the color of all turned over disc + the disc we just placed.<br />
<br />
<pre><br />
// Update scores according to the number of disc on board<br />
$sql = "UPDATE player<br />
SET player_score = (<br />
SELECT COUNT( board_x ) FROM board WHERE board_player=player_id<br />
)";<br />
self::DbQuery( $sql );<br />
<br />
// Statistics<br />
self::incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );<br />
if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )<br />
self::incStat( 1, 'discPlayedOnCorner', $player_id );<br />
else if( $x==1 || $x==8 || $y==1 || $y==8 )<br />
self::incStat( 1, 'discPlayedOnBorder', $player_id );<br />
else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )<br />
self::incStat( 1, 'discPlayedOnCenter', $player_id );<br />
<br />
</pre><br />
<br />
... now, we update both player score by counting all disc, and we manage game statistics.<br />
<br />
<pre><br />
// Notify<br />
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ), array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'returned_nbr' => count( $turnedOverDiscs ),<br />
'x' => $x,<br />
'y' => $y<br />
) );<br />
<br />
self::notifyAllPlayers( "turnOverDiscs", '', array(<br />
'player_id' => $player_id,<br />
'turnedOver' => $turnedOverDiscs<br />
) );<br />
<br />
$newScores = self::getCollectionFromDb( "SELECT player_id, player_score FROM player", true );<br />
self::notifyAllPlayers( "newScores", "", array(<br />
"scores" => $newScores<br />
) );<br />
</pre><br />
<br />
... then we notify about all these changes. We are using for that 3 notifications ('playDisc', 'turnOverDiscs' and 'newScores' that we are going to implement on client side later). Note that the description of the 'playDisc' notification will be logged in the game log.<br />
<br />
<pre><br />
// Then, go to the next state<br />
$this->gamestate->nextState( 'playDisc' );<br />
}<br />
else<br />
throw new feException( "Impossible move" );<br />
}<br />
</pre><br />
<br />
... finally, we jump to the next game state if everything goes fine ('playDisc' is also the name of a transition in the 'playerTurn' game state description above).<br />
To make the statistics work, we have to initialize them in stats.inc.php:<br />
<br />
<pre><br />
// Statistics existing for each player<br />
"player" => array(<br />
<br />
"discPlayedOnCorner" => array( "id"=> 10,<br />
"name" => totranslate("Discs played on a corner"), <br />
"type" => "int" ),<br />
<br />
"discPlayedOnBorder" => array( "id"=> 11,<br />
"name" => totranslate("Discs played on a border"), <br />
"type" => "int" ),<br />
<br />
"discPlayedOnCenter" => array( "id"=> 12,<br />
"name" => totranslate("Discs played on board center part"), <br />
"type" => "int" ),<br />
<br />
"turnedOver" => array( "id"=> 13,<br />
"name" => totranslate("Number of discs turned over"), <br />
"type" => "int" ) <br />
)<br />
</pre><br />
<br />
A last thing to do on the server side is to activate the next player when we enter the "nextPlayer" game state:<br />
<br />
<pre><br />
function stNextPlayer()<br />
{<br />
// Activate next player<br />
$player_id = self::activeNextPlayer();<br />
<br />
self::giveExtraTime( $player_id );<br />
$this->gamestate->nextState( 'nextTurn' );<br />
<br />
}<br />
</pre><br />
<br />
Now, when we play a disc, the rules are checked and the disc appears in the database.<br />
<br />
[[File:reversi9.jpg]]<br />
<br />
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.<br />
<br />
== Make the move appear automatically ==<br />
<br />
Now, what we have to do is process the notifications sent by the server and make the move appear on the interface.<br />
<br />
In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):<br />
<br />
<pre><br />
dojo.subscribe( 'playDisc', this, "notif_playDisc" );<br />
this.notifqueue.setSynchronous( 'playDisc', 500 );<br />
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );<br />
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );<br />
dojo.subscribe( 'newScores', this, "notif_newScores" );<br />
this.notifqueue.setSynchronous( 'newScores', 500 );<br />
</pre><br />
<br />
As you can see, we associate our 2 notifications with 2 methods with the "notif_" prefix. At the same time, we define these notifications as "synchronous", with a duration in millisecond (500 for the first one, and 1500 for the second one). 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:<br />
* Make a disc slide from the player panel to its place on the board<br />
* (wait 500ms)<br />
* Make all turned over discs blink (and of course turned them over)<br />
* (wait 1500ms)<br />
* Let the next player play.<br />
<br />
Let's have a look now on the "playDisc" notification handler method:<br />
<br />
<pre><br />
notif_playDisc: function( notif )<br />
{<br />
// Remove current possible moves (makes the board more clear)<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' ); <br />
<br />
this.addTokenOnBoard( notif.args.x, notif.args.y, notif.args.player_id );<br />
},<br />
</pre><br />
<br />
No surprise here, we re-used some existing stuff to:<br />
* Remove the highlighted squares.<br />
* Add a new disc on board, coming from player panel.<br />
<br />
Now, here's the method that handles the turnOverDiscs notification:<br />
<br />
<pre><br />
notif_turnOverDiscs: function( notif )<br />
{<br />
// Get the color of the player who is returning the discs<br />
var targetColor = this.gamedatas.players[ notif.args.player_id ].color;<br />
<br />
// Make these discs blink and set them to the specified color<br />
for( var i in notif.args.turnedOver )<br />
{<br />
var token = notif.args.turnedOver[ i ];<br />
<br />
// Make the token blink 2 times<br />
var anim = dojo.fx.chain( [<br />
dojo.fadeOut( { node: 'token_'+token.x+'_'+token.y } ),<br />
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } ),<br />
dojo.fadeOut( { <br />
node: 'token_'+token.x+'_'+token.y,<br />
onEnd: function( node ) {<br />
<br />
// Remove any color class<br />
dojo.removeClass( node, [ 'tokencolor_000000', 'tokencolor_ffffff' ] );<br />
// ... and add the good one<br />
dojo.addClass( node, 'tokencolor_'+targetColor );<br />
<br />
} <br />
} ),<br />
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } )<br />
<br />
] ); // end of dojo.fx.chain<br />
<br />
// ... and launch the animation<br />
anim.play(); <br />
}<br />
},<br />
</pre><br />
<br />
The list of the discs to be turned over has been made available by our server side code in "notif.args.turnedOver" (see previous paragraph). We loop through all these discs, and create a complex animation using dojo.Animation for each of them. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].<br />
<br />
And Also the notification to update the scores:<br />
<br />
<pre><br />
notif_newScores: function( notif )<br />
{<br />
for( var player_id in notif.args.scores )<br />
{<br />
var newScore = notif.args.scores[ player_id ];<br />
this.scoreCtrl[ player_id ].toValue( newScore );<br />
}<br />
},<br />
</pre><br />
<br />
<br />
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 "play()".</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=First_steps_with_BGA_Studio&diff=4034
First steps with BGA Studio
2020-04-15T21:12:23Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
== Connect to the BGA Studio website ==<br />
<br />
Go to BGA Studio website:<br />
http://en.studio.boardgamearena.com<br />
<br />
Choose one of your 10 accounts (ex: myusername0), and login into the website - as you would do for Board Game Arena.<br />
<br />
If you don't have account see [[How to join BGA developer team?]]<br />
<br />
<br />
== Create a new game project ==<br />
<br />
You can do most of projects-related operation from "Control Panel / Manage games". In particular, you can create a new project automatically from there.<br />
<br />
You first "game" should be one of the tutorials, so your project name should be something like "tutorialbob".<br />
<br />
At this stage it is too early to create a real game but if you really don't want to start until you have a game in mind, check [[Create a game in BGA Studio: Complete Walkthrough]]<br />
section "Select a First Game"<br />
<br />
For reference top bar studio links<br />
* AVAILABLE LICENSES - list of all available licenses (not public domain) - http://en.studio.boardgamearena.com/#!licensing<br />
* STUDIO PROJECTS - list of all registered studio projects - http://en.studio.boardgamearena.com/#!projects <br />
* CONTROL PANEL - manage projects - http://en.studio.boardgamearena.com/#!controlpanel<br />
<br />
== Connect to your SFTP folder == <br />
<br />
From the initial email from the Studio you get:<br />
* the name of the SFTP server to connect to<br />
* your SFTP login and password<br />
<br />
Using this information:<br />
# Connect to the SFTP server using your SFTP login and password, through your favourite SFTP client software (such as [http://winscp.net/ WinSCP], see [[Tools_and_tips_of_BGA_Studio#File_Sync_on_Windows|File Sync]])<br />
# Check that your remote home folder contains one folder for each of the three example games (reversi, hearts, gomoku). If you have already created a new game project, one additional folder should be in your "home" folder.<br />
# Note: You have to setup AUTOMATED sync between your folder and remote folder, manually ftp'ing files would be no-starter. For WinSCP you can do this from the file menu (Commands->Keep remote directories up to Date...)<br />
<br />
== Let's code! ==<br />
<br />
Now, you can try to launch a new game on BGA Studio from the "Play now" menu entry, as you would do on Board Game Arena website.<br />
<br />
# Find your game in the 'PLAY NOW' section and create a table<br />
# Use the 'I want between X and X' players to tick down the maximum players number to the minimum<br />
# Click 'Express start': your game launches with the maximum number of players specified. It shows an empty canvas: in the game zone you just have a sentence 'This is your game interface. You can edit this HTML in your ".tpl" file.'.<br />
# Switch to your SFTP home folder, go into your game folder. Edit the game_game.tpl file, and change this sentence to 'Hey, this is my first game!', then save.<br />
# Go back to your browser and refresh, check that the game zone has updated.<br />
# Click on the 'Gear' icon on the top right, and in the popup choose 'Express STOP'. The game ends automatically and you are brought back to the table screen for this ended game.<br />
# Switch to your game folder, go into the img folder and overwrite your game_box.png file with another image.<br />
# Go back to your browser, '''empty your browser cache''', then refresh the page, and check that the game box image has been updated.<br />
<br />
Then you can modify the provided skeleton and begin to develop your game :)<br />
<br />
== Commit your changes ==<br />
<br />
Committing uploads your changes on BGA's [http://en.wikipedia.org/wiki/Revision_control revision control] system. This is an extra assurance not to lose your code, and to have the possibility to get a previous version of your code if you need to backtrack. It also helps us to follow your progress (we get an email when you commit). So you should commit from time to time, when you hit some landmark in your development.<br />
<br />
You can automatically commit your sources in the repository from "Control Panel / Manage Games / Your game / Commit my modifications now". Then:<br />
<br />
# Enter your commit comment (such as 'My first commit') then hit the 'Submit' button;<br />
# Check the log for errors, it should end with the following lines:<br />
<br />
Transmitting file data .<br />
Committed revision #revision number#.<br />
HAL says: done.<br />
<br />
NOTE: committing the code is currently not working until admin commits it manually the first time. Even if it does you cannot automatically deal with this version control system except for committing. Therefore its recommended to use another means of storing the code in version control system, such as local git repo or github, see [[Tools_and_tips_of_BGA_Studio#Version_Control|Version Control]]<br />
<br />
== That's all! ==<br />
<br />
Now you know about the basics of updating your game on BGA Studio and testing your changes.<br />
<br />
Now you can select one of the tutorials to play with and start coding.<br />
<br />
For links to tutorials and ALL studio documentation see [[Studio]].</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=BGA_game_Lifecycle&diff=4033
BGA game Lifecycle
2020-04-15T21:12:12Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
Here's a summary of the different steps you would follow when developing a game with BGA Studio.<br />
<br />
{| class="wikitable"<br />
|-<br />
! Step !! How to reach this step !! What happened during the step?<br />
|-<br />
| Initial || [[How to join BGA developer team?]] || You can choose to join an existing team / create a new project<br />
|-<br />
| Assigned || You choose a game || You can start the development of the game<br />
|-<br />
| Pre-alpha || You've started to write some piece of code || You develop the game. During this phase, we can assist you with the framework and give you some pieces of advice.<br />
|-<br />
| Alpha || You tell us that your development is finished || "BGA review": we are reviewing your game and check if it respects [http://fr.slideshare.net/boardgamearena/bga-studio-guidelines BGA guidelines]. If not, we will ask you (and help you) to fix them.<br />
|-<br />
| Private beta || We give a "go" || "Publisher review": On preproduction platform, the publisher, the designer, we and you can test the game together and separately. We help you to take into account remarks from the publisher and the designer.<br />
|-<br />
| Public beta || The adaptation is approved by the publisher || We find together a good launch date for the game, we announce the game on BGA news, and then player can start to play! During the first days, it is common that some bugs are reported by players, and you can fix them following the instructions in [[Post-release phase]].<br />
|-<br />
| Gold || The game is stable on BGA || Congrats! You can still modify and optimize things following the instructions in [[Post-release phase]].<br />
|}</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Zone&diff=4032
Zone
2020-04-15T21:11:24Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
The Zone component is meant to organise items of the same type inside a predefined space.<br />
<br />
== Zone in action ==<br />
<br />
If you want to see how Zone works, please try "Can't Stop" or "Niagara" on BGA, or watch a game in progress or game replay.<br />
<br />
In Can't Stop, zone is used to display the bhikkus ascending the mountain when there is more than one on the same space (diagonal mode).<br />
<br />
In Niagara, it is used to display the canoes over the circles going down the river (custom mode).<br />
<br />
== How to use Zone == <br />
<br />
At first, don't forget to add "ebg/zone" as a dependency:<br />
<pre><br />
define([<br />
"dojo","dojo/_base/declare",<br />
"ebg/core/gamegui",<br />
"ebg/counter",<br />
"ebg/zone" /// <==== HERE<br />
],<br />
</pre><br />
<br />
Then, declare a new variable in your class for the Zone object:<br />
<br />
<pre><br />
constructor: function(){<br />
console.log('yourgame constructor');<br />
<br />
// Zone control <br />
this.myZone = new ebg.zone();<br />
</pre><br />
<br />
Now, in your template file, you must add a div that will host this zone:<br />
<br />
<pre><br />
<div id="my_zone"></div><br />
</pre><br />
<br />
And set its width (and optionnaly, height and position) in CSS:<br />
<br />
<pre><br />
<br />
#my_zone {<br />
width: 100px;<br />
}<br />
<br />
</pre><br />
<br />
Then in your Javascript setup, attach your Zone component to the div and define its properties :<br />
<br />
<pre><br />
zone.create( this, 'my_zone', <item_width>, <item_height> );<br />
zone.setPattern( <mode> );<br />
</pre><br />
<br />
* <item_width> is an integer for the width of the objects you want to organise in the zone<br />
* <item_height> is an integer for the height of the objects you want to organise in the zone <br />
* <mode> is one of 'grid' (objects will be put on lines from top left to bottom right, wrapping when there is not enough space left on the line, relatively to the width you have defined) 'diagonal' (objects will be organised on a top left to bottom right diagonal, overlapping each other) or 'custom' (objects will be organised depending upon their number and the coordinates that you provide - see below)<br />
<br />
Since the width of the Zone is defined statically, beware of not letting items overflow on small screens. If you need a design-responsive component, consider using the Stock component instead.<br />
<br />
Now your zone is ready to be used!<br />
<br />
After creating an object that you want to add to the zone as a classic HTML template (dojo.place / this.format_block), you can simply use:<br />
<br />
<pre><br />
zone.placeInZone( <object_id>, <weight> );<br />
</pre><br />
<br />
* <object_id> is the string identifier for your object 'my_object_id'<br />
* <weight> is an optional parameter used to sort items<br />
<br />
To remove an item, use:<br />
<br />
<pre><br />
zone.removeFromZone( <object_id>, <destroy?>, <to> );<br />
</pre><br />
<br />
* <object_id> is the string identifier for your object 'my_object_id'<br />
* <destroy?> is a boolean indicating if the object should be destroyed after being removed<br />
* <to> is the destination the object must be slided to when being removed (before being eventually destroyed)<br />
<br />
You can also:<br />
* remove all items from the zone (and destroy them) using zone.removeAll();<br />
* get the number of items in your zone using zone.getItemNumber();<br />
* get an array of the ids of all the items using zone.getAllItems();<br />
<br />
== Custom mode == <br />
<br />
If you want complete control on how your objects are laid out inside the Zone, you can determine their coordinates after their number when being added to the zone. Here is how to do it, when defining your Zone properties in the javascript setup:<br />
<br />
<pre><br />
this.zone.setPattern( 'custom' );<br />
<br />
this.zone.itemIdToCoords = function( i, control_width ) {<br />
if( i%8==0 )<br />
{ return { x:1,y:19, w:60, h:30 }; }<br />
else if( i%8==1 )<br />
{ return { x:30,y:38, w:60, h:30 }; }<br />
else if( i%8==2 )<br />
{ return { x:42,y:8, w:60, h:30 }; }<br />
else if( i%8==3 )<br />
{ return { x:5,y:58, w:60, h:30 }; }<br />
else if( i%8==4 )<br />
{ return { x:5,y:24, w:60, h:30 }; }<br />
else if( i%8==5 )<br />
{ return { x:35,y:43, w:60, h:30 }; }<br />
else if( i%8==6 )<br />
{ return { x:47,y:13, w:60, h:30 }; }<br />
else if( i%8==7 )<br />
{ return { x:10,y:63, w:60, h:30 }; }<br />
};<br />
</pre></div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Stock&diff=4031
Stock
2020-04-15T21:11:12Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
'''Stock''' is a javascript component that you can use in your game interface to display a set of elements of the same size that need to be arranged in single or multiple lines.<br />
<br />
Stock is very flexible and is the most used component in BGA games.<br />
<br />
Examples of stock use cases:<br />
<br />
* Display a set of cards, typically hands (examples: ''Hearts'', ''Seasons'', ''The Boss'', ''Race for the Galaxy'').<br />
* Display items in player panels (examples: ''Takenoko'', ''Amyitis'', ...)<br />
* ... Many other situations. For example, black dice and cubes on cards in ''Troyes'' are displayed with stock components.<br />
<br />
Using stock:<br />
<br />
* Your items are arranged nicely and sorted by type.<br />
* When adding or removing items to a set, all items slide smoothly to their new position in the set.<br />
* Selecting and unselecting items are built-in functions.<br />
* You don't have to worry about inserting/removing HTML code; the entire life cycle of the stock is managed by the component.<br />
<br />
== Using stock: a simple example ==<br />
<br />
Let's have a look on how the stock is used in the game ''Hearts'' to display a hand of standard cards.<br />
<br />
First, don't forget to add "ebg/stock" as a dependency in your js file:<br />
<br />
<pre><br />
define([<br />
"dojo","dojo/_base/declare",<br />
"ebg/core/gamegui",<br />
"ebg/counter",<br />
"ebg/stock" /// <==== HERE<br />
],<br />
</pre><br />
<br />
The stock is initialized in the Javascript "setup" method like this:<br />
<br />
<pre><br />
// Player hand<br />
this.playerHand = new ebg.stock();<br />
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );<br />
</pre><br />
<br />
Explanations:<br />
* We create a new stock object for the player hand.<br />
* As parameters of the "create" method, we provide the width/height of an item (a card), and the div container "myhand" - which is a simple empty "div" element defined in our HTML template (.tpl).<br />
<br />
Then, we must tell the stock what items it is going to display during its life: the 52 cards of a standard card game. Of course, we did not create 52 different images, but a "CSS sprite" image named "cards.jpg" with the cards arranged in 4 rows and 13 columns.<br />
<br />
Here's how we tell stock what items to display:<br />
<br />
<pre><br />
// Specify that there are 13 images per row in the CSS sprite image<br />
this.playerHand.image_items_per_row = 13;<br />
<br />
// Create card types:<br />
for( var color=1;color<=4;color++ )<br />
{<br />
for( var value=2;value<=14;value++ )<br />
{<br />
// Build card type id<br />
var card_type_id = this.getCardUniqueId( color, value );<br />
this.playerHand.addItemType( card_type_id, card_type_id, g_gamethemeurl+'img/cards.jpg', card_type_id );<br />
}<br />
}<br />
</pre><br />
<br />
Explanation:<br />
<br />
* First, we tell the stock component that our CSS sprite contains 13 items per row. This way, it can find the correct image for each card type id.<br />
* Then for the 4x13 cards, we call the "addItemType" method that creates the type. The arguments are the type id, the weight of the card (for sorting purpose), the URL of our CSS sprite, and the position of our card image in the CSS sprite.<br />
<br />
Note: In this specific example we need to generate a unique ID for each type of card based on its color and value. This is the only purpose of "getCardUniqueId".<br />
<br />
From now on, if we need to add a card - for example, the 5 of Hearts - to a player's hand, we can do this:<br />
<br />
<pre><br />
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ) );<br />
</pre><br />
<br />
In reality, cards have some IDs, which are useful to manipulate them. This is the reason we are using "addToStockWithId" instead:<br />
<br />
<pre><br />
this.playerHand.addToStockWithId( this.getCardUniqueId( 2 /* 2=hearts */, 5 ), my_card_id );<br />
</pre><br />
<br />
If afterwards we want to remove this card from the stock:<br />
<br />
<pre><br />
this.playerHand.removeFromStockById( my_card_id );<br />
</pre><br />
<br />
== Complete stock component reference ==<br />
<br />
'''create( page, container_div, item_width, item_height ):'''<br />
<br />
With create, you create a new stock component.<br />
<br />
Parameters:<br />
* page: the container page. Usually: "this".<br />
* container_div: the container "div" element (a void div element in your template, with an id).<br />
* width and height (in pixels) for the stock component.<br />
<br />
(See ''Hearts'' example above).<br />
<br />
'''count():'''<br />
<br />
Return the total number of items in the stock right now.<br />
<br />
'''addItemType( type, weight, image, image_position ):'''<br />
<br />
Define a new type of item and add it to the stock.<br />
<br />
This is mandatory to define a new item type before adding it to the stock. Example: if you want to have a stock contain cubes of 3 different colors, you must add 3 item types (one for each color).<br />
<br />
Parameters:<br />
* type: ID of the type to add. You can choose any positive integer. All item types must have distinct IDs.<br />
* weight: weight of items of this type. Weight value is used to sort items of the stock during the display. Note that you can specify the same weight for all items; in this case, they are not sorted and their order might change randomly at any time.<br />
* image: URL of item image. Most of the time, you will use a CSS sprite for stock items, so you have to specify CSS sprite image here.<br />
<br />
Be careful: you must specify the image url as this:<br />
<br />
<pre><br />
g_gamethemeurl+'img/yourimage.png'<br />
</pre><br />
<br />
* image_position: if "image" specify the URL of a CSS sprite, you must specify the position of the item image in this CSS sprite. For example, if you have a CSS sprite with 3 cubes with a size of 20x20 pixels each (so your CSS image has for example a size of 20x60 or 60x20), you specify "0" for the first cube image, 1 for the second, 2 for the third.<br />
<br />
''Important'': if there is more than one line of items in your CSS sprite, you must specify how many items per line you have in your CSS sprite like this:<br />
<br />
<pre><br />
// Specify that there are 10 image items per row in images used in "myStockObject" control.<br />
this.myStockObject.image_items_per_row = 10;<br />
</pre><br />
<br />
'''addToStock( type, from )'''<br />
<br />
Add an item to the stock, with the specified type, but without a unique ID.<br />
<br />
To make your life easier, in most cases we suggest you use '''addToStockWithId''' in order to give an ID to the item added. '''addToStock''' is suitable when you are using a stock to control items that are generic game materials that don't need to be addressed individually (example: a bunch of money tokens).<br />
<br />
Parameters:<br />
* type: ID of the item type to use (as specified in "addItemType")<br />
* from: OPTIONAL: if you specify an HTML item here, the item will appear on this item and will be slid to its position on the stock item.<br />
<br />
Example:<br />
<pre><br />
// Add a money token to the "player money" stock.<br />
// The money token will appear on "player_id" player panel and will move to its position.<br />
this.playerMoney.addToStock( MONEY_TOKEN, 'overall_player_board_'+player_id );<br />
</pre><br />
<br />
Important: for a given stock control, you must use either '''addToStock''' or '''addToStockWithId''', but NEVER BOTH OF THEM.<br />
<br />
'''addToStockWithId( type, id, from )'''<br />
<br />
This is the same method as '''addToStock''', except that it also associates an ID with the newly created item.<br />
<br />
This is especially useful:<br />
<br />
* When you need to know which item(s) have been selected by the user (see '''getSelectedItems''').<br />
* When you need to remove a specific item from the stock with '''removeFromStockById'''.<br />
<br />
Important: for a given stock control, you must use either '''addToStock''' or '''addToStockWithId''', but NEVER BOTH OF THEM.<br />
<br />
'''removeFromStock( type, to )'''<br />
<br />
Remove an item of the specific type from the stock.<br />
<br />
"to" is an optional parameter. If "to" contains the ID of an HTML element, the item removed from the stock is slided to this HTML element before it disappear.<br />
<br />
'''removeFromStockById( id, to )'''<br />
<br />
Remove an item with a specific ID from the stock.<br />
<br />
"to" is an optional parameter. If "to" contains the ID of an HTML element, the item removed from the stock is slided to this HTML element before it disappear.<br />
<br />
'''removeAll()'''<br />
<br />
Remove all items from the stock.<br />
<br />
'''removeAllTo( to )'''<br />
<br />
Remove all items from the stock. If "to" contains the ID of an HTML element, the item removed from the stock is slided to this HTML element before it disappear.<br />
<br />
'''getPresentTypeList()'''<br />
<br />
Return an array with all the types of items present in the stock right now.<br />
<br />
Example:<br />
<pre><br />
this.myStockControl.removeAll();<br />
this.myStockControl.addToStock( 65 );<br />
this.myStockControl.addToStock( 34 );<br />
this.myStockControl.addToStock( 89 );<br />
this.myStockControl.addToStock( 65 );<br />
<br />
// The following returns: { 34:1, 65:1, 89:1 }<br />
var item_types = this.myStockControl.getPresentTypeList();<br />
</pre><br />
<br />
'''resetItemsPosition()'''<br />
<br />
If you moved an item from the stock control manually (ex: after a drag'n'drop) and want to reset their positions to their original ones, you can call this method.<br />
<br />
'''item_margin'''<br />
<br />
By default, there is a margin of 5px between the items of a stock. You can change the member variable "item_margin" to change this.<br />
<br />
Example:<br />
<pre><br />
this.myStockControl.item_margin=5;<br />
</pre><br />
<br />
'''changeItemsWeight( newWeights )'''<br />
<br />
With this method you can change dynamically the weight of the item types in a stock control.<br />
<br />
Items are immediately re-sorted with the new weight.<br />
<br />
Example: with a stock control that contains classic cards, you can order them by value or by color. Using changeItemsWeight you can switch from one sort method to another when a player request this.<br />
<br />
newWeights is an associative array: item type id => new weight.<br />
<br />
Example:<br />
<pre><br />
// Item type 1 gets a new weight of 10, 2 a new weight of 20, 3 a new weight of 30.<br />
this.myStockControl.changeItemsWeight( { 1: 10, 2: 20, 3: 30 } );<br />
</pre><br />
<br />
'''centerItems'''<br />
<br />
Center the stock items in the middle of the stock container.<br />
e.g. this.myStock.centerItems = true; <br />
<br />
'''setSelectionMode( mode )'''<br />
<br />
For each stock control, you can specify a selection mode:<br />
* 0: no item can be selected by the player.<br />
* 1: a maximum of one item can be selected by the player at a time.<br />
* 2 (default): multiple items can be selected by the player at the same time.<br />
<br />
'''setSelectionAppearance( type )'''<br />
<br />
For each stock control, you can specify a selection highlighting type:<br />
* 'border': there will be a red border around selected items (this is the default). The attribute 'apparenceBorderWidth' can be used to manage the width of the border (in pixels).<br />
* 'disappear': the selected item will fade out and disappear. This is useful when the selection has the effect of destroying the item.<br />
* 'class': there will be an extra '''stockitem_selected''' css class added to the element when it is selected (and removed when unselected). You can override this class in the css file for your game.<br />
<br />
By default this class definition is:<br />
<pre><br />
.stockitem_selected {<br />
border: 2px solid red ! important;<br />
}<br />
</pre><br />
<br />
If you want to override it (for example, to change the border color) add this in your <game>.css file:<br />
<pre><br />
.stockitem_selected {<br />
border: 2px solid orange ! important;<br />
}<br />
</pre><br />
<br />
'''isSelected( id )'''<br />
<br />
Return a boolean indicating whether the specified item id has been selected.<br />
<br />
'''selectItem( id )'''<br />
<br />
Select the specified item.<br />
<br />
'''unselectItem( id )'''<br />
<br />
Unselect the specified item.<br />
<br />
'''unselectAll()'''<br />
<br />
Unselect all items of the stock.<br />
<br />
'''onChangeSelection'''<br />
<br />
This callback method is called when the player selects/unselects an item of the stock.<br />
<br />
You can connect this to one of your methods like this:<br />
<br />
<pre><br />
dojo.connect( this.myStockControl, 'onChangeSelection', this, 'onMyMethodToCall' );<br />
<br />
(...)<br />
<br />
onMyMethodToCall: function( control_name, item_id )<br />
{<br />
// This method is called when myStockControl selected items changed<br />
var items = this.myStockControl.getSelectedItems();<br />
<br />
// (do something)<br />
},<br />
</pre><br />
<br />
Nota bene: <br />
- The "control_name" argument is the ID (the "DOM" id) of the "div" container of your stock control. Using "control_name", you can use the same callback method for different Stock control and see which one trigger the method.<br />
- The "item_id" argument is the stock ID (index) of the stock item that has just been selected/unselected.<br />
<br />
'''getSelectedItems()'''<br />
<br />
Return the list of selected items, as an array with the following format:<br />
<pre><br />
[<br />
{ type:1, id: 1001 },<br />
{ type:1, id: 1002 },<br />
{ type:3, id: 1003 }<br />
...<br />
]<br />
</pre><br />
<br />
'''getUnselectedItems()'''<br />
<br />
Same as the previous one, but return unselected item instead of seleted ones.<br />
<br />
'''getAllItems()'''<br />
<br />
Get all items (same format as getSelectedItems and getUnselectedItems).<br />
<br />
'''getItemDivId(id)'''<br />
<br />
Get the div id using the stock item id (to manipulate element properties directly).<br />
<br />
'''setOverlap( horizontal_percent, vertical_percent )'''<br />
<br />
Make items of the stock control "overlap" each other, to save space.<br />
<br />
By default, horizontal_overlap and vertical_overlap are 0.<br />
<br />
When horizontal_overlap=20, it means that a stock item will overlap to only show 20% of the width of all the previous items. horizontal_overlap can't be greater than 100.<br />
<br />
vertical_overlap works differently: one items on two are shifted up.<br />
<br />
See the games "Jaipur" or "Koryŏ" to see examples of use of this function.<br />
<br />
'''onItemCreate'''<br />
<br />
Using onItemCreate, you can trigger a method each time a new item is added to the Stock, in order to customize it.<br />
<br />
Complete example:<br />
<pre><br />
// During "setup" phase, we associate our method "setupNewCard" with the creation of a new stock item:<br />
this.myStockItem.onItemCreate = dojo.hitch( this, 'setupNewCard' ); <br />
<br />
(...)<br />
<br />
// And here is our "setupNewCard":<br />
setupNewCard: function( card_div, card_type_id, card_id )<br />
{<br />
// Add a special tooltip on the card:<br />
this.addTooltip( card_div.id, _("Some nice tooltip for this item"), '' );<br />
<br />
// Note that "card_type_id" contains the type of the item, so you can do special actions depending on the item type<br />
<br />
// Add some custom HTML content INSIDE the Stock item:<br />
dojo.place( this.format_block( 'jstpl_my_card_content', {<br />
....<br />
} ), card_div.id );<br />
}<br />
<br />
</pre><br />
<br />
== Tips when adding/removing items to/from Stock components ==<br />
<br />
Most cases will be one of the following situations:<br />
<br />
'''Situation A''':<br />
<br />
When you add a card to a stock item, and this card is '''not''' coming from another stock:<br />
<br />
* Use '''addToStockWithId''' with a "from" argument set to the element of your interface where the card should come from.<br />
<br />
'''Situation B''':<br />
<br />
When you add a card to a stock item, and this card is coming from another stock:<br />
<br />
* On the destination Stock, use '''addToStockWithId''' with a "from" argument which is the HTML id of the corresponding item in the source Stock. For example, if the source stock id is "myHand", then the HTML id of card 48 is "myHand_item_48".<br />
* Then, remove the source item with '''removeFromStockById'''.<br />
<br />
(Note that it's important to do things in this order, because the source item must still exist when you use it as the origin of the slide.)<br />
<br />
'''Situation C''':<br />
<br />
When you move a card from a stock item to something that is not a stock item:<br />
<br />
* Insert the card as a classic HTML template (dojo.place / this.format_block).<br />
* Place it on the Stock item with '''this.placeOnObject''', using the Stock item HTML id (see above).<br />
* Slide it to its new position with '''this.slideToObject'''.<br />
* Remove the card from the Stock item with '''removeFromStockById'''.<br />
<br />
Using the methods above, your cards should slide to, from, and between your Stock controls smoothly.<br />
<br />
<br />
You can customize this (showing the default value):<br />
<pre><br />
<br />
this.mystock.jstpl_stock_item= "<div id=\"${id}\" class=\"stockitem\" style=\"top:${top}px;left:${left}px;width:${width}px;height:${height}px;z-index:${position};background-image:url('${image}');\"></div>";<br />
</pre><br />
To produce a different type of stock item</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Scrollmap&diff=4030
Scrollmap
2020-04-15T21:09:15Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
Scrollmap is a BGA client side component to display an infinite game area.<br />
<br />
In some games, players are building the main game area with tiles or cards. Examples:<br />
* Carcassonne<br />
* Saboteur<br />
* Takenoko<br />
* Taluva<br />
* ...<br />
<br />
Of course this cause an additional difficulty for the adaptation, because we have to display an infinite game area into a finite space on the screen. This is where Scrollmap component can help you.<br />
<br />
== Scrollmap in action ==<br />
<br />
If you want to see how Scrollmap looks like, please try "Saboteur" or "Takenoko" games on BGA, or watch a game in progress.<br />
<br />
In both games, you can see that there are arrow controls around the main game area, so that players can use them to scroll the view. You can also drag'n'drop the game area to scroll.<br />
<br />
== How to use Scrollmap ==<br />
<br />
At first, don't forget to add "ebg/scrollmap" as a dependency:<br />
<pre><br />
define([<br />
"dojo","dojo/_base/declare",<br />
"ebg/core/gamegui",<br />
"ebg/counter",<br />
"ebg/scrollmap" /// <==== HERE<br />
],<br />
</pre><br />
<br />
<br />
Then, declare a new variable in your class for the Scrollmap object:<br />
<br />
<pre><br />
constructor: function(){<br />
console.log('yourgame constructor');<br />
<br />
// Scrollable area <br />
this.scrollmap = new ebg.scrollmap();<br />
</pre><br />
<br />
Now, open your template (TPL) file and add this HTML code:<br />
<br />
<pre><br />
<div id="map_container"><br />
<div id="map_scrollable"></div><br />
<div id="map_surface"></div><br />
<div id="map_scrollable_oversurface"></div><br />
<a id="movetop" href="#"></a><br />
<a id="moveleft" href="#"></a><br />
<a id="moveright" href="#"></a><br />
<a id="movedown" href="#"></a><br />
</div><br />
</pre><br />
<br />
There are also some lines to add to your CSS stylesheet. Please note that you can adapt it to your needs, especially the default width of the scrollable area:<br />
<pre><br />
/** Scrollable area **/<br />
<br />
#map_container {<br />
position: relative;<br />
width: 100%;<br />
height: 400px;<br />
overflow: hidden;<br />
}<br />
#map_scrollable, #map_scrollable_oversurface {<br />
position: absolute;<br />
top: 205px;<br />
left: 315px;<br />
}<br />
#map_surface {<br />
position: absolute;<br />
top: 0px;<br />
left: 0px;<br />
width: 100%;<br />
height: 100%;<br />
cursor: move;<br />
}<br />
#map_footer {<br />
text-align: center;<br />
}<br />
<br />
</pre><br />
<br />
Finally, to link your HTML code with your Javascript, place this in your Javascript "Setup" method:<br />
<br />
<pre><br />
// Make map scrollable <br />
this.scrollmap.create( $('map_container'),$('map_scrollable'),$('map_surface'),$('map_scrollable_oversurface') );<br />
this.scrollmap.setupOnScreenArrows( 150 );<br />
<br />
</pre><br />
<br />
This is it! Now, you should see on your game interface a scrollable game area. This is not really impressive though, because you didn't add anything on the game area yet. This is the next step.<br />
<br />
== Scrollable area layers ==<br />
<br />
There are 2 - and only 2 - places where you should place your HTML stuff in your scrollable area:<br />
* inside "map_scrollable" div<br />
* inside "map_scrollable_oversurface" div<br />
<br />
The difference is very important: "map_scrollable" is beneath the surface that is used to drag'n'drop the game area, and "map_scrollable_oversurface" is above this surface. In practice:<br />
* If some element on the game area need to be clicked (or any kind of user interaction), you should place it in map_scrollable_oversurface, otherwise no click can reach it.<br />
* If some element on the game area don't need to be clicked, you'd better place it in "map_scrollable", so it is possible to drag'n'drop the game area from a point on this element.<br />
<br />
Of course, all layers are scrolled synchronously.<br />
<br />
Tips: in some situation, it's also useful to place a game element on map_scrollable and a corresponding invisible element over the surface to manage the interactions. Example: when an interactive element must be placed beneath a non interactive element for display reason.<br />
<br />
== Positioning elements on game area ==<br />
<br />
All elements on the game are must be absolute positioned (with "top" and "left" attributes).<br />
<br />
By default, the game area is centered on 0,0 coordinates.<br />
<br />
== Enable move arrows ==<br />
<br />
To show move arrows icons around the scrollmap in order to enable click based navigation in addition to drag and drop, add these lines to your CSS:<br />
<br />
<pre><br />
/** Move arrows **/<br />
<br />
#movetop,#moveleft,#moveright,#movedown {<br />
display: block;<br />
position: absolute;<br />
background-image: url('../../../img/common/arrows.png');<br />
width: 32px;<br />
height: 32px;<br />
}<br />
<br />
#movetop {<br />
top: 0px;<br />
left: 50%;<br />
background-position: 0px 32px;<br />
}<br />
#moveleft {<br />
top: 50%;<br />
left: 0px;<br />
background-position: 32px 0px;<br />
}<br />
#moveright {<br />
top: 50%;<br />
right: 0px;<br />
background-position: 0px 0px;<br />
}<br />
#movedown {<br />
bottom: 0px;<br />
left: 50%;<br />
background-position: 32px 32px;<br />
}<br />
</pre><br />
<br />
In your javascript, define the following functions:<br />
<br />
<pre><br />
onMoveTop : function( evt )<br />
{<br />
console.log( "onMoveTop" ); <br />
evt.preventDefault();<br />
this.scrollmap.scroll( 0, 300 );<br />
},<br />
onMoveLeft : function( evt )<br />
{<br />
console.log( "onMoveLeft" ); <br />
evt.preventDefault();<br />
this.scrollmap.scroll( 300, 0 );<br />
},<br />
onMoveRight : function( evt )<br />
{<br />
console.log( "onMoveRight" ); <br />
evt.preventDefault();<br />
this.scrollmap.scroll( -300, 0 );<br />
},<br />
onMoveDown : function( evt )<br />
{<br />
console.log( "onMoveDown" ); <br />
evt.preventDefault();<br />
this.scrollmap.scroll( 0, -300 );<br />
},<br />
</pre><br />
<br />
And connect onclick events on the arrows to these functions in your javascript setup<br />
<br />
<pre><br />
dojo.connect( $('movetop'), 'onclick', this, 'onMoveTop' );<br />
dojo.connect( $('moveleft'), 'onclick', this, 'onMoveLeft' );<br />
dojo.connect( $('moveright'), 'onclick', this, 'onMoveRight' );<br />
dojo.connect( $('movedown'), 'onclick', this, 'onMoveDown' );<br />
</pre><br />
<br />
== Enable scrollmap zone extension ==<br />
<br />
This is optional, when there can be unused screen space under the scrollmap that a player might want to use.<br />
Add this in your .tpl after the scrollmap div (the matching css rules has already been defined):<br />
<br />
<pre><br />
<div id="map_footer" class="whiteblock"><br />
<a href="#" id="enlargedisplay">&darr;&nbsp;&nbsp;{LABEL_ENLARGE_DISPLAY}&nbsp;&nbsp;&darr;</a><br />
</div><br />
</pre><br />
<br />
In your javascript, define the following function:<br />
<br />
<pre><br />
onIncreaseDisplayHeight: function( evt )<br />
{<br />
console.log( '$$$$ Event : onIncreaseDisplayHeight' );<br />
evt.preventDefault();<br />
<br />
var cur_h = toint( dojo.style( $('map_container'), 'height' ) );<br />
dojo.style( $('map_container'), 'height', ( cur_h+300 ) + 'px' );<br />
},<br />
</pre><br />
<br />
and connect them to the 'enlargedisplay' link in your setup:<br />
<br />
<pre><br />
dojo.connect( $('enlargedisplay'), 'onclick', this, 'onIncreaseDisplayHeight' );<br />
</pre><br />
<br />
In your view.php file, define the template variable LABEL_ENLARGE_DISPLAY so that it gets substituted with appropriate translatable text:<br />
<br />
<pre><br />
$this->tpl['LABEL_ENLARGE_DISPLAY'] = self::_("Enlarge display");<br />
</pre></div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Counter&diff=4029
Counter
2020-04-15T21:08:54Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
<br />
== Dependency ==<br />
<br />
Don't forget to add '''ebg/counter''' as a dependency:<br />
<br />
// in your game js<br />
define([<br />
"dojo","dojo/_base/declare",<br />
"ebg/core/gamegui",<br />
"ebg/counter" /// <==== HERE],<br />
<br />
== Setup a counter ==<br />
<br />
<pre><br />
player.handSizeCounter = new ebg.counter();<br />
player.handSizeCounter.create('hand_size_player_' + player_id);<br />
</pre><br />
<br />
== Update counter ==<br />
<br />
<pre><br />
player.handSizeCounter.setValue(player.handSize);<br />
</pre><br />
<br />
== Players panels ==<br />
<br />
=== Adding stuff to player's panel ===<br />
<br />
First, create a new JS template string in your template (tpl) file.<br />
<br />
From the ''Gomoku'' example:<br />
<br />
<pre><br />
var jstpl_player_board = '\<div class="cp_board">\<br />
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\<br />
</div>';<br />
</pre><br />
<br />
Then, add this piece of code in the '''setup''' function of your JS file to add this template to each player panel:<br />
<br />
<pre><br />
// Setting up player boards<br />
for( var player_id in gamedatas.players )<br />
{<br />
var player = gamedatas.players[player_id];<br />
<br />
// Setting up players boards if needed<br />
var player_board_div = $('player_board_'+player_id);<br />
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );<br />
}<br />
</pre><br />
<br />
Often, you have to distinguish between the current player and other players. In this case, create another JS template (ex: jstpl_otherplayer_board) and use it where "player_id" is different than "this.player_id".</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Deck&diff=4028
Deck
2020-04-15T21:08:40Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
"Deck" is one of the most useful component on the PHP side. With "Deck", you can manage the cards in your game on the server side.<br />
<br />
Using "deck", you will be able to use the following features without writing a single SQL database request:<br />
* Place cards in a pile, shuffle cards, draw cards one by one or many at a time.<br />
* "Auto-reshuffle" the discard pile into the deck when the deck is empty.<br />
* Move cards between different locations: hands of players, the table, etc.<br />
<br />
<br />
== Using Deck: Hearts example ==<br />
<br />
The Deck component is extensively used in the sample ''Hearts'' card game. You will find in "hearts.game.php" that the object "$this->cards" is used many times.<br />
<br />
== Deck overview ==<br />
<br />
With Deck component, you manage all cards of your game.<br />
<br />
=== The 5 properties of each card ===<br />
<br />
Using the Deck component, each card will have 5 properties:<br />
* '''id''': This is the unique ID of each card.<br />
* '''type''' and '''type_arg''': These two values define the type of your card (i.e., what sort of card is this?).<br />
* '''location''' and '''location_arg''': These two values define where the card is at now.<br />
<br />
The id, type, and type_arg properties are constants throughout the game. location and location_arg change when your cards move from one place to another in the game area.<br />
<br />
'''id''' is the unique ID of each card. Two cards cannot have the same ID. IDs are generated automatically by the Deck component when you create cards during the Setup phase of your game.<br />
<br />
'''type''' and '''type_arg''' defines the type of your card.<br />
<br />
'''type''' is a short string, and '''type_arg''' is an integer.<br />
<br />
You can use these two values as you like to make sure you will be able to identify the different cards in the game. See usage of "type" and "type_arg" below.<br />
<br />
Examples of usage of "type" and "type_arg":<br />
* In ''Hearts'', "type" represents the color (suite) of the card (1 to 4) and "type_arg" is the value of the card (1, 2, ... 10, J, Q, K).<br />
* In ''Seasons'', "type" represents the type of the card (e.g., 1 is Amulet of Air, 2 is Amulet of Fire, etc...). type_arg is not used.<br />
* In ''Takenoko'', a Deck component is used for objective cards. "type" is the kind of objective (irrigation/panda/plot) and "type_arg" is the ID of the specific objective to realize (e.g., "green bamboo x4"). Note that a second Deck component is used in ''Takenoko'' to manage the "garden plot" pile.<br />
<br />
'''location''' and '''location_arg''' define where a card is at now. '''location''' is a short string, and '''location_arg''' is an integer.<br />
<br />
You can use 'location' and 'location_arg' as you like, to move your card within the game area.<br />
<br />
There are 3 special 'location' values that Deck manages automatically. You can choose to use these locations or not, depending on your needs:<br />
* 'deck': the 'deck' location is a standard draw deck. Cards are placed face down in a stack and are drawn in sequential order during the game. 'location_arg' is used to specify where the card is located within the stack (the card with the highest location_arg value is the next to be drawn).<br />
* 'hand': the 'hand' location represents cards in a player's hand. 'location_arg' is set to the ID of each player.<br />
* 'discard': the 'discard' location is used for discard piles. Card in 'discard' may be reshuffled into the deck if needed (see "autoreshuffle").<br />
<br />
<br />
Tips: using the Deck component, you will use generic properties ("location", "type_arg",...) for specific purposes in your game. Thus, during the design step before realizing your game, take a few minutes to write down the exact meaning of each of these generic properties in the context of your game.<br />
<br />
=== Create a new Deck component ===<br />
<br />
For each Deck component in your game, you need to create a dedicated table in the SQL database. This table has a standard format. In practice, if you just want to have a Deck component named "card", you can copy/paste the following into your "dbmodel.sql" file:<br />
<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `card` (<br />
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,<br />
`card_type` varchar(16) NOT NULL,<br />
`card_type_arg` int(11) NOT NULL,<br />
`card_location` varchar(16) NOT NULL,<br />
`card_location_arg` int(11) NOT NULL,<br />
PRIMARY KEY (`card_id`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;<br />
</pre><br />
<br />
Note: the database schema of this table does not have to be exactly what is listed above. You can increase the size of the fields or add more fields. For additional fields<br />
you just have to do manual queries.<br />
<br />
Once you have done this (and restarted your game), you can declare the Deck component in your PHP code in your class constructor. For ''Hearts'' for example, I added to the "Hearts()" method:<br />
<br />
<pre><br />
$this->cards = self::getNew( "module.common.deck" );<br />
$this->cards->init( "card" );<br />
</pre><br />
<br />
Note that we specify "card" here: the name of our previously created table. This means you can create several "Deck" components with multiple tables:<br />
<br />
<pre><br />
$this->firstKindCards = self::getNew( "module.common.deck" );<br />
$this->firstKindCards ->init( "first_kind_card" );<br />
$this->secondKindCards = self::getNew( "module.common.deck" );<br />
$this->secondKindCards ->init( "second_kind_card" );<br />
</pre><br />
<br />
Most of the time this is not useful; a Deck component should manage all objects of the same kind (i.e., all cards in the game).<br />
<br />
Afterwards, we can initialize your "Deck" by creating all the cards of the game. Generally, this is done only once during the game, in the "setupNewGame" method.<br />
<br />
The "Deck" component provides a fast way to initialize all your cards at once: createCards. Here is how it is used for "Hearts":<br />
<pre><br />
// Create cards<br />
$cards = array();<br />
foreach( $this->colors as $color_id => $color ) // spade, heart, diamond, club<br />
{<br />
for( $value=2; $value<=14; $value++ ) // 2, 3, 4, ... K, A<br />
{<br />
$cards[] = array( 'type' => $color_id, 'type_arg' => $value, 'nbr' => 1);<br />
}<br />
}<br />
<br />
$this->cards->createCards( $cards, 'deck' );<br />
</pre><br />
<br />
As you can see, "createCards" takes a description of all cards of the game. For each type of card, you have to specify its "type", "type_arg" and the number of card to create. "createCards" create all cards and place them into the "deck" location (as specified in the second argument).<br />
<br />
Now, you are ready to use "Deck"!<br />
<br />
=== Simple examples using Deck ===<br />
<br />
(Most examples are from "Hearts" game)<br />
<br />
<pre><br />
// In "getAllDatas', we need to send to the current player all the cards he has in hand:<br />
$result['hand'] = $this->cards->getCardsInLocation( 'hand', $player_id );<br />
</pre><br />
<br />
<pre><br />
// At some time we want to check if all the cards (52) are in player's hands:<br />
if( $this->cards->countCardInLocation( 'hand' ) == 52 )<br />
// do something<br />
</pre><br />
<br />
<pre><br />
// When a player plays a card in front of him on the table:<br />
$this->cards->moveCard( $card_id, 'cardsontable', $player_id );<br />
<br />
// Note the use of the custom location 'cardsontable' here to keep track of cards on the table.<br />
</pre><br />
<br />
<br />
<pre><br />
// This is a new hand: let's gather all cards from everywhere in the deck:<br />
$this->cards->moveAllCardsInLocation( null, "deck" );<br />
<br />
// And then shuffle the deck<br />
$this->cards->shuffle( 'deck' );<br />
<br />
// And then deal 13 cards to each player<br />
// Deal 13 cards to each players<br />
// Create deck, shuffle it and give 13 initial cards<br />
$players = self::loadPlayersBasicInfos();<br />
foreach( $players as $player_id => $player )<br />
{<br />
$cards = $this->cards->pickCards( 13, 'deck', $player_id );<br />
<br />
// Notify player about his cards<br />
self::notifyPlayer( $player_id, 'newHand', '', array( <br />
'cards' => $cards<br />
) );<br />
} <br />
<br />
// Note the use of "notifyPlayer" instead of "notifyAllPlayers": new cards is a private information ;) <br />
</pre><br />
<br />
== Deck component reference ==<br />
<br />
=== Initializing Deck component ===<br />
<br />
'''init( $table_name )'''<br />
<br />
Initialize the Deck component.<br />
<br />
Argument:<br />
* table_name: name of the DB table used by this Deck component.<br />
<br />
Must be called before any other Deck method.<br />
<br />
Usually, init is called in your game constructor.<br />
<br />
Example with Hearts:<br />
<br />
<pre><br />
function Hearts( )<br />
{<br />
(...)<br />
<br />
$this->cards = self::getNew( "module.common.deck" );<br />
$this->cards->init( "card" );<br />
}<br />
</pre> <br />
<br />
'''createCards( $cards, $location='deck', $location_arg=null )'''<br />
<br />
Create card items in your deck component. Usually, all card items are created once, during the setup phase of the game.<br />
<br />
"cards" describe all cards that need to be created. "cards" is an array with the following format:<br />
<br />
<pre><br />
// Create 1 card of type "1" with type_arg=99,<br />
// and 4 cards of type "2" with type_arg=12,<br />
// and 2 cards of type "3" with type_arg=33<br />
<br />
$cards = array(<br />
array( 'type' => 1, 'type_arg' => 99, 'nbr' => 1 ),<br />
array( 'type' => 2, 'type_arg' => 12, 'nbr' => 4 ),<br />
array( 'type' => 3, 'type_arg' => 33, 'nbr' => 2 )<br />
...<br />
);<br />
</pre><br />
<br />
Note: During the "createCards" process, Deck generates unique IDs for all card items.<br />
<br />
Note: createCards is optimized to create a lot of cards at once. Do not use it to create cards one by one.<br />
<br />
If "location" and "location_arg" arguments are not set, newly created cards are placed in the "deck" location. If "location" (and optionally location_arg) is specified, cards are created for this specific location.<br />
<br />
=== Card standard format ===<br />
<br />
When Deck component methods are returning one or several cards, the following format is used:<br />
<br />
<pre><br />
array(<br />
'id' => .., // the card ID<br />
'type' => .., // the card type<br />
'type_arg' => .., // the card type argument<br />
'location' => .., // the card location<br />
'location_arg' => .. // the card location argument<br />
);<br />
</pre><br />
<br />
=== Picking cards ===<br />
<br />
'''pickCard( $location, $player_id )'''<br />
<br />
Pick a card from a "pile" location (ex: "deck") and place it in the "hand" of specified player.<br />
<br />
Return the card picked or "null" if there are no more card in given location.<br />
<br />
This method supports auto-reshuffle (see "auto-reshuffle" below).<br />
<br />
'''pickCards( $nbr, $location, $player_id )'''<br />
<br />
Pick "$nbr" cards from a "pile" location (ex: "deck") and place them in the "hand" of specified player.<br />
<br />
Return an array with the cards picked, or "null" if there are no more card in given location.<br />
<br />
Note that the number of cards picked can be less than "$nbr" in case there are not enough cards in the pile location.<br />
<br />
This method supports auto-reshuffle (see "auto-reshuffle" below). In case there are not enough cards in the pile, all remaining cards are picked first, then the auto-reshuffle is triggered, then the other cards are picked.<br />
<br />
'''pickCardForLocation( $from_location, $to_location, $location_arg=0 )'''<br />
<br />
This method is similar to 'pickCard', except that you can pick a card for any sort of location and not only the "hand" location.<br />
<br />
* from_location is the "pile" style location from where you are picking a card.<br />
* to_location is the location where you will place the card picked.<br />
* if "location_arg" is specified, the card picked will be set with this "location_arg".<br />
<br />
This method supports auto-reshuffle (see "auto-reshuffle" below).<br />
<br />
'''pickCardsForLocation( $nbr, $from_location, $to_location, $location_arg=0, $no_deck_reform=false )'''<br />
<br />
This method is similar to 'pickCards', except that you can pick cards for any sort of location and not only the "hand" location.<br />
<br />
* from_location is the "pile" style location from where you are picking some cards.<br />
* to_location is the location where you will place the cards picked.<br />
* if "location_arg" is specified, the cards picked will be set with this "location_arg".<br />
* if "no_deck_reform" is set to "true", the auto-reshuffle feature is disabled during this method call.<br />
<br />
This method supports auto-reshuffle (see "auto-reshuffle" below).<br />
<br />
=== Moving cards ===<br />
<br />
'''moveCard( $card_id, $location, $location_arg=0 )'''<br />
<br />
Move the specific card to given location.<br />
<br />
* card_id: ID of the card to move.<br />
* location: location where to move the card.<br />
* location_arg: if specified, location_arg where to move the card. If not specified "location_arg" will be set to 0.<br />
<br />
<br />
'''moveCards( $cards, $location, $location_arg )'''<br />
<br />
Move the specific cards to given location.<br />
<br />
* cards: an array of IDs of cards to move.<br />
* location: location where to move the cards.<br />
* location_arg: if specified, location_arg where to move the cards. If not specified "location_arg" will be set to 0.<br />
<br />
'''insertCard( $card_id, $location, $location_arg )'''<br />
<br />
Move a card to a specific "pile" location where card are ordered.<br />
<br />
If location_arg place is already taken, increment all cards after location_arg in order to insert new card at this precise location.<br />
<br />
(note: insertCardOnExtremePosition method below is more useful in most of the case)<br />
<br />
'''insertCardOnExtremePosition( $card_id, $location, $bOnTop )'''<br />
<br />
Move a card on top or at bottom of given "pile" type location.<br />
<br />
'''moveAllCardsInLocation( $from_location, $to_location, $from_location_arg=null, $to_location_arg=0 )'''<br />
<br />
Move all cards in specified "from" location to given location.<br />
<br />
* from_location: where to take the cards<br />
* to_location: where to put the cards<br />
* from_location (optional): if specified, only cards with given "location_arg" are moved.<br />
* to_location (optional): if specified, cards moved "location_arg" is set to given value. Otherwise location_arg is set to zero.<br />
<br />
Note: if you want to keep "location_arg" untouched, you should use "moveAllCardsInLocationKeepOrder" below.<br />
<br />
'''moveAllCardsInLocationKeepOrder( $from_location, $to_location )'''<br />
<br />
Move all cards in specified "from" location to given "to" location. This method does not modify the "location_arg" of cards.<br />
<br />
'''playCard( $card_id )'''<br />
<br />
Move specified card at the top of the "discard" location.<br />
<br />
Note: this is an alias for: insertCardOnExtremePosition( $card_id, "discard", true )<br />
<br />
=== Get cards informations ===<br />
<br />
'''getCard( $card_id )'''<br />
<br />
Get specific card information.<br />
<br />
Return null if this card is not found.<br />
<br />
'''getCards( $cards_array )'''<br />
<br />
Get specific cards information.<br />
<br />
cards_array is an array of cards ID.<br />
<br />
If some cards are not found or if some cards IDs are specified multiple times, the method throws an (unexpected) Exception.<br />
<br />
'''getCardsInLocation( $location, $location_arg = null, $order_by = null )'''<br />
<br />
Get all cards in specific location, as an array. Return an empty array if the location is empty.<br />
<br />
* location (string): the location where to get the cards.<br />
* location_arg (optional): if specified, return only cards with the specified "location_arg".<br />
* order_by (optional): if specified, returned cards are ordered by the given database field. Example: "card_id" or "card_type".<br />
<br />
'''countCardInLocation( $location, $location_arg=null )'''<br />
<br />
Return the number of cards in specified location.<br />
<br />
* location (string): the location where to count the cards.<br />
* location_arg (optional): if specified, count only cards with the specified "location_arg".<br />
<br />
'''countCardsInLocations()'''<br />
<br />
Return the number of cards in each location of the game.<br />
<br />
The method returns an associative array with the format "location" => "number of cards".<br />
<br />
Example:<br />
<pre><br />
array(<br />
'deck' => 12,<br />
'hand' => 21,<br />
'discard' => 54,<br />
'ontable' => 3<br />
);<br />
</pre><br />
<br />
'''countCardsByLocationArgs( $location )'''<br />
<br />
Return the number of cards in each "location_arg" for the given location.<br />
<br />
The method returns an associative array with the format "location_arg" => "number of cards".<br />
<br />
Example: count the number of cards in each player's hand:<br />
<pre><br />
countCardsByLocationArgs( 'hand' );<br />
<br />
// Result:<br />
array(<br />
122345 => 5, // player 122345 has 5 cards in hand<br />
123456 => 4 // and player 123456 has 4 cards in hand<br />
);<br />
</pre><br />
<br />
<br />
'''getPlayerHand( $player_id )'''<br />
<br />
Get all cards in given player hand.<br />
<br />
Note: This is an alias for:<br />
getCardsInLocation( "hand", $player_id )<br />
<br />
'''getCardOnTop( $location )'''<br />
<br />
Get the card on top of the given ("pile" style) location, or null if the location is empty.<br />
<br />
Note that the card pile won't be "auto-reshuffled" if there is no more card available.<br />
<br />
'''getCardsOnTop( $nbr, $location )'''<br />
<br />
Get the "$nbr" cards on top of the given ("pile" style) location.<br />
<br />
The method return an array with at most "$nbr" elements (or a void array if there is no card in this location).<br />
<br />
Note that the card pile won't be "auto-reshuffled" if there is not enough cards available.<br />
<br />
'''getExtremePosition( $bGetMax ,$location )'''<br />
<br />
(rarely used)<br />
<br />
Get the position of cards at the top of the given location / at the bottom of the given location.<br />
<br />
Of course this method works only on location in "pile" where you are using "location_arg" to specify the position of each card (example: "deck" location).<br />
<br />
If bGetMax=true, return the location of the top card of the pile.<br />
<br />
If bGetMax=false, return the location of the bottom card of the pile.<br />
<br />
'''getCardsOfType( $type, $type_arg=null )'''<br />
<br />
Get all cards of a specific type (rarely used).<br />
<br />
Return an array of cards, or an empty array if there is no cards of the specified type.<br />
<br />
* type: the type of cards<br />
* type_arg: if specified, return only cards with the specified "type_arg".<br />
<br />
'''getCardsOfTypeInLocation( $type, $type_arg=null, $location, $location_arg = null )<br />
<br />
Get all cards of a specific type in a specific location (rarely used).<br />
<br />
Return an array of cards, or an empty array if there is no cards of the specified type.<br />
<br />
* type: the type of cards<br />
* type_arg: if specified, return only cards with the specified "type_arg".<br />
* location (string): the location where to get the cards.<br />
* location_arg (optional): if specified, return only cards with the specified "location_arg".<br />
<br />
=== Shuffling ===<br />
<br />
'''shuffle( $location )'''<br />
<br />
Shuffle all cards in specific location.<br />
<br />
Shuffle only works on locations where cards are on a "pile" (ex: "deck").<br />
<br />
Please note that all "location_arg" will be reset to reflect the new order of the cards in the pile.<br />
<br />
=== auto-reshuffle ===<br />
<br />
To enable auto-reshuffle you must do "$this->cards->autoreshuffle = true" during the setup of the component.<br />
<br />
Every time a card must be retrieved from the "deck" location, if it is empty the "discard" location will be automatically reshuffled into the "deck" location.<br />
<br />
If you need to notify players when the deck is shuffled, you can setup a callback method using this feature: $this->cards->autoreshuffle_trigger = array('obj' => $this, 'method' => 'deckAutoReshuffle');<br />
<br />
If you need to use other locations than "deck" and "discard" for auto-reshuffle feature, you can configure it this way: $this->cards->autoreshuffle_custom = array('deck' => 'discard'); (replace 'deck' and 'discard' with your custom locations).</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Common_board_game_elements_image_resources&diff=4027
Common board game elements image resources
2020-04-15T21:08:20Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
A lot of games need common image elements.<br />
You can find a lot of image assets online or directly from the publisher.<br />
<br />
But for common elements such as wooden cubes or discs or meeples, here are some image assets that you can use:<br />
<br />
[[File:110_110_dice.png]]<br />
<br />
[[File:25_25_wooden_tokens.png]]<br />
<br />
[[File:30_30_colored_dice.png]]<br />
<br />
[[File:30_30_meeple.png]]<br />
<br />
[[File:30_30_tokens.png]]<br />
<br />
[[File:30_30_wooden_cubes.png]]<br />
<br />
[[File:37_60_hexaedrons.png]]<br />
<br />
[[File:accept.png]]<br />
<br />
[[File:hand.png]]<br />
<br />
[[File:point.png]]<br />
<br />
[[File:refuse.png]]</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=3D&diff=4026
3D
2020-04-15T21:07:52Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
= Overview =<br />
<br />
Board Game Arena is using CSS 3D features to provide a basic 3D view of the games.<br />
<br />
This is not a "100% real" 3D as this is very difficult to play with real 3D model with CSS, but most of the time it provides a satisfying 3D view of the game.<br />
<br />
The objective of 3D is to provide a nice view of the game : 90% of the time, 2D is more suitable for playing. So we don't force developers to make sure games can be played in 3D : this is just a "bonus".<br />
<br />
= Enabling 3D =<br />
<br />
3D is enabled by default for your game.<br />
<br />
You can click on the "3D" button at the top right and see your game in 3D.<br />
<br />
If you don't want to allow players to use 3D with your game, you can add this to you "gameinfos.inc.php" file :<br />
<br />
'enable_3d' => false,<br />
<br />
= Detecting 3D =<br />
<br />
When 3D is "on", BGA adds CSS class "mode_3d" to the body element.<br />
<br />
In CSS, you should prefix all your 3D mode specific directives by ".mode_3d".<br />
<br />
.mode_3d .board {<br />
overflow: visible;<br />
}<br />
<br />
In Javascript, you can detect 3D by using the following :<br />
<br />
if( this.control3dmode3d )<br />
{<br />
// Only executed in 3d mode<br />
}<br />
<br />
= Built-in 3D enhancements =<br />
<br />
BGA is doing some built-in 3D enhancements with your 3D adaptations, so your adaptation will have some 3D effects without any efforts :<br />
<br />
* When executing a slideToObject, a slideToObjectPos or a slideTemporaryObject, BGA is moving the objects vertically (up, then down).<br />
* It also happens when moving elements of a Stock module, or to a Zone module.<br />
<br />
<br />
= Enhance your adaptation for 3D =<br />
<br />
== Use Z axis ==<br />
<br />
Using CSS transform: translateZ, you can translate your HTML elements along the Z axis. Example :<br />
<br />
.floating_element {<br />
transform: translateZ( 20px ); /* This element is going to float 20px above the surface */<br />
}<br />
<br />
The framework will add the following to all your divs:<br />
transform-style: preserve-3d; <br />
<br />
So they will keep their position in 3D space relative to other elemens with the transformation defined. Note that some CSS artifacts can break the css inheritance of the "preserve-3d" like "overflow:auto"<br />
<br />
<br />
At any moment, you can know the Z position of an element from javascript using :<br />
<br />
this.getComputedTranslateZ( html_element );<br />
<br />
== Use pre-build BGA 3D CSS classes ==<br />
<br />
By adding the following classes to your objects, they will look nicer in 3D:<br />
<br />
* thickness: add a (3px) black thickness to your HTML element.<br />
<br />
* roundthickness: (to be used with thickness) if your element is a circle, you should add roundthickness so your element thickness can be a circle too.<br />
<br />
* whitethickness: (to be used with thickness) if you prefer to have a whitethickness instead of black.<br />
<br />
* floatingabove: make your element "float" 10px above the surface, with a nice shadow.<br />
<br />
* roundfloatingabove: (to be used with floatingabove) if your element is a circle, use roundfloatingabove in addition to floatingabove.<br />
<br />
<br />
Note: if you found some generic CSS that may help some other developers for 3D enhancements, please send it to us so we can add it there.<br />
<br />
<br />
== Setting the default point of view and enabling 3d by default ==<br />
<br />
Your game may require to use 3D mode enabled by default and also with a certain custom default PoinOfView. You can achieve this setting in your constructor section of your game:<br />
<br />
'''Important: you must use this only if your game doesn't work without 3D mode.''' As a general platform policy, interface must be optimised for 2D and display in 2D by default. 3D is meant as an option that can be activated by the user if he wants it.<br />
<br />
if (!dojo.hasClass("ebd-body", "mode_3d")) {<br />
dojo.addClass("ebd-body", "mode_3d");<br />
dojo.addClass("ebd-body", "enableTransitions");<br />
$("globalaction_3d").innerHTML = "2D"; // controls the upper right button <br />
this.control3dxaxis = 30; // rotation in degrees of x axis (it has a limit of 0 to 80 degrees in the frameword so users cannot turn it upsidedown)<br />
this.control3dzaxis = 0; // rotation in degrees of z axis<br />
this.control3dxpos = 100; // center of screen in pixels<br />
this.control3dypos = 300; // center of screen in pixels<br />
this.control3dscale = 1.4; // zoom level, 1 is default 2 is double normal size, <br />
this.control3dmode3d = true ; // is the 3d enabled <br />
$("game_play_area").style.transform = <br />
"rotatex(" + this.control3dxaxis + "deg) translate(" + this.control3dypos + "px," + this.control3dxpos + "px) rotateZ(" + this.control3dzaxis + "deg) scale3d(" + this.control3dscale <br />
+ "," + this.control3dscale + "," + this.control3dscale + ")";<br />
}</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Game_replay&diff=4025
Game replay
2020-04-15T21:07:42Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
Game replay is managed by the framework (through replaying javascript notifications).<br />
You do not need to do anything special about it in your code.</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Game_meta-information:_gameinfos.inc.php&diff=4024
Game meta-information: gameinfos.inc.php
2020-04-15T21:05:56Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
From this file, you can edit the various meta-information of your game.<br />
<br />
Once you modified the file, don't forget to click on "Reload game informations" from the Control Panel in order in can be taken into account.<br />
<br />
Most information provided in this file are self-explainable. Some information, though:<br />
<br />
* You are not allowed to set the "'''is_beta'''" to 0 before the game has been released on BGA and stabilized.<br />
<br />
* "'''fast/medium/slow_additional_time'''": please set high values here: after the game has been released, we will lower these value to match the real game duration.<br />
<br />
* "'''players'''":<br />
** during the first step of development of a game, you'd better allow the "1 player" configuration: much easy to start/stop a game this way.<br />
** if you change the minimum number of players from for example 1 to 2, make sure the new tables you create are not restricted from 1 to 1 player otherwise when you create a new table and this account setting is used, there will be a conflict with the new minimum number of players allowed.<br />
<br />
* '''suggest_player_number''' / '''not_recommend_player_number''': don't specify anything here if there is no configuration that is REALLY better/worst than another one. You can check player's poll on BoardGameGeek game page if you have any doubt.<br />
<br />
== Losers not ranked between themselves ==<br />
<br />
By default, all player are ranked, but in some games, the rules says that there is only one winner and that all the other players are losers and not ranked between themselves. You can set this option to true so that for your game, there is only one winner and losers, without a full ranking of all players.<br />
<br />
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true <br />
// The game end result will display "Winner" for the 1st player and "Loser" for all other players<br />
'losers_not_ranked' => false,<br />
<br />
== Disable player rotation in case of rematch ==<br />
<br />
By default, in case of a rematch players are rotated so that the first player changes. If for your game it's better to always have a random player order you can change this option.<br />
<br />
// When doing a rematch, the player order is swapped using a "rotation" so the starting player is not the same<br />
// If you want to disable this, set this to false<br />
'disable_player_order_swap_on_rematch' => false,<br />
<br />
== Custom "buy this game" button ==<br />
<br />
By default, the "buy this game" button is a link to an Amazon search with the name of the game.<br />
<br />
You can replace it by a different URL / game button label with :<br />
<br />
'custom_buy_button' => array(<br />
'url' => 'http://yoururl.com',<br />
'label' => 'Name of the website'<br />
),<br />
<br />
Note : button label will be "Buy on <Name of the website>"<br />
<br />
== Tags ==<br />
<br />
Any number of '''Tags''' can be attribute to your game. Tags are useful to place your game in the correct place and to give a good quick overview of what the game is about to players.<br />
<br />
Main game category (you MUST specify one tag AND ONLY ONE from this category):<br />
* 1: Abstract game<br />
* 2: Casual games<br />
* 3: For regular players<br />
* 4: For core gamers<br />
<br />
Other tags (you can specify any numbers of tags):<br />
* 10: Short game (<10 minutes)<br />
* 11: Medium length game (10 minutes to 30 minutes)<br />
* 12: Long game (>30mn)<br />
* 20: Awarded game (Win a prestigious award) (the game must have been at the '''first''' place of one the [http://boardgamegeek.com/wiki/page/Gaming_Industry_Awards# following major awards list]).<br />
* 22: Prototype (This game has not been published yet)<br />
* 23: Classic (This game is a classic from Public Domain)<br />
* 30: 2 players (2p game / best with 2 players)<br />
* 100: Fantasy theme<br />
* 101: Science Fiction them<br />
* 102: Historical theme<br />
* 103: Adventure<br />
* 104: Exploration<br />
* 105: Conquest<br />
* 106: Building<br />
* 200: Card game (Cards plays a central role in this game)<br />
* 201: Dice<br />
* 202: Solo game<br />
* 203: Worker placement<br />
* 204: Hand management<br />
* 205: Bluff<br />
* 206: Tile placement<br />
* 207: Combinations<br />
* 208: Majority<br />
* 209: Race<br />
* 210: Collection<br />
<br />
== Game Presentation ==<br />
<br />
Short game presentation text that will appear on the game description page, structured as an array of paragraphs.<br />
<br />
Each paragraph must be wrapped with totranslate() for translation and should not contain html (plain text without formatting). A good length for this text is between 100 and 150 words (about 6 to 9 lines on a standard display)<br />
<br />
Example:<br />
'presentation' => array(<br />
totranslate("This wonderful game is about geometric shapes!"),<br />
totranslate("It was awarded best triangle game of the year in 2005 and nominated for the Spiel des Jahres."),<br />
...<br />
),</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Options_and_preferences:_gameoptions.json,_gamepreferences.json&diff=4023
Options and preferences: gameoptions.json, gamepreferences.json
2020-04-15T21:05:47Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
In this file, you can define your game options (= game variants) and user preferences.<br />
<br />
Note: If your game has no variants or preferences, you don't have to modify this file.<br />
<br />
'''IMPORTANT:''' after you edited this file in your SFTP folder you have to go to the control panel and press "Reload game options configuration" for your changes to take effect.<br />
<br />
== Game Options ==<br />
<br />
Game options is something selected by table creator and usually correspond to game variant, for example if game includes expansion or certain special rule.<br />
<br />
These variants defined in gameoptions.inc.php as variable <br />
$game_options = array(...); // exactly named that<br />
<br />
Each option is pair number => 'option description array'. <br />
<br />
All options defined in this file should have a corresponding "game state label" with the same ID (see "initGameStateLabels" in yourgame.game.php)<br />
<br />
self::initGameStateLabels ( array (<br />
...<br />
"my_first_game_variant" => 100,<br />
) );<br />
<br />
That is how you access them during runtime:<br />
<br />
$this->gamestate->table_globals[100]<br />
<br />
The following are the parameters of option description array:<br />
* '''name''' - '''mandatory'''. The name of the option visible for table creator. Value must be wrapped in totranslate function.<br />
* '''values''' - '''mandatory'''. The array (map) of values with additional parameters per value.<br />
** '''name''' - '''mandatory'''. String representation of the numeric value visible to table creator. Value must be wrapped in totranslate function.<br />
** '''description''' - String description of this value to use when the name of the option is not self-explanatory. Displayed at the table under the option when this value is selected.<br />
** '''tmdisplay''' - String representation of the option visible in the table description, usually if variant "names" are On and Off, but the description would be same as option name when On, and nothing when Off.<br />
** '''nobeginner''' - Set to true if not recommended for begginers<br />
** '''beta''' - Option in beta stage on development<br />
** '''premium''' - Option can be only used by premium members<br />
* '''displaycondition''' - checks the conditions before displaying the option for selection. All conditions must be true for the option to display. Supported condition types:<br />
** ''otheroption'' condition ensures another option is set to this given values. Framework options - 201 - ELO OFF.<br />
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given values<br />
* '''displayconditionoperand''' - can be 'and' (this is the default) or 'or'. Allows to change the behaviour to display the option if one of the conditions is true instead of all of them.<br />
* '''startcondition''' - checks the conditions (on options VALUES) before starting the game. All conditions must be true for the game to start, otherwise players will get a red error message when attempting to begin the game. Supported condition types:<br />
** ''minplayers'' condition ensures at least this many players<br />
** ''maxplayers'' conditions ensure at most this many players<br />
** ''otheroption'' conditions ensure another option is set to this given values. That works the same as in '''displaycondition'''.<br />
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given value. That works the same as in '''displaycondition'''.<br />
* '''notdisplayedmessage''' - if option is not suppose to be visible because of displaycondition but this is set, the text will be visible instead of combo drop down<br />
<br />
<pre><br />
$game_options = array(<br />
100 => array(<br />
'name' => totranslate('my game option'),<br />
'values' => array(<br />
// A simple value for this option:<br />
1 => array(<br />
'name' => totranslate('option 1')<br />
),<br />
<br />
// A simple value for this option.<br />
// If this value is chosen, the value of "tmdisplay" is displayed in the game lobby<br />
2 => array(<br />
'name' => totranslate('option 2'),<br />
'tmdisplay' => totranslate('option 2')<br />
),<br />
<br />
// Another value, with other options:<br />
// beta=true => this option is in beta version right now.<br />
// nobeginner=true => this option is not recommended for beginners<br />
3 => array(<br />
'name' => totranslate('option 3'),<br />
'beta' => true,<br />
'nobeginner' => true<br />
),<br />
)<br />
),<br />
<br />
101 => array(<br />
'name' => totranslate('Draft variant'),<br />
'values' => array(<br />
1 => array(<br />
'name' => totranslate('No draft')<br />
),<br />
2 => array(<br />
'name' => totranslate('Draft'),<br />
'tmdisplay' => totranslate('Draft'),<br />
'premium' => true,<br />
'nobeginner' => true<br />
),<br />
),<br />
'displaycondition' => array( <br />
// Note: do not display this option unless these conditions are met<br />
array(<br />
'type' => 'otheroption',<br />
'id' => 100, // Game specific option defined in the same array above<br />
'value' => array(2, 3, 4)<br />
),<br />
// Note: do not display this option unless these conditions are met<br />
array( 'type' => 'otheroption', <br />
'id' => 201, // ELO OFF hardcoded framework option<br />
'value' => 1 // 1 if OFF<br />
)<br />
),<br />
<br />
'startcondition' => array(<br />
1 => array(),<br />
2 => array(<br />
array(<br />
'type' => 'maxplayers',<br />
'value' => 3,<br />
'message' => totranslate('Draft option is available for 3 players maximum.')<br />
)<br />
),<br />
),<br />
),<br />
<br />
102 => array(<br />
'name' => totranslate('Takeovers'),<br />
'values' => array(<br />
2 => array(<br />
'name' => totranslate('No takeover')<br />
),<br />
1 => array(<br />
'name' => totranslate('Allow takeovers'),<br />
'tmdisplay' => totranslate('Takeovers'),<br />
'premium' => true,<br />
'nobeginner' => true<br />
),<br />
),<br />
'displaycondition' => array( // Note: do not display this option unless these conditions are met<br />
array(<br />
'type' => 'otheroption',<br />
'id' => 100,<br />
'value' => array(3, 4)<br />
)<br />
),<br />
'startcondition' => array(<br />
2 => array(),<br />
1 => array(<br />
array(<br />
'type' => 'maxplayers',<br />
'value' => 2,<br />
'message' => totranslate('Rebel vs Imperium Takeover Scenario is available for 2 players only.')<br />
)<br />
),<br />
),<br />
)<br />
);<br />
</pre><br />
<br />
Example of option that condition on ELO off<br />
<br />
<pre><br />
$game_options = array(<br />
<br />
100 => array(<br />
'name' => totranslate('Learning Game (No Research)'),<br />
'values' => array(<br />
<br />
1 => array( 'name' => totranslate('Off'), 'tmdisplay' => totranslate('') ),<br />
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Learning Game') ),<br />
<br />
),<br />
'displaycondition' => array(<br />
// Note: do not display this option unless these conditions are met<br />
array( 'type' => 'otheroption',<br />
'id' => 201, // ELO OFF hardcoded framework option<br />
'value' => 1, // 1 if OFF<br />
<br />
)<br />
),<br />
'notdisplayedmessage' => totranslate('Learning variant available only with ELO off')<br />
),<br />
<br />
);<br />
</pre><br />
<br />
Example of using condition on your own option<br />
<pre><br />
102 => array(<br />
'name' => totranslate('Scenarios'),<br />
'values' => array(<br />
1 => array( 'name' => totranslate('Off'),<br />
'nobeginner' => false ),<br />
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Scenarios'),<br />
'nobeginner' => true ),<br />
<br />
),<br />
'displaycondition' => array(<br />
// Note: do not display this option unless these conditions are met<br />
array( 'type' => 'otheroptionisnot',<br />
'id' => 100, // learning variant<br />
'value' => 2, // 1 if OFF,2 is ON<br />
<br />
)<br />
),<br />
'notdisplayedmessage' => totranslate('Scenarios variant is not available if Learning variant is chosen')<br />
),<br />
</pre><br />
<br />
== User Preferences ==<br />
<br />
User preferences is something cosmetic about the game interface which however can create user wars, so you can satisfy all users<br />
by giving them individual preferences. You should use this only if it significantly improves the interface for a large proportion of users.<br />
<br />
<pre><br />
$game_preferences = array(<br />
100 => array(<br />
'name' => totranslate('Notation style'),<br />
'needReload' => true, // after user changes this preference game interface would auto-reload<br />
'values' => array(<br />
1 => array( 'name' => totranslate( 'Classic' ), 'cssPref' => 'notation_classic' ),<br />
2 => array( 'name' => totranslate( 'Tournament' ), 'cssPref' => 'notation_tournament' )<br />
)<br />
)<br />
);<br />
</pre><br />
<br />
There is two ways to check/apply this. In java Script<br />
<br />
if (this.prefs[100].value == 2) ...<br />
<br />
This checks if preferences 100 has selected value 2.<br />
<br />
Second, if cssPref specified it will be applied to the '''<html>''' tag. So you can use different css styling for the preference. Note: it seems needed to set needReload to true for that class change to be effective.<br />
<br />
As user you have to select them from the Gear menu when game is started. On studio only user0 will have it actually working (bug?).</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Translations&diff=4022
Translations
2020-04-15T21:05:38Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
<br />
Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.<br />
<br />
== How translation works? ==<br />
<br />
When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.<br />
<br />
Before the release of the game, BGA team will do the French translation of the game.<br />
<br />
After the release of the game, the BGA players community will translate the game in every language.<br />
<br />
== What should be translated? ==<br />
<br />
Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages, ...<br />
<br />
This does NOT include error messages that are not supposed to happen (unexpected errors).<br />
<br />
== What rules should I follow for the original English strings? ==<br />
<br />
For a coherent and homogeneous interface, here are some rules about ending a sentence with a final dot '.'<br />
<br />
* As a general rule:<br />
** If a sentence is displayed isolated in the interface => no final dot<br />
** If a sentence is followed or could be followed by another sentence in the same interface space => final dot.<br />
<br />
* In detail:<br />
** No final dot:<br />
*** button labels<br />
*** section titles<br />
*** menu elements<br />
*** links triggering an isolated action<br />
*** anything that is not a full sentence<br />
*** current action in the status bar<br />
** Final dot:<br />
*** complete explanation sentence, that can be chained with another sentence<br />
** We can tolerate a dot or no dot (but it should be consistent inside the game) for:<br />
*** isolated tooltip / isolated small sentence<br />
*** game log (no dot is usually preferable)<br />
*** error messages (except if more than one sentence in the error message => final dot mandatory in this case)<br />
<br />
Otherwise, you should try to follow as closely as possible the general style and format (including capitalization) used in the English rulebook and game material of the game.<br />
<br />
== Focus on translating notifications ==<br />
<br />
Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.<br />
<br />
However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.<br />
<br />
== WARNING: how to make sure your strings will be translated ==<br />
<br />
For each game, our translation tool is doing a full scan of the code, looking for translator markers like "_()" or "clientranslate()"... (see below the list of translation markers).<br />
<br />
If your original string is not "physically" inside one of this marker, it won't be translated.<br />
<br />
<pre><br />
// Examples: the following strings will be translated:<br />
var mystring_translated = _("my string"); // JS<br />
$mystring_translated = self::_("my string"); // PHP<br />
$mystring_translated = sprintf( _("my string with an %s argument"), $argument ); // PHP<br />
<br />
// Examples: the following strings WILL NOT be translated:<br />
$my_string = "my string";<br />
$not_translated = self::_( $my_string ); // The original string is not bordered by a translator marker => no translation<br />
$not_translated = self::_( sprintf( "my string with a %s argument", $argument ) ); // Same thing<br />
</pre><br />
<br />
== How to not make translators crazy ;) ==<br />
<br />
* When you need the same string twice, try to reuse exactly the same string (with the same case) to minimize the number of strings.<br />
* Do not mark as translatable a game element that does not have to be translated (ex: if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).<br />
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:<br />
<pre>_("First part of the string, ").$argument.' '._("second part of the string")</pre><br />
Write instead:<br />
<pre>sprintf( _("First part of the string, %s second part of the string"), $argument )</pre><br />
(or the equivalent "dojo.string.substitute" in Javascript)<br />
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The more the string is a short insignificant string, the more difficult is the task for them. As a rule of thumb, try to avoid insignificant short strings. You can also leave a comment on what is the context of the string in the translation program (English to English) if you are the developer of the game.<br />
* The BGA translation policy is to be flexible on grammar... We prefer to write "player gets 1 coin(s)" than write two versions of the same string for plural and singular - it reduces the number of strings to translate.<br />
* Instead of writing nice strings like "With the effect of ZZZ, player XXX gets a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".<br />
* Use present tense instead of past, i.e. "player gets wood" instead of "player got wood"<br />
* Avoid using gender specific pronouns, i.e. "player returns card to their hand" instead of "player returns card to his hand"<br />
<br />
== On client side (Javascript) ==<br />
<br />
On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.<br />
<br />
Examples:<br />
<pre><br />
// Get a string in player's language:<br />
var translated = _("original english string");<br />
<br />
// Get a string in player's language with parameter:<br />
var translated = dojo.string.substitute( _("You can pick ${p} cards and discard ${d}"), {<br />
p: 2,<br />
d: 4<br />
} );<br />
</pre><br />
<br />
'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.<br />
<br />
== On server side (PHP) ==<br />
<br />
On PHP side, you can use 3 different functions to specify that a string must be translated.<br />
<br />
'''clienttranslate( "my string to translate" ):'''<br />
<br />
This function is '''transparent''': it will return the original English string without any change. It's only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.<br />
<br />
In general, you use clienttranslate:<br />
* On your states.inc.php, for field "description" and "descriptionmyturn".<br />
<br />
<pre><br />
"description" => clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),<br />
</pre><br />
<br />
* On "material.inc.php", when defining texts for game material that must be displayed on client side.<br />
<pre><br />
$this->card_types = array(<br />
<br />
1 => array(<br />
'name' => clienttranslate("Amulet of Air"), // Thus, we can use "_( card_name )" on Javascript side.<br />
</pre><br />
<br />
* When sending a notification with "notifyAllPlayers" or "notifyPlayer", for the game log string and all game log arguments that need a translation.<br />
<br />
<pre><br />
// A game log string with no argument:<br />
self::notifyAllPlayers( 'pickLibraryCards', clienttranslate("Everyone draw cards from his library"), array() );<br />
</pre><br />
<br />
Translating arguments is a little bit more complex. It is using the "i18n" special argument as below:<br />
<br />
<pre><br />
// In the following example, we translate the game log itself, but also the "card_name" argument:<br />
<br />
self::notifyAllPlayers( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(<br />
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be transate<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'points' => $points,<br />
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.<br />
) ); <br />
</pre><br />
<br />
Pay attention when using 'i18n' argument when translating argument for client : do NOT use same argument for both translation AND key code for client side action (like using 'card_name' to move it on player board as described in the example). It's pretty obvious in the example, but it can be very tricky when translation is made at the end of the development (which is often the case). Use explicit argument name like 'card_name_translated' by example.<br />
<br />
'''self::_( "my string to translate" ):'''<br />
<br />
This function returns a string translated in the language of CURRENT user (ie: player who send the request to the server) (be careful, this is NOT the active player).<br />
<br />
Most of the time, you don't need to translate strings on server side, except on the following 3 situations:<br />
* When throwing an exception because the player did a forbidden move.<br />
<br />
<pre><br />
// This will display a translatable red message to the player that just do some wrong action:<br />
throw new BgaUserException( self::_('You must choose 3 cards') );<br />
<br />
// ... notice the use of BgaUserException that signals that this exception is "expected". In theory, all exception that are expected should be translated.<br />
</pre><br />
<br />
* In "yourgame.view.php", when creating the labels for the game interface used in your template (.tpl) file.<br />
<br />
<pre><br />
$this->tpl['CARDS_FOR_YEAR_2'] = self::_("Your cards for year II");<br />
</pre><br />
<br />
* Eventually, in your material.inc.php, if for example you need to use some string elements in your exceptions.<br />
<br />
<pre><br />
// In material.inc.php, $this->energies[n]['nametr'] has been created with the self::_() method. This we can do this:<br />
throw new BgaUserException( self::_("To execute this action you need more: ").' '.$this->energies[$resource_id]['nametr'] );<br />
</pre><br />
<br />
* Eventually, in your "getAllDatas" PHP method, as the data return by this method is used only by current user.<br />
<br />
'''totranslate( "my string to translate" ):'''<br />
<br />
This function works exactly like 'clienttranslate', except it tells BGA that the string is not needed on client side.<br />
<br />
You should not use this function, except on the following cases:<br />
* Statistics name in stats.inc.php<br />
* Option names and option values name in gameoptions.inc.php</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Your_game_mobile_version&diff=4021
Your game mobile version
2020-04-15T21:05:29Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
Board Game Arena is now adaptated for Mobiles and Tablets too.<br />
<br />
It is very easy to have a mobile version of the game you developed with BGA Studio. In fact, your game is probably already 100% playable on mobile.<br />
<br />
However, to provide your players the best experience, you should follow the two piece of advice below.<br />
<br />
== Declare your interface minimum width ==<br />
<br />
By default, your game can run in a window of up to 740 pixels wide. Including the information in the right column (player's panel), it fits on a 1024px wide screen.<br />
<br />
However, you can choose to declare that your game is able to run with a smaller width. This way, the game will appear much better on mobile screens and tablets.<br />
<br />
For example, the Reversi board is only 540px wide. If we stay with the default width (740px), the game interface displayed on mobile will be too large and some space will be lost on the left and on the right. Consequently the Reversi board will appear very small on the mobile screen, and players will have to "pinch & zoom" to display it correctly.<br />
<br />
To avoid that, we can specify that the game can be played with an interface with a minimum width of 540 pixels, by adding the following to '''gameinfos.inc.php''' :<br />
<br />
<br />
// Game interface width range (pixels)<br />
// Note: game interface = space on the left side, without the column on the right<br />
'game_interface_width' => array(<br />
<br />
// Minimum width<br />
// default: 740<br />
// maximum possible value: 740 (i.e. your game interface should fit with a 740px width, corresponding to a 1024px screen)<br />
// minimum possible value: 320 (the lower the value you specify, the better the display is on mobile)<br />
'min' => 540,<br />
<br />
// Maximum width<br />
// default: null (i.e. no limit, the game interface is as big as the player's screen allows).<br />
// maximum possible value: unlimited<br />
// minimum possible value: 740<br />
'max' => null<br />
),<br />
<br />
<br />
And that's it! Now, BGA can choose the better display for your game interface, whatever the device.<br />
<br />
'''Important'''<br />
<br />
If you declare that your interface can run with a 540 pixels width, it must effectively run on an interface with 540 pixels width.<br />
<br />
Note that this doesn't mean that your interface must ''always'' be 540 pixels width; you just have to make your interface fluid and/or use CSS media queries to fit any width.<br />
<br />
Examples :<br />
<br />
* On '''Can't Stop''', when the screen is too narrow, we move the dice on another position (below the main board) to fit within the width :<br />
<br />
@media only screen and (max-width: 990px) {<br />
<br />
#dicechoices {<br />
left: 180px;<br />
top: 530px;<br />
}<br />
#cantstop_wrap {<br />
height: 900px;<br />
width: 550px;<br />
}<br />
}<br />
<br />
* On Seasons, we have some panels on the right of the board. On small screens, we display these panels below the board:<br />
<br />
<br />
@media only screen and (max-width: 970px) {<br />
<br />
#board {<br />
float: none;<br />
margin: auto;<br />
}<br />
.seasons_rightpanel {<br />
margin-left: 0px;<br />
}<br />
<br />
}<br />
<br />
<br />
Tip: on mobile, BGA displays player panels at the top of the page (instead of displaying them on the right). When doing this, BGA applies the CSS class "mobile_version" to the root HTML element with id "ebd-body". If you want you can use this CSS "mobile_version" class to optimize some of your game adaptations to this change. In the opposite, when the "normal" version is active, the CSS class "desktop_version" BGA applies the CSS class "desktop_version" to the root HTML element with id "ebd-body".<br />
<br />
== Touchscreen compatibility ==<br />
<br />
Most of your games should work with touchscreen devices without needing any changes.<br />
<br />
Note: when your game is running on a touchscreen device, the global CSS class "touch-device" is added to the to the root HTML element with id "ebd-body" (and "notouch-device" is added for the opposite).<br />
<br />
What may not work :<br />
* ":hover" CSS switch. Because there is no mouse, ":hover" won't be triggered. This is not an issue unless it is needed to play the game. In addition, some touch devices consider that a short touch must trigger a ":hover" (and should apply corresponding CSS), which can block an interaction in your game. We advise you to explicitely disable ":hover" effects when your game is running on a touchscreen device (for ex. by adding ".notouch-device" as a prefix to all your CSS :hover rules).<br />
* Mouseover events : like the previous one : if you associated Javascript events to "onmouseover" event, it won't work on tablets.<br />
* Drag'n'drop : it won't work. To make it work, you should listen to "ontouchstart", "ontouchmove" and "ontouchend" event and trigger the same logic you already have for "onmousedown", "onmousemove" and "onmouseup". You should also make sure to stop the Javascript "ontouchmove" event (ex: dojo.stopEvent( evt ) ) during the drag n drop, otherwise the interface is going to scroll while drag'n'dropping.</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl&diff=4020
Game layout: view and template: yourgamename.view.php and yourgamename yourgamename.tpl
2020-04-15T21:04:58Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
These 2 files work together to provide the HTML layout of your game.<br />
<br />
Using these 2 files, you specify what HTML is rendered in your game client interface.<br />
<br />
In <yourgame.tpl>, you can directly write raw HTML that will be displayed by the browser.<br />
<br />
Example: extract of "hearts_hearts.tpl":<br />
<br />
<pre><br />
<div id="myhand_wrap" class="whiteblock"><br />
<h3>{MY_HAND}</h3><br />
<div id="myhand"><br />
</div><br />
</div><br />
</pre><br />
<br />
== WARNING ==<br />
<br />
Your view and your template are supposed to generate only the BASE layout of the game<br />
<br />
You shouldn't try to setup the current game situation in the view: this is the role of your Javascript code. Why? Because you'll have to write Javascript code to put game elements in place anyway, and you don't want to write it twice :)<br />
<br />
Example of things to generate in your view:<br />
* The overall layout of your game interface (what is displayed where).<br />
* The board and fixed elements on the board (ex: places for cards, squares, ...).<br />
<br />
Example of things that shouldn't be generate by your view:<br />
* Game elements that come and go from the game area.<br />
* Game elements that normally hidden from players (other players cards, cards in the deck).<br />
<br />
== phplib template system ==<br />
<br />
BGA is using the phplib template system, used for example in PHPbb forums.<br />
<br />
More details about how to use phplib template system here:<br />
http://www.phpbuilder.com/columns/david20000512.php3<br />
<br />
== Variables ==<br />
<br />
In your template ("tpl") file, you can use variables. Then in your view (".view.php") file, you fill these variables with value.<br />
<br />
In the example above, "{MY_HAND}" is a variable. As you can see, a variable is uppercase characters border by "{" and "}".<br />
<br />
To give a value to this variable in your view.php:<br />
<br />
Examples:<br />
<pre><br />
<br />
// Display a translated version of "My hand" at the place of the variable in the template<br />
$this->tpl['MY_HAND'] = self::_("My hand");<br />
<br />
// Display some raw HTML material at the place of the variable<br />
$this->tpl['MY_HAND'] = self::raw( "<div class='myhand_icon'></div>" );<br />
<br />
</pre><br />
<br />
WARNING: do not use a variable called {id} as it will interfere with action buttons.<br />
<br />
== Blocks ==<br />
<br />
Using "blocks", you can repeat a piece of HTML from your template several time.<br />
<br />
You should use "blocks" whenever you have a block of HTML that must be repeated many times. For example, for ''Reversi'', we have to generate 64 (8x8) squares:<br />
<br />
<pre><br />
<br />
(in reversi_reversi.tpl)<br />
<br />
<div id="board"><br />
<!-- BEGIN square --><br />
<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div><br />
<!-- END square --><br />
<br />
<div id="discs"><br />
</div><br />
</div><br />
<br />
(in reversi.view.php)<br />
<br />
$this->page->begin_block( "reversi_reversi", "square" );<br />
<br />
$hor_scale = 64.8;<br />
$ver_scale = 64.4;<br />
for( $x=1; $x<=8; $x++ )<br />
{<br />
for( $y=1; $y<=8; $y++ )<br />
{<br />
$this->page->insert_block( "square", array(<br />
'X' => $x,<br />
'Y' => $y,<br />
'LEFT' => round( ($x-1)*$hor_scale+10 ),<br />
'TOP' => round( ($y-1)*$ver_scale+7 )<br />
) );<br />
} <br />
}<br />
<br />
</pre><br />
<br />
Explanations:<br />
* You specify a block in your template file, using "BEGIN" and "END" keywords. In the example above, we are creating a block named "square".<br />
* In your view, you declare your block using "begin_block" method.<br />
* Then, you can insert as many block as you want to, using "insert_block" method.<br />
<br />
The insert_block method takes 2 parameters:<br />
* the name of the block to insert.<br />
* an associative array you can use to assign values to template variables of this block. In the example above, there are 4 parameters in the block (X, Y, LEFT and TOP).<br />
<br />
== Nested blocks ==<br />
<br />
You can use nested blocks. In the example below, we are going to add a mini-board for each player of the game, with 4 card places on each of it:<br />
<br />
<pre><br />
<br />
(In template file)<br />
<br />
<!-- BEGIN player --><br />
<div class="miniboard" id="miniboard_{PLAYER_ID}"><br />
<br />
<div class="card_places"><br />
<!-- BEGIN card_place --><br />
<div id="card_place_{PLAYER_ID}_{PLACE_ID}"><br />
</div><br />
<!-- END card_place --><br />
</div><br />
<br />
</div><br />
<!-- END player --><br />
<br />
(In view file)<br />
<br />
$this->page->begin_block( "mygame_mygame.tpl", "card_place" ); // Nested block must be declared first<br />
$this->page->begin_block( "mygame_mygame.tpl", "player" );<br />
<br />
foreach( $players as $player_id => $player )<br />
{<br />
// Important: nested block must be reset here, otherwise the second player miniboard will<br />
// have 8 card_place, the third will have 12 card_place, and so one...<br />
$this->page->reset_subblocks( 'card_place' ); <br />
<br />
for( $i=1; $i<=4; $i++ )<br />
{<br />
$this->page->insert_block( "card_place", array( <br />
'PLAYER_ID' => $player_id,<br />
'PLACE_ID' => $i<br />
);<br />
}<br />
<br />
$this->page->insert_block( 'player', array( 'PLAYER_ID' => $player_id );<br />
}<br />
<br />
</pre><br />
<br />
== Javascript templates ==<br />
<br />
For game elements that come and go from the game area, we suggest you to define a Javascript template.<br />
<br />
A Javascript template is defined in your template file like this:<br />
<br />
(Reversi Token from Reversi example):<br />
<pre><br />
<script type="text/javascript"><br />
<br />
// Templates<br />
<br />
var jstpl_disc='<div class="disc disccolor_${color}" id="disc_${xy}"></div>';<br />
<br />
</script> <br />
</pre><br />
<br />
Note: a section for javascript templates is already available at the end of your template skeleton file.<br />
<br />
Then, you can use this javascript template to insert this piece of HTML in your game interface, like this:<br />
<br />
<pre><br />
dojo.place( this.format_block( 'jstpl_disc', {<br />
xy: x+''+y,<br />
color: color<br />
} ) , 'discs' );<br />
</pre><br />
<br />
WARNING: always use lowercase for substitution variables in your Javascript templates, in order to avoid collision with phplib template variables (in particular, do not use ${ID}).<br />
<br />
== How to access game information from .view.php? ==<br />
<br />
From your .view.php, you can access the following:<br />
<br />
=== Access current player id===<br />
<br />
<pre><br />
global $g_user;<br />
$current_player_id = $g_user->get_id();<br />
</pre><br />
<br />
=== Access game object ===<br />
<br />
In your view file, "$this->game" contains an instance of your main game class.<br />
<br />
Example:<br />
<pre><br />
<br />
// Access to some game elements description described in your "material.inc.php":<br />
$my_cards_types = $this->game->card_types;<br />
<br />
// Access to any (public) method defined in my .game.php file:<br />
$result = $this->game->myMethod();<br />
</pre><br />
<br />
== Tips: displaying a nice button ==<br />
<br />
From time to time, you need to display a standard button in your interface. BGA framework provides you a standard button that you can use directly in your interface:<br />
<br />
<pre><br />
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a><br />
</pre><br />
<pre><br />
<a href="#" id="my_button_id" class="bgabutton bgabutton_gray"><span>My gray button</span></a><br />
</pre><br />
<pre><br />
<a href="#" id="my_button_id" class="bgabutton bgabutton_red"><span>My red button</span></a><br />
</pre><br />
<pre><br />
<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a><br />
</pre><br />
<br />
<br />
Note: To see it in action, check for example a Coloretto game</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Game_interface_stylesheet:_yourgamename.css&diff=4019
Game interface stylesheet: yourgamename.css
2020-04-15T21:04:45Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This is the CSS stylesheet of your game User Interface.<br />
<br />
Styles defined on this file will be applied to the HTML elements you define in your HTML template (yourgame_yourgame.tpl), and to HTML elements you create dynamically with Javascript.<br />
<br />
Usually, you are using CSS to:<br />
<br />
1°) define the overall layout of your game<br />
(ex: place the board on the top left, place player's hand beside, place the deck on the right, ...).<br />
<br />
2°) create your CSS-sprites:<br />
All images of your games should be gathered into a small number of image files. Then, using background-image and background-position CSS properties, you create HTML blocks that can display these images correctly.<br />
<br />
Example:<br />
<pre><br />
Example of CSS sprites (a black token and a white token, 20x20px each, embedded in the same "tokens.png" 40x20px image):<br />
<br />
.white_token {<br />
background-image: url('img/tokens.png');<br />
background-position: 0px 0px;<br />
}<br />
.black_token {<br />
background-image: url('img/tokens.png');<br />
background-position: -20px 0px;<br />
}<br />
.token {<br />
width: 20px;<br />
height: 20px;<br />
background-repeat: none;<br />
}<br />
</pre><br />
<br />
3°) ... anything else:<br />
<br />
It is really easy to add and remove CSS classes dynamically from your Javascript with dojo.addClass and dojo.removeClass. It is also easy to check if an element has a class (dojo.hasClass) or to get all elements with a specific class (dojo.query). <br />
<br />
This is why, very often, using CSS classes for the logic of your user interface allow you to do complex thing easily.<br />
<br />
Note: on the production platform, this file will be compressed and comments will be removed. Consequently, don't hesitate to put as many comments as necessary.<br />
<br />
Important: ALL the CSS directives for your game must be included in this CSS file. You can't create additional CSS files and import them.<br />
<br />
== Warning: using Z-index ==<br />
<br />
You may use z-index CSS property in your game interface, but you should pay attention to the following: BGA dialogs are displayed with a z-index of 950. If you want to use z-index safely, you should use value '''lower than 900'''.<br />
<br />
About z-index: don't forget that if you are using a z-index, your element will be displayed above all elements that do not have a z-index. So it's no use to have big z-index values: 1 is enough most of the time :)<br />
<br />
== spectatorMode ==<br />
<br />
When a spectator (= a player that is not part of the game) is viewing a game, the BGA framework add the CSS class "spectatorMode" to the wrapping HTML tag of your game.<br />
<br />
This way, if you want to apply a special style to some elements of your game for spectators, you can do this in your CSS:<br />
<br />
<pre><br />
.spectatorMode #your_element_id {<br />
/* your special style */<br />
}<br />
</pre><br />
<br />
The most common usage of this is to hide some elements to spectators. For example, to hide "my hand" elements:<br />
<br />
<pre><br />
.spectatorMode #my_hand {<br />
display: none;<br />
}<br />
</pre></div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Game_art:_img_directory&diff=4018
Game art: img directory
2020-04-15T21:04:34Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
== Requested images ==<br />
<br />
The following images are requested by BGA:<br />
<br />
;game_box.png<br />
* It is displayed on the main site on the game description page and when creating a table (280x280 px).<br />
* It should be a 3D image of a physical copy of the game box as it appears in an online shop.<br />
* It is better to take the version of the game that is coherent with the game art used in the adaptation, and from the original publisher of the game.<br />
* The background of the image must be transparent.<br />
* If you don't have a 3D version of the game box, you can use the following website to create one: http://www.3d-pack.com/<br />
<br />
;game_box180.png<br />
;game_box75.png<br />
<br />
* Don't modify these images, they are auto generated by "Reload game box image" action. If you have another copy of your source make sure you update you copy of these files after they have been generated and not override with old copied.<br />
<br />
;game_icon.png<br />
<br />
* It is the icon displayed in the lists of games and tables (50x50 px).<br />
* The objective of this icon is to make the game recognizable among the other games. A good idea is to take a part of the game cover that is distinctive (ex: the game title).<br />
* This one does not have to be transparent. This image should not have a border <br />
<br />
;publisher.png<br />
* It is the logo of the publisher of the game, displayed on the game description page.<br />
* The width must be 150 px. The height can be anything (reasonable). The image could be transparent.<br />
<br />
;publisher2.png (optional)<br />
* If the game has been co-published by 2 publishers, you should upload a second image named "publisher2.png" (same characteristics as the first one).<br />
<br />
;game_banner.jpg<br />
* size 1386x400px<br />
* should not contain any text; representative of the atmosphere of the game such as a cover element or communication image; the box image covering the banner on the left should stand out<br />
<br />
;game_displayX.jpg (X an integer between 0 and 9)<br />
* height between 400px and 760px, width maximum 1.5 x height;<br />
* the idea is to make players want to play the game, so it could be a zoomed card, some detail of the board, an overview of an ongoing physical game... but NOT a screenshot of the BGA adaptation since there is already the "see game in action" replay for that<br />
<br />
'''Important''': when you modify these images, you MUST click on "Reload game box image" from the Control Panel in order your update can be taken into account.<br />
<br />
== Game art ==<br />
<br />
You must upload in img directory all images of your game interface.<br />
<br />
=== Images naming constraints ===<br />
<br />
To be correctly deployed your images file names should not contain spaces or parenthesis.<br />
<br />
=== Images loading ===<br />
<br />
'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.<br />
<br />
Note that you can tune the way images are loaded with Javascript method "dontPreloadImage" (see [[Game_interface_logic:_yourgamename.js|Game Interface Logic]]).<br />
<br />
General recommendation it to have no more than dozen of image files, 2Mb max each. However if there is heavy game resources specific to a player (i.e. player board of specific color or set of cards) it is better to separate them and "don't pre-load" since in any given game only some of them will be used.<br />
<br />
=== Images format ===<br />
<br />
You can use 3 image format while building your game interface:<br />
;jpg images<br />
<br />
should be used for non-transparent images. Jpg are usually lighter than Pngs, so please choose Jpg for big pictures (ex: game board, cards) when you don't need transparency to accelerate game load. You don't need transparency for rounded card corners, it can be done using css.<br />
<br />
;png images<br />
<br />
should be used for images with transparency, such as non-square tokens, meeples, etc (combined into sprite).<br />
<br />
;gif images<br />
<br />
can be used for animated images. This is not recommended to use gif animated images as they can upset players, but for some specific interface element this could be useful.<br />
<br />
=== Use CSS Sprites ===<br />
<br />
To limit the number of images load and make the game load faster, you must use CSS sprites, i.e. you must gather several images in a single one. However, there are limitations. Do not make any CSS image sprite with dimensions that exceed 4096x4096 pixels or it will not work on mobile devices (Android max texture size is 4096 pixels, test your own browser at [http://webglreport.com/ WebGL Report]).<br />
<br />
To learn more on CSS Sprites:<br />
* [http://www.w3schools.com/css/css_image_sprites.asp CSS sprites (W3C documentation)].<br />
* [[Game interface stylesheet: yourgamename.css]]<br />
<br />
=== Shrink images ===<br />
<br />
If you get high resolution images from publisher you need to shrink them since web display requires much lower resolution than printing.<br />
<br />
* Shrink images without loss of quality https://tinypng.com/ or http://www.iloveimg.com/<br />
<br />
== Image Manipulation Tools ==<br />
<br />
You have no choice but to use one of the image manipulating tools to create a successful game adaptation, you would have to<br />
deal with<br />
* Converting to supported formats<br />
* Adding transparency <br />
* Stitching<br />
* Shrinking with no quality loss<br />
* Resizing<br />
<br />
For that you need a good tools, recommended tools (if you know more add them here)<br />
* Gimp (linux) - general GUI image editor<br />
* Paint.net (Windows) - general GUI image editor<br />
* ImageMagic (All platforms) - https://www.imagemagick.org/script/download.php - command line image editor, great for mass manipulations and scripting</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Game_interface_logic:_yourgamename.js&diff=4017
Game interface logic: yourgamename.js
2020-04-15T21:03:50Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This is the main file for your game interface. Here you will define:<br />
<br />
* Which actions on the page will generate calls to the server.<br />
* What happens when you get a notification for a change from the server and how it will show in the browser. <br />
<br />
== File structure ==<br />
<br />
The details of how the file is structured are described below with comments on the code skeleton provided to you.<br />
<br />
Here is the basic structure:<br />
<br />
* '''constructor''': here you can define global variables for your whole interface.<br />
* '''setup''': this method is called when the page is refreshed, and sets up the game interface.<br />
* '''onEnteringState''': this method is called when entering a new game state. You can use it to customize the view for each game state.<br />
* '''onLeavingState''': this method is called when leaving a game state.<br />
* '''onUpdateActionButtons''': called when entering a new state, in order to add action buttons to the status bar.<br />
* ''(utility methods)'': this is where you can define your utility methods.<br />
* ''(player's actions)'': this is where you can write your handlers for player actions on the interface (example: click on an item).<br />
* '''setupNotifications''': this method associates notifications with notification handlers. For each game notification, you can trigger a javascript method to handle it and update the game interface.<br />
* ''(notification handlers)'': this is where you define the notifications handlers associated with notifications in '''setupNotifications''', above.<br />
<br />
== General tips ==<br />
<br />
; this.player_id<br />
: ID of the player on whose browser the code is running.<br />
<br />
; this.isSpectator<br />
: Flag set to true if the user at the table is a spectator (not a player).<br />
: Note: This is a variable, not a function.<br />
: Note: If you want to hide an element from spectators, you should use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].<br />
<br />
; this.gamedatas<br />
: Contains the initial set of data to init the game, created at game start or by game refresh (F5).<br />
: You can update it as needed to keep an up-to-date reference of the game on the client side if you need it. (Most of the time this is unnecessary).<br />
<br />
; this.isCurrentPlayerActive()<br />
: Returns true if the player on whose browser the code is running is currently active (it's his turn to play).<br />
<br />
; this.getActivePlayerId()<br />
: Return the ID of the active player, or null if we are not in an "activeplayer" type state.<br />
<br />
; this.getActivePlayers()<br />
: Return an array with the IDs of players who are currently active (or an empty array if there are none).<br />
<br />
; this.bRealtime<br />
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.<br />
<br />
== Dojo framework ==<br />
<br />
BGA uses the [http://dojotoolkit.org/ Dojo Javascript framework].<br />
<br />
The Dojo framework allows us to do complex things more easily. The BGA framework uses Dojo extensively.<br />
<br />
To implement a game, you only need to use a few parts of the Dojo framework. All the Dojo methods you need are described on this page.<br />
<br />
== Shrinksafe minimization ==<br />
<br />
For performance reasons, when deploying a game the js code is minimized using Shrinksafe (based on ECMASCRIPT version 3). Some advanced syntax may not be compatible with this process. In particular:<br />
* You should not use reserved keywords from the javascript language as variables.<br />
* You should not declare default argument values in function declarations. The following syntax is invalid for Shrinksafe: '''function myFunc(requiredArg, optionalArg = 'defaultValue') {}'''<br />
<br />
== Accessing and manipulating the DOM ==<br />
<br />
'''$('some_html_element_id')'''<br />
<br />
The $() function is used to get an HTML element using its "id" attribute.<br />
<br />
Example 1: modify the content of a "span" element:<br />
<br />
<pre><br />
In your HTML code:<br />
<span id="a_value_in_the_game_interface">1234</span><br />
<br />
In your Javascript code:<br />
$('a_value_in_the_game_interface').innerHTML = "9999";<br />
</pre><br />
<br />
Note: $() is the standard method to access some HTML element with the BGA Framework. You should not use the '''getElementById''' function.<br />
<br />
<br />
'''dojo.style'''<br />
<br />
With dojo.style you can modify the CSS property of any HTML element in your interface.<br />
<br />
Examples:<br />
<br />
<pre><br />
// Make an element disappear<br />
dojo.style( 'my_element', 'display', 'none' );<br />
<br />
// Give an element a 2px border<br />
dojo.style( 'my_element', 'borderWidth', '2px' );<br />
<br />
// Change the background position of an element<br />
// (very practical when you are using CSS sprites to transform an element to another)<br />
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );<br />
</pre><br />
<br />
Note: you must always use dojo.style to modify the CSS properties of HTML elements.<br />
<br />
Note²: if you have to modify several CSS properties of an element, or if you have a complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).<br />
<br />
'''dojo CSS classes manipulation'''<br />
<br />
In many situations, many small CSS property updates can be replaced by a CSS class change (i.e., you add a CSS class to your element instead of applying all modifications manually).<br />
<br />
Advantages are:<br />
* All your CSS stuff remains in your CSS file.<br />
* You can add/remove a list of CSS modifications with a simple function and without error.<br />
* You can test whether you applied the CSS to an element with the '''dojo.hasClass''' method.<br />
<br />
Example from ''Reversi'':<br />
<br />
<pre><br />
// We add "possibleMove" to an element<br />
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );<br />
<br />
// In our CSS file, the class is defined as:<br />
.possibleMove {<br />
background-color: white;<br />
opacity: 0.2;<br />
filter:alpha(opacity=20); /* For IE8 and earlier */ <br />
cursor: pointer; <br />
}<br />
<br />
// So we've applied 4 CSS property changes in one line of code.<br />
<br />
// ... and when we need to check if a square is a possible move on the client side:<br />
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )<br />
{ ... }<br />
<br />
// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );<br />
</pre><br />
<br />
Conclusion: We encourage you to use '''dojo.addClass''', '''dojo.removeClass''' and '''dojo.hasClass''' to make your life easier :)<br />
<br />
'''dojo.query'''<br />
<br />
With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.<br />
<br />
Example:<br />
<pre><br />
// All elements with class "possibleMove":<br />
var elements = dojo.query( '.possibleMove' );<br />
<br />
// Count number of tokens (i.e., elements of class "token") on the board (i.e., the element with id "board"):<br />
dojo.query( '#board .token' ).length;<br />
</pre><br />
<br />
But what is really cool with dojo.query is that you can combine it with almost all methods above.<br />
<br />
Examples:<br />
<pre><br />
// Trigger a method when the mouse enter in any element with class "meeple":<br />
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );<br />
<br />
// Hide all meeples who are on the board<br />
dojo.query( '#board .meeple' ).style( 'display', 'none' );<br />
</pre><br />
<br />
'''dojo.place'''<br />
<br />
dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.<br />
<br />
<pre><br />
// Insert your HTML code as a child of a container element<br />
dojo.place( "<your html code>", "your_container_element_id" );<br />
<br />
// Replace the container element with your new html<br />
dojo.place( "<your html code>", "your_container_element_id", "replace" );<br />
<br />
</pre><br />
<br />
The third parameter of dojo.place can take various interesting value.<br />
<br />
values possibles :<br />
<br />
"replace" : (see description above).<br />
<br />
"first" : Places the node as a child of the reference node. The node is placed as the first child.<br />
<br />
"last" : Places the node as a child of the reference node. The node is placed as the last child.<br />
<br />
"before" : places the node right before the reference node.<br />
<br />
"last (value by default) " : places the node right after the reference node.<br />
<br />
"only" : replaces all children of the reference node with the node.<br />
<br />
positif integer : This parameter can be a positif integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child. <br />
<br />
See also full doc on dojo.place : [http://dojotoolkit.org/reference-guide/1.7/dojo/place.]<br />
<br />
Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".<br />
<br />
'''addStyleToClass: function( cssClassName, cssProperty, propertyValue )'''<br />
<br />
Same as dojo.style(), but for all the nodes set with the specified cssClassName<br />
<br />
=== Animations ===<br />
<br />
'''Dojo Animations'''<br />
<br />
BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).<br />
<br />
However, most of the time, you can just use methods below, which are built on top of Dojo Animation.<br />
<br />
Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.<br />
<br />
'''this.slideToObject( mobile_obj, target_obj, duration, delay )'''<br />
<br />
You can use slideToObject to "slide" an element to a target position.<br />
<br />
Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.<br />
<br />
The parameters are:<br />
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.<br />
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.<br />
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.<br />
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.<br />
<br />
BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.<br />
<br />
Example:<br />
<pre><br />
this.slideToObject( "some_token", "some_place_on_board" ).play();<br />
</pre><br />
<br />
<br />
'''this.slideToObjectPos( mobile_obj, target_obj, target_x, target_y, duration, delay )'''<br />
<br />
This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".<br />
<br />
Example: slide a token to some place on the board, 10 pixels to the bottom:<br />
<pre><br />
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();<br />
</pre><br />
<br />
'''this.slideTemporaryObject( mobile_obj_html, mobile_obj_parent, from, to, duration, delay )'''<br />
<br />
This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.<br />
<br />
slideTemporaryObject does all of this for you:<br />
* mobile_obj_html is a piece of HTML code that represent the object to slide.<br />
* mobile_obj_parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.<br />
* from is the ID of the origin of the slide.<br />
* to is the ID of the target of the slide.<br />
* duration/delay works exactly like in "slideToObject"<br />
<br />
Example:<br />
<pre><br />
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' );<br />
</pre><br />
<br />
'''this.slideToObjectAndDestroy: function( node, to, time, delay )'''<br />
<br />
This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.<br />
<br />
It works the same as this.slideToObject and takes the same arguments. <br />
<br />
Example:<br />
<pre><br />
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );<br />
</pre><br />
<br />
'''this.fadeOutAndDestroy( node, duration, delay )'''<br />
<br />
This function fade out the target HTML node, then destroy it.<br />
<br />
Example:<br />
<pre><br />
this.fadeOutAndDestroy( "a_card_that_must_disappear" );<br />
</pre><br />
<br />
CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.<br />
<br />
'''Rotating elements'''<br />
<br />
You can check here [http://jimfulton.info/demos/dojo-animated-rotate.html an example of use] of Dojo to make an element rotate.<br />
<br />
This example combines "Dojo.Animation" method and a CSS3 property that allow you to rotate the element.<br />
<br />
IMPORTANT: to asses browser compatibility, you must select the CSS property to use just like in the example (see sourcecode below):<br />
<br />
<pre><br />
var transform;<br />
dojo.forEach(<br />
['transform', 'WebkitTransform', 'msTransform',<br />
'MozTransform', 'OTransform'],<br />
function (name) {<br />
if (typeof dojo.body().style[name] != 'undefined') {<br />
transform = name;<br />
}<br />
});<br />
// ... and then use "transform" as the name of your CSS property for rotation<br />
</pre><br />
<br />
'''Animation Callbacks'''<br />
<br />
If you wish to run some code only after an animation has completed you can do this by linking a callback method.<br />
<br />
<pre><br />
var animation_id = this.slideToObject( mobile_obj, target_obj, duration, delay );<br />
dojo.connect(animation_id, 'onEnd', dojo.hitch(this, 'callback_function', parameters));<br />
animation_id.play();<br />
<br />
…<br />
<br />
callback_function: function(params) {<br />
// this will be called after the animation ends<br />
},<br />
</pre><br />
<br />
If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).<br />
<br />
=== Moving elements ===<br />
<br />
'''this.placeOnObject( mobile_obj, target_obj )'''<br />
<br />
placeOnObject works exactly like "slideToObject", except that the effect is immediate.<br />
<br />
This is not really an animation, but placeOnObject is frequently used before starting an animation.<br />
<br />
Example:<br />
<pre><br />
// (We just created an object "my_new_token")<br />
<br />
// Place the new token on current player board<br />
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );<br />
<br />
// Then slide it to its position on the board<br />
this.slideToObject( "my_new_token", "a_place_on_board" ).play();<br />
</pre><br />
<br />
'''this.placeOnObjectPos( mobile_obj, target_obj, target_x, target_y )'''<br />
<br />
This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates. This way, "mobile_obj" will be placed to the specified x,y position relatively to "target_obj".<br />
<br />
'''this.attachToNewParent( mobile_obj, target_obj )'''<br />
<br />
With this method, you change the HTML parent of "mobile_obj" element. "target_obj" is the new parent of this element. The beauty of <br />
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.<br />
<br />
Note: what happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.<br />
<br />
Why using this method?<br />
<br />
Changing the HTML parent of an element can be useful for the following reasons:<br />
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.<br />
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.<br />
<br />
CAREFUL: this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).<br />
<br />
== Players input ==<br />
<br />
'''dojo.connect'''<br />
<br />
Used to associate a player event with one of your notification method.<br />
<br />
Example: associate a click on an element ("my_element") with one of our method ("onClickOnMyElement"):<br />
<pre><br />
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );<br />
</pre><br />
<br />
Note: this is the only possible correct way to associate a player input event to your code, and you must not use anything else.<br />
<br />
'''this.checkAction( "my_action_name" )'''<br />
<br />
Usage: checkAction: function( action, nomessage )<br />
<br />
Check if player can do the specified action by taking into account:<br />
* current game state<br />
* interface locking (a player can't do any action if an action is already in progress)<br />
<br />
Restricted arguments names (please don't use them):<br />
<br />
* "action"<br />
* "module"<br />
* "class"<br />
return true if action is authorized (ie: the action is listed as a "possibleaction" in current game state).<br />
<br />
return false and display an error message if not (display no message if nomessage parameter is true). The displayed error message could be either "This move is not allowed at this moment" or "An action is already in progress".<br />
<br />
Example:<br />
<pre><br />
function onClickOnGameElement( evt )<br />
{<br />
if( this.checkAction( "my_action" ) )<br />
{<br />
// Do the action<br />
}<br />
}<br />
</pre><br />
<br />
'''this.checkPossibleActions( "my_action_name" )'''<br />
<br />
Usage: checkPossibleActions: function( action, nomessage )<br />
<br />
* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. <br />
<br />
Check if player can do the specified action by taking into account:<br />
* current game state<br />
* interface locking (a player can't do any action if an action is already in progress)<br />
<br />
Restricted arguments names (please don't use them):<br />
* "action"<br />
* "module"<br />
* "class"<br />
<br />
'''this.ajaxcall( url, parameters, obj_callback, callback, callback_error )'''<br />
<br />
This method must be used to send a player input to the game server.<br />
<br />
* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"<br />
* parameters: an array of parameter to send to the game server. Note that "lock:true" must always be specified in this list of parameter in order the interface can be locked during the server call.<br />
* obj_callback: must be set to "this".<br />
* callback: a function to trigger when the server returns and everything went fine.<br />
* callback_error: (optional and rarely used) a function to trigger when the server returns an error.<br />
<br />
Usage:<br />
<pre><br />
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true, <br />
arg1: myarg1, <br />
arg2: myarg2, <br />
...<br />
}, this, function( result ) {<br />
// Do some stuff after a successful call<br />
} );<br />
</pre><br />
<br />
'''this.confirmationDialog()'''<br />
<br />
Display a confirmation dialog with a yes/no choice.<br />
<br />
We advice you to NOT use this function unless the player action is really critical and could ruins the game, because it slows down the game and upset players.<br />
<br />
Usage: this.confirmationDialog( "Question to displayed", callback_function_if_click_on_yes );<br />
<br />
Example:<br />
<pre><br />
this.confirmationDialog( _('Are you sure to use this bonus (points penalty at the end of the game) ?'),<br />
dojo.hitch( this, function() {<br />
this.ajaxcall( '/seasons/seasons/useBonus.html',<br />
{ id:bonus_id, lock:true }, this, function( result ) {} );<br />
} ) ); <br />
</pre><br />
<br />
<br />
; addEventToClass: function( cssClassName, eventName, functionName )<br />
: Same as dojo.connect(), but for all the nodes set with the specified cssClassName<br />
<br />
'''this.addActionButton( id, label, method, (opt)destination, (opt)blinking, (opt)color )'''<br />
<br />
You can use this method to add an action button in the main action status bar.<br />
<br />
Arguments:<br />
* id: an element ID that should be unique in your HTML DOM document.<br />
* label: the text of the button. Should be translatable (use _() function).<br />
* method: the name of your method that must be triggered when the player clicks on this button.<br />
* destination (optional): deprecated, do not use this. Use '''null''' as value if you need to specify other arguments.<br />
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please don't abuse of blinking button.<br />
* color: could be '''blue''' (default), '''red''' or '''gray'''.<br />
<br />
You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this (from Hears example):<br />
<br />
<pre><br />
onUpdateActionButtons: function( stateName, args ) {<br />
<br />
if (this.isCurrentPlayerActive()) { <br />
switch( stateName ) {<br />
case 'giveCards':<br />
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' ); <br />
break;<br />
}<br />
}<br />
}, <br />
</pre><br />
<br />
In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.<br />
<br />
Example using blinking red button:<br />
<pre><br />
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', null, true, 'red'); <br />
</pre><br />
<br />
Note: at least in studio example above will make button huge, because it sets it display of blinking things to '''block''', <br />
if you don't like it you have to change css display value<br />
of the button to inline-block (the id of the button is the first argument, i.e 'commit_button' in example above)<br />
<br />
== Translations ==<br />
<br />
See [[Translations]]<br />
<br />
== Notifications ==<br />
<br />
When something happens on the server side, your game interface Javascript logic received a notification.<br />
<br />
Here's how you can handle these notifications on the client side.<br />
<br />
=== Subscribe to notifications ===<br />
<br />
Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.<br />
<br />
Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):<br />
<br />
<pre><br />
// In setupNotifications method:<br />
dojo.subscribe( 'playDisc', this, "notif_playDisc" );<br />
</pre><br />
<br />
Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.<br />
<br />
Then, you have to define your "notif_playDisc" method:<br />
<br />
<pre><br />
notif_playDisc: function( notif )<br />
{<br />
// Remove current possible moves (makes the board more clear)<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' ); <br />
<br />
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );<br />
},<br />
</pre><br />
<br />
In a notification handler like our "notif_playDisc" method, you can access to all notifications arguments with "notif.args".<br />
<br />
Example:<br />
<pre><br />
// If you did this on PHP side:<br />
self::notifyAllPlayers( "myNotification", '', array( "myArgument" => 3 ) );<br />
<br />
// On Javascript side, you can access the "myArgument" like this:<br />
notif_myNotification: function( notif )<br />
{<br />
alert( "myArgument = " + notif.args.myArgument );<br />
}<br />
</pre><br />
<br />
<br />
=== Synchronous notifications ===<br />
<br />
When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.<br />
<br />
However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, they are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.<br />
<br />
As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.<br />
<br />
Here's how we do this, right after our subscription:<br />
<pre><br />
dojo.subscribe( 'playDisc', this, "notif_playDisc" );<br />
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler<br />
</pre><br />
<br />
<br />
=== Pre-defined notification types ===<br />
<br />
'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.<br />
<br />
'''message''' - This defines notification that shows on players log and have no other effect<br />
<br />
// You can call this on php side without doing anything on client side<br />
self::notifyAllPlayers( 'message', 'hello', array( ) );<br />
<br />
== Tooltips ==<br />
<br />
'''this.addTooltip( nodeId, _( helpString ), _( actionString ), delay )'''<br />
<br />
Add a simple text tooltip to the DOM node.<br />
<br />
Specify 'helpString' to display some information about "what is this game element?".<br />
Specify 'actionString' to display some information about "what happens when I click on this element?".<br />
<br />
You must specify both helpString and actionString. Most of the time, you should use only one and specify a void string ("") for the other one.<br />
<br />
Usually, _() must be used for the text to be marked for translation.<br />
<br />
"Delay" is an optional parameter. Usually, it is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).<br />
<br />
Example:<br />
<pre><br />
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );<br />
</pre><br />
<br />
'''this.addTooltipHtml( nodeId, html, delay )'''<br />
<br />
Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).<br />
<br />
'''this.addTooltipToClass( cssClass, _( helpString ), _( actionString ), delay )'''<br />
<br />
Add a simple text tooltip to all the DOM nodes set with this cssClass. <br />
<br />
IMPORTANT: all concerned nodes must have IDs to get tooltips.<br />
<br />
'''this.addTooltipHtmlToClass( cssClass, html, delay )'''<br />
<br />
Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).<br />
<br />
IMPORTANT: all concerned nodes must have IDs to get tooltips<br />
<br />
'''this.removeTooltip( nodeId )'''<br />
<br />
Remove a tooltip from the DOM node.<br />
<br />
== Dialogs, warning messages, confirmation dialogs, ... ==<br />
<br />
=== Warning messages ===<br />
<br />
Sometimes, there is something important that is happening on the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.<br />
<br />
Ex: someone fulfill one of the end of the game condition, so this is the last turn.<br />
<br />
'''this.showMessage( msg, type )'''<br />
<br />
showMessage shows a message in a big rectangular area on the top of the screen of current player.<br />
<br />
* "msg" is the string to display. It should be translated.<br />
* "type" can be set to "info" or "error". If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background.<br />
<br />
Important: the normal way to inform players about the progression of the game is the game log. "showMessage" is intrusive and should not be used often.<br />
<br />
=== Confirmation dialog ===<br />
<br />
'''confirmationDialog( message, yesHandler, noHandler )'''<br />
<br />
<br />
When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.<br />
<br />
CAREFUL: the general guidelines of BGA is to AVOID the use of confirmation dialog. Confirmation dialogs slow down the game and bother players. The players knows that they have to pay attention about each move when they are playing online.<br />
<br />
The situation where you should use a confirmation dialog are the following:<br />
* It must not happen very often during a game.<br />
* It must be linked to an action that can really "kill a game" if the player do not pay attention.<br />
* It must be something that can be done by mistake (ex: a link on the action status bar).<br />
<br />
How to display a confirmation dialog:<br />
<pre><br />
this.confirmationDialog( _('Are you sure you want to bake the pie?'), dojo.hitch( this, function() {<br />
this.bakeThePie();<br />
} ) ); <br />
return; // nothing should be called or done after calling this, all action must be done in the handler <br />
</pre><br />
<br />
=== Multiple choice dialog ===<br />
You can use this dialog to give user a choice with small amount of options:<br />
<pre><br />
var keys = [1,5,10];<br />
this.multipleChoiceDialog(<br />
_('How many bugs to fix?"), keys, <br />
dojo.hitch(this, function(choice) {<br />
var bugchoice = keys[choice];<br />
console.log('dialog callback with '+bugchoice);<br />
this.ajaxcall( '/mygame/mygame/fixBugs.html', { bugs: bugchoice}, this, function( result ) {} ); }));<br />
</pre><br />
<br />
=== Dialogs ===<br />
<br />
As a general rule, you shouldn't use dialogs windows.<br />
<br />
BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.<br />
<br />
Sometimes although, you need to display a dialog window. Here is how you do this:<br />
<br />
<br />
<br />
// Create the new dialog over the play zone. You should store the handler in a member variable to access it later<br />
this.myDlg = new ebg.popindialog();<br />
this.myDlg.create( 'myDialogUniqueId' );<br />
this.myDlg.setTitle( _("my dialog title to translate") );<br />
this.myDlg.setMaxWidth( 500 ); // Optional<br />
<br />
// Create the HTML of my dialog. <br />
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]<br />
var html = this.format_block( 'jstpl_myDialogTemplate', { <br />
arg1: myArg1,<br />
arg2: myArg2,<br />
...<br />
} ); <br />
<br />
// Show the dialog<br />
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog<br />
this.myDlg.show();<br />
<br />
// Now that the dialog has been displayed, you can connect your method to some dialog elements<br />
// Example, if you have an "OK" button in the HTML of your dialog:<br />
dojo.connect( $('my_ok_button'), 'onclick', this, function(evt){<br />
evt.preventDefault();<br />
this.myDlg.destroy();<br />
} );<br />
<br />
If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:<br />
// Removes the default close icon<br />
this.myDlg.hideCloseIcon();<br />
<br />
// Replace the function call when it's clicked<br />
this.myDlg.replaceQuitCallback( function() { ... } );<br />
<br />
=== Scoring dialogs ===<br />
<br />
Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.<br />
<br />
Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.<br />
<br />
Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.<br />
<br />
Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":<br />
<pre><br />
// on PHP side:<br />
$this->notifyAllPlayers( "tableWindow", '', array(<br />
"id" => 'finalScoring',<br />
"title" => clienttranslate("Title of the scoring dialog"),<br />
"table" => $table<br />
) ); <br />
</pre><br />
<br />
The "table" argument is a 2 dimensional PHP array that describe the table you want to display, line by line and column by column.<br />
<br />
Example: display an 3x3 array of strings<br />
<pre><br />
$table = array(<br />
array( "one", "two", "three" ), // This is my first line<br />
array( "four", "five", "six" ), // This is my second line<br />
array( "seven", "height", "nine" ) // This is my third line<br />
);<br />
</pre><br />
<br />
As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:<br />
<pre><br />
$table = array(<br />
array( "one", "two", array( "str" => clienttranslate("a string with an ${argument}"), "args" => array( 'argument' => 'argument_value' ) ) ),<br />
array( "four", "five", "six" ), <br />
array( "seven", "height", "nine" )<br />
);<br />
</pre><br />
<br />
This is especially useful when you want to display player names with colors. Example from "Hearts":<br />
<pre><br />
$firstRow = array( '' );<br />
foreach( $players as $player_id => $player )<br />
{<br />
$firstRow[] = array( 'str' => '${player_name}',<br />
'args' => array( 'player_name' => $player['player_name'] ),<br />
'type' => 'header'<br />
);<br />
}<br />
$table[] = $firstRow;<br />
</pre><br />
<br />
You can also use three extra attributes in the parameter array for the notification:<br />
<br />
<pre><br />
$this->notifyAllPlayers( "tableWindow", '', array(<br />
"id" => 'finalScoring',<br />
"title" => clienttranslate("Title of the scoring dialog"),<br />
"table" => $table,<br />
"header" => array('str' => clienttranslate('Table header with parameter ${number}'),<br />
'args' => array( 'number' => 3 ),<br />
),<br />
"footer" => '<div>Some footer</div>',<br />
"closing" => clienttranslate( "Closing button label" )<br />
) ); <br />
</pre><br />
<br />
*'''header''': the content for this parameter will display before the table (also, the html will be parsed and player names will be colored according to the current game colors). <br />
*'''footer''': the content for this parameter will display after the table (no parsing for coloring the player names)<br />
*'''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).<br />
<br />
=== Scoring animated display ===<br />
<br />
Sometimes (Terra Mystica final scoring for example), you may want to display a score value over an element to make the scoring easier to follow for the players.<br />
You can do it with:<br />
<br />
<pre><br />
this.displayScoring( anchor_id, color, score );<br />
</pre><br />
<br />
<br />
=== Speech bubble ===<br />
<br />
For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.<br />
This is done with:<br />
<br />
<pre><br />
this.showBubble( anchor_id, text, delay, duration, custom_class )<br />
</pre><br />
<br />
delay in milliseconds is optional (default 0)<br />
<br />
duration in milliseconds is optional (default 3000)<br />
<br />
custom_class is optional, if you need to override the default bubble style<br />
<br />
'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.<br />
<br />
== Update players score ==<br />
<br />
Increase a player score (with a positive or negative number):<br />
<br />
<pre><br />
this.scoreCtrl[ player_id ].incValue( score_delta );<br />
</pre><br />
<br />
Set a player score to a specific value:<br />
<br />
<pre><br />
this.scoreCtrl[ player_id ].setValue( new_score );<br />
</pre><br />
<br />
== Players panels ==<br />
<br />
=== Adding stuff to player's panel ===<br />
<br />
At first, create a new "JS template" string in your template (tpl) file:<br />
<br />
(from Gomoku example)<br />
<pre><br />
var jstpl_player_board = '\<div class="cp_board">\<br />
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\<br />
</div>';<br />
</pre><br />
<br />
Then, you add this piece of code in your JS file to add this template to each player panel:<br />
<br />
<pre><br />
// Setting up player boards<br />
for( var player_id in gamedatas.players )<br />
{<br />
var player = gamedatas.players[player_id];<br />
<br />
// Setting up players boards if needed<br />
var player_board_div = $('player_board_'+player_id);<br />
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );<br />
}<br />
</pre><br />
<br />
(Note: the code above is of course from your "setup" function in your Javascript).<br />
<br />
Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".<br />
<br />
=== Player's panel disabling/enabling ===<br />
<br />
'''this.disablePlayerPanel( player_id )'''<br />
<br />
Disable given player panel (the panel background become gray).<br />
<br />
Usually, this is used to signal that this played passes, or will be inactive during a while.<br />
<br />
Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.<br />
<br />
'''this.enablePlayerPanel( player_id )'''<br />
<br />
Enable a player panel that has been disabled before.<br />
<br />
'''this.enableAllPlayerPanels()'''<br />
<br />
Enable all player panels that has been disabled before.<br />
<br />
== Image loading ==<br />
<br />
See also [[Game_art:_img_directory]].<br />
<br />
'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.<br />
<br />
'''dontPreloadImage( image_file_name )'''<br />
<br />
Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.<br />
<br />
Example of use:<br />
<pre><br />
this.dontPreloadImage( 'cards.png' );<br />
</pre><br />
<br />
This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.<br />
<br />
Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.<br />
<pre><br />
// By default, do not preload anything<br />
this.dontPreloadImage( 'cards.png' );<br />
this.dontPreloadImage( 'clan1.png' );<br />
this.dontPreloadImage( 'clan2.png' );<br />
this.dontPreloadImage( 'clan3.png' );<br />
this.dontPreloadImage( 'clan4.png' );<br />
this.dontPreloadImage( 'clan5.png' );<br />
this.dontPreloadImage( 'clan6.png' );<br />
this.dontPreloadImage( 'clan7.png' );<br />
this.dontPreloadImage( 'clan8.png' );<br />
this.dontPreloadImage( 'clan9.png' );<br />
this.dontPreloadImage( 'clan10.png' );<br />
var to_preload = [];<br />
for( i in this.gamedatas.clans )<br />
{<br />
var clan_id = this.gamedatas.clans[i];<br />
to_preload.push( 'clan'+clan_id+'.png' );<br />
}<br />
if( to_preload.length == 5 )<br />
{<br />
this.ensureSpecificGameImageLoading( to_preload );<br />
}<br />
</pre><br />
<br />
'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.<br />
<br />
== Other useful stuff ==<br />
<br />
<br />
'''dojo.hitch'''<br />
<br />
With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.<br />
<br />
Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:<br />
<br />
<pre><br />
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {<br />
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, function( result ) {} );<br />
} ) ); <br />
</pre><br />
<br />
In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.<br />
<br />
<br />
; updateCounters(counters)<br />
: Useful for updating game counters in the player panel (such as resources). <br />
: 'counters' arg is an associative array [counter_name_value => [ 'counter_name' => counter_name_value, 'counter_value' => counter_value_value], ... ]<br />
: All counters must be referenced in this.gamedatas.counters and will be updated.<br />
: DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.<br />
<br />
== BGA GUI components ==<br />
<br />
BGA framework provides some useful ready-to-use components for the game interface:<br />
<br />
[[Studio#BGA_Studio_game_components_reference]]<br />
<br />
Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.<br />
<br />
Example if you are using "ebg.stock":<br />
<pre><br />
define([<br />
"dojo","dojo/_base/declare",<br />
"ebg/core/gamegui",<br />
"ebg/counter",<br />
"ebg/stock" /// <=== we are using ebg.stock module<br />
],<br />
</pre></div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Game_statistics:_stats.json&diff=4016
Game statistics: stats.json
2020-04-15T21:03:36Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
In this file, you are describing game statistics, that will be displayed at the end of the<br />
game.<br />
<br />
After modifying this file, you must use "Reload statistics configuration" <br />
in BGA Studio Control Panel -> Manage Games ("Game Configuration" section):<br />
<br />
http://en.studio.boardgamearena.com/#!studio<br />
<br />
There are 2 types of statistics:<br />
* table statistics, that are not associated to a specific player (i.e.: one value for each game).<br />
* player statistics, that are associated to each players (i.e.: one value for each player in the game).<br />
<br />
Statistics types can be "int" for integer, "float" for floating point values, and "bool" for boolean.<br />
<br />
Once you defined your statistics there, you can start using "initStat", "setStat" and "incStat" methods<br />
in your game logic, using statistics names defined below.<br />
See API http://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Game_statistics.<br />
<br />
!! It is not a good idea to modify this file when a game is running !!<br />
<br />
If your game is already public on BGA, please read the following before any change:<br />
http://en.doc.boardgamearena.com/Post-release_phase#Changes_that_breaks_the_games_in_progress<br />
<br />
Notes:<br />
* Statistic index is the reference used in setStat/incStat/initStat PHP method<br />
* Statistic index must contains alphanumerical characters and no space. Example: 'turn_played'<br />
* Statistics IDs must be >=10<br />
* Two table statistics can't share the same ID, two player statistics can't share the same ID<br />
* A table statistic can have the same ID than a player statistics<br />
* Statistics ID is the reference used by BGA website. If you change the ID, you lost all historical statistic data. Do NOT re-use an ID of a deleted statistic<br />
* Statistic name is the English description of the statistic as shown to players<br />
<br />
<br />
<pre><br />
$stats_type = array(<br />
<br />
// Statistics global to table<br />
"table" => array(<br />
<br />
"turns_number" => array("id"=> 10,<br />
"name" => totranslate("Number of turns"),<br />
"type" => "int" ),<br />
),<br />
<br />
// Statistics existing for each player<br />
"player" => array(<br />
<br />
"turns_number" => array("id"=> 10,<br />
"name" => totranslate("Number of turns"),<br />
"type" => "int" ),<br />
<br />
<br />
"player_teststat1" => array( "id"=> 11,<br />
"name" => totranslate("player test stat 1"), <br />
"type" => "int" ),<br />
<br />
"player_teststat2" => array( "id"=> 12,<br />
"name" => totranslate("player test stat 2"), <br />
"type" => "float" )<br />
<br />
<br />
)<br />
<br />
);<br />
</pre></div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Game_material_description:_material.inc.php&diff=4015
Game material description: material.inc.php
2020-04-15T21:03:26Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This PHP file describes all the material of your game.<br />
<br />
This file is include by the constructor of your main game logic (yourgame.game.php), and then the variables defined here are accessible everywhere in your game logic file.<br />
<br />
Using material.inc.php makes your PHP logic file smaller and clean.<br />
<br />
Example from "Hearts": if you define this in material.inc.php:<br />
<br />
<pre><br />
$this->colors = array(<br />
1 => array( 'name' => clienttranslate('spade'),<br />
'nametr' => self::_('spade') ),<br />
2 => array( 'name' => clienttranslate('heart'),<br />
'nametr' => self::_('heart') ),<br />
3 => array( 'name' => clienttranslate('club'),<br />
'nametr' => self::_('club') ),<br />
4 => array( 'name' => clienttranslate('diamond'),<br />
'nametr' => self::_('diamond') )<br />
);<br />
</pre><br />
<br />
... you can access "$this->colors" everywhere in your PHP game logic file.</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Players_actions:_yourgamename.action.php&diff=4014
Players actions: yourgamename.action.php
2020-04-15T21:03:06Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
== Purpose of this file ==<br />
<br />
With this file, you define all the player entry points (i.e., possible game actions) for your game.<br />
<br />
This file is a sort of "bridge" between the AJAX calls you perform from the Javascript client side, and your main PHP code in "yourgame.game.php".<br />
<br />
The role of the methods defined in this file is to filter the arguments, format them a bit, and then call a corresponding PHP method from your main game logic ("yourgame.game.php" file).<br />
<br />
Methods in this file should be short: no game logic must be introduced here.<br />
<br />
== Example of typical action method ==<br />
<br />
(from Reversi example)<br />
<br />
<pre><br />
public function playDisc()<br />
{<br />
self::setAjaxMode(); <br />
$x = self::getArg( "x", AT_posint, true );<br />
$y = self::getArg( "y", AT_posint, true );<br />
$result = $this->game->playDisc( $x, $y );<br />
self::ajaxResponse( );<br />
}<br />
</pre><br />
<br />
== Methods to use in action methods ==<br />
<br />
'''function setAjaxMode()'''<br />
<br />
Must be used at the beginning of each action method.<br />
<br />
'''function ajaxResponse()'''<br />
<br />
Must be used at the end of each action method.<br />
<br />
'''function getArg( $argName, $argType, $mandatory=false, $default=NULL, $argTypeDetails=array(), $bCanFail=false )'''<br />
<br />
This method must be used to retrieve the arguments sent with your AJAX query.<br />
<br />
You must ''not'' use "_GET", "_POST" or equivalent PHP variables to do this, as it is unsafe.<br />
<br />
This method uses the following arguments:<br />
<br />
* argName: the name of the argument to retrieve.<br />
* argType: the type of the argument. You should use one of the following:<br />
'AT_int' for an integer<br />
'AT_posint' for a positive integer <br />
'AT_float' for a float<br />
'AT_bool' for 1/0/true/false<br />
'AT_enum' for an enumeration (argTypeDetails lists the possible values as an array)<br />
'AT_alphanum' for a string with 0-9a-zA-Z_ and space<br />
'AT_numberlist' for a list of numbers separated with "," or ";" (example: 1,4;2,3;-1,2).<br />
* mandatory: specify "true" if the argument is mandatory.<br />
* default: if mandatory=false, you can specify here a default value in case the argument is not present.<br />
* argTypeDetails: see AT_enum above.<br />
* bCanFail: if true, specify that it may be possible that the argument won't be of the type specified by argType (and then do not log this as a fatal error in the system, and return a standard exception to the player).<br />
<br />
<br />
'''function isArg( $argName )'''<br />
<br />
This is a useful method when you only want to check if an argument is present or not present in your AJAX request (and don't care about the value).<br />
<br />
It returns "true" or "false" according to whether "argName" has been specified as an argument of the AJAX request or not.<br />
<br />
== Useful tip: retrieve a list of numbers ==<br />
<br />
If your Javascript sends a list of integers separated by ";" (example: "1;2;3;4") as an argument, you can transform them into a PHP array with the following:<br />
<br />
<pre><br />
public function playCards()<br />
{<br />
self::setAjaxMode(); <br />
<br />
$card_ids_raw = self::getArg( "card_ids", AT_numberlist, true );<br />
<br />
// Removing last ';' if exists<br />
if( substr( $card_ids_raw, -1 ) == ';' )<br />
$card_ids_raw = substr( $card_ids_raw, 0, -1 );<br />
if( $card_ids_raw == '' )<br />
$card_ids = array();<br />
else<br />
$card_ids = explode( ';', $card_ids_raw );<br />
<br />
$this->game->playCards( $card_ids );<br />
self::ajaxResponse( );<br />
}<br />
</pre></div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Game_database_model:_dbmodel.sql&diff=4013
Game database model: dbmodel.sql
2020-04-15T21:02:54Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
In this file you specify the database schema of your game.<br />
<br />
This file contains SQL queries that will be executed during the creation of your game table.<br />
<br />
'''Note:''' you can't change the database schema during the game.<br />
<br />
== Create your schema ==<br />
<br />
To build this file, we recommend you to build the tables you need with the PhpMyAdmin tool (see BGA user guide), and then to export them and to copy/paste the content inside this file.<br />
<br />
'''Note:''' you must not use for a column the same name as for the table, as the framework replay function relies on regexp substitution to save/restore a previous state in a clone table with another name.<br />
<br />
== Default tables ==<br />
<br />
Important: by default, BGA creates 4 tables for your game: global, stats, gamelog, and player.<br />
<br />
You must not modify the schema of global, stats and gamelog tables (and you must not access them directly with SQL queries in your PHP code).<br />
<br />
You may add columns to "player" table. This is very practical to add simple values associated with players.<br />
<br />
Example:<br />
<pre><br />
ALTER TABLE `player` ADD `player_reserve_size` SMALLINT UNSIGNED NOT NULL DEFAULT '7';<br />
</pre><br />
<br />
For your information, the useful columns of default "player" table are:<br />
* player_no: the index of player in natural playing order.<br />
* player_id<br />
* player_name: (note: you should better access this date with getActivePlayerName() or loadPlayersBasicInfos() methods)<br />
* player_score: the current score of the player (displayed in the player panel). You must update this field to update player's scores.<br />
* player_score_aux: the secondary score, used as a tie breaker. You must update this field according to tie breaking rules of the game (see also: [[Main_game_logic:_yourgamename.game.php#Manage_player_scores_and_Tie_breaker|Manage_player_scores_and_Tie_breaker]])<br />
<br />
== CREATE TABLES ==<br />
you can create tables, using engine InnoDB<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `hands` <br />
(<br />
`id` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT, <br />
`player_id` TINYINT(1) NOT NULL,<br />
`1` BOOL NOT NULL DEFAULT 1, <br />
`2` BOOL NOT NULL DEFAULT 1, <br />
`3` BOOL NOT NULL DEFAULT 1, <br />
`4` BOOL NOT NULL DEFAULT 1, <br />
`5` BOOL NOT NULL DEFAULT 1, <br />
`6` BOOL NOT NULL DEFAULT 1, <br />
`7` BOOL NOT NULL DEFAULT 1, <br />
PRIMARY KEY (`id`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;<br />
</pre><br />
<br />
'''Note''': if you put comments, you cannot do it in the same line as code.<br />
<br />
Example:<br />
<br />
<pre><br />
`3` BOOL NOT NULL DEFAULT 1, -- activated or not<br />
</pre><br />
<br />
will also comment out `3` BOOL, and that code will not be executed.<br />
<br />
== Link ==<br />
You can add your Db inits in function SetupNewGame() from file 'gamename.game.php'<br />
<br />
== Errors Log ==<br />
To trace Database creation check the logs that you can access in /admin/studio.<br />
<br />
== Post-release database modification ==<br />
If you want to modify your database schema after the first release of your game in production, you should consult the [[Post-release phase#Updating the database schema|related section]]</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Template:Studio_Framework_Navigation&diff=4012
Template:Studio Framework Navigation
2020-04-15T21:02:20Z
<p>Tutchek: Margin & background of the navbox</p>
<hr />
<div>__NOTOC__<br />
<br />
<div style="float: right; width: 300px; border: solid #000 1px; padding: 1em; margin-left: 1em; background: #fff;"><br />
<br />
=== Studio Framework Navigation ===<br />
<br />
This part of the documentation focuses on the development framework itself: functions and methods available to build your game.<br />
<br />
[[Studio file reference|File structure of a BGA game]]<br />
<br />
==== Game logic (Server side) ====<br />
<br />
* [[Main game logic: yourgamename.game.php]]<br />
* [[Your game state machine: states.inc.php]]<br />
* [[Game database model: dbmodel.sql]]<br />
* [[Players actions: yourgamename.action.php]]<br />
* [[Game material description: material.inc.php]]<br />
* [[Game statistics: stats.inc.php]]<br />
<br />
==== Game interface (Client side) ====<br />
<br />
* [[Game interface logic: yourgamename.js]]<br />
* [[Game art: img directory]]<br />
* [[Game interface stylesheet: yourgamename.css]]<br />
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl]]<br />
* [[Your game mobile version]]<br />
<br />
==== Other components ====<br />
<br />
* [[Translations]] (how to make your game translatable)<br />
* [[Game options and preferences: gameoptions.inc.php]]<br />
* [[Game meta-information: gameinfos.inc.php]]<br />
* [[Game replay]]<br />
* [[3D]]<br />
* [[Some usual board game elements image ressources]]<br />
<br />
=== BGA Studio game components reference ===<br />
<br />
Game components are useful tools you can use in your game adaptations.<br />
<br />
* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).<br />
* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).<br />
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).<br />
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.<br />
* [[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).<br />
<br />
Undocumented component (if somebody knows please help with docs)<br />
* [[Draggable]]: a JS component to manage drag'n'drop actions.<br />
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.<br />
* [[Wrapper]]: a JS component to wrap a &lt;div&gt; element around its child, even if these elements are absolute positioned.<br />
<br />
=== BGA Studio user guide ===<br />
<br />
This part of the documentation is a user guide for the BGA Studio online development environment.<br />
<br />
* [[BGA game Lifecycle]]<br />
* [[First steps with BGA Studio]]<br />
* [[Tutorial reversi]] <br />
* [[Tutorial gomoku]] <br />
* [[Tutorial hearts]]<br />
* [[Create a game in BGA Studio: Complete Walkthrough]]<br />
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment<br />
* [[Practical debugging]] - Tips focused on debugging<br />
* [[Studio logs]] - Instructions for log access<br />
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks<br />
* [[BGA Studio Guidelines]]<br />
* [[Troubleshooting]] - Most common "I am really stuck" situations<br />
* [[Studio FAQ]]<br />
* [[Pre-release checklist]] - Go throught this list if you think you done development<br />
* [[Post-release phase]]<br />
* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links<br />
<br />
<br />
</div></div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Your_game_state_machine:_states.inc.php&diff=4011
Your game state machine: states.inc.php
2020-04-15T21:01:20Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This file describes the state machine of your game (all the game states properties, and the transitions to get from one state to another).<br />
<br />
Important: to understand the game state machine, it's recommended that you read this presentation first:<br />
<br />
[http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine]<br />
<br />
== Overall structure ==<br />
<br />
The machine states are described by a PHP associative array.<br />
<br />
Example:<br />
<br />
<pre><br />
$machinestates = array(<br />
<br />
// The initial state. Please do not modify.<br />
1 => array(<br />
"name" => "gameSetup",<br />
"description" => clienttranslate("Game setup"),<br />
"type" => "manager",<br />
"action" => "stGameSetup",<br />
"transitions" => array( "" => 2 )<br />
),<br />
<br />
// Note: ID=2 => your first state<br />
<br />
2 => array(<br />
"name" => "playerTurn",<br />
"description" => clienttranslate('${actplayer} must play a card or pass'),<br />
"descriptionmyturn" => clienttranslate('${you} must play a card or pass'),<br />
"type" => "activeplayer",<br />
"possibleactions" => array( "playCard", "pass" ),<br />
"transitions" => array( "playCard" => 2, "pass" => 2 )<br />
),<br />
</pre><br />
<br />
== Syntax ==<br />
<br />
=== id ===<br />
<br />
The keys determine game state IDs (in the example above: 1 and 2).<br />
<br />
IDs must be positive integers.<br />
<br />
ID=1 is reserved for the first game state and should not be used (and you must not modify it).<br />
<br />
ID=99 is reserved for the last game state (end of the game) (and you must not modify it).<br />
<br />
Note: you may use any ID, even an ID greater than 100. But you cannot use 1 or 99.<br />
<br />
Note²: You must not use the same ID twice.<br />
<br />
Note³: When a game is in prod and you change the ID of a state, all active games (including many turn based) will behave unpredictably.<br />
<br />
=== name ===<br />
<br />
('''Mandatory''')<br />
<br />
The name of a game state is used to identify it in your game logic.<br />
<br />
Several game states can share the same name; however, this is not recommended.<br />
<br />
Warning! Do not put spaces in the name. This could cause unexpected problems in some cases.<br />
<br />
PHP example:<br />
<pre><br />
<br />
// Get current game state<br />
$state = $this->gamestate->state();<br />
if( $state['name'] == 'myGameState' )<br />
{<br />
...<br />
}<br />
<br />
</pre><br />
<br />
JS example:<br />
<pre><br />
onEnteringState: function( stateName, args )<br />
{<br />
console.log( 'Entering state: '+stateName );<br />
<br />
switch( stateName )<br />
case 'myGameState':<br />
<br />
// Do some stuff at the beginning at this game state<br />
....<br />
<br />
break;<br />
</pre><br />
<br />
=== type ===<br />
<br />
('''Mandatory''')<br />
<br />
You can use 3 types of game states:<br />
* activeplayer (1 player is active and must play.)<br />
* multipleactiveplayer (1..N players can be active and must play.)<br />
* game (No player is active. This is a transitional state to do something automatic specified by the game rules.)<br />
<br />
'''Note:''' Make sure you don't mistype the value of this attribute. If you do (e.g. 'multiactiveplayer' instead of 'multipleactiveplayer'), things won't work, and you might have a hard time figuring out why.<br />
<br />
=== description ===<br />
<br />
('''Mandatory''')<br />
<br />
The description is the string that is displayed in the main action bar (top of the screen) when the state is active.<br />
<br />
When a string is specified as a description, you must use "clienttranslate" in order for the string to be translated on the client side:<br />
<br />
<pre><br />
"description" => clienttranslate('${actplayer} must play a card or pass'),<br />
</pre><br />
<br />
In the description string, you can use ${actplayer} to refer to the active player.<br />
<br />
You can also use custom arguments in your description. These custom arguments correspond to values returned by your "args" PHP method (see below "args" field).<br />
<br />
Example of custom field:<br />
<pre><br />
<br />
In states.inc.php:<br />
"description" => clienttranslate('${actplayer} must choose ${nbr} identical energies'),<br />
"args" => "argMyArgumentMethod"<br />
<br />
In mygame.game.php:<br />
function argMyArgumentMethod()<br />
{<br />
return array(<br />
'nbr' => 2 // In this case ${nbr} in the description will be replaced by "2"<br />
); <br />
}<br />
</pre><br />
<br />
Note: You may specify an empty string ("") here if it never happens that the game remains in this state (i.e., if this state immediately jumps to another state when activated).<br />
<br />
Note²: Usually, you specify a string for "activeplayer" and "multipleactiveplayer" game states, and you specify an empty string for "game" game states. BUT, if you are using synchronous notifications, the client can remain on a "game" type game state for a few seconds, and in this case it may be useful to display a description in the status bar while in this state.<br />
<br />
=== descriptionmyturn ===<br />
<br />
('''Mandatory''' when the state type is "activeplayer" or "multipleactiveplayer")<br />
<br />
"descriptionmyturn" has exactly the same role and properties as "description", except that this value is displayed to the current active player - or to all active players in case of a multipleactiveplayer game state.<br />
<br />
In general, we have this situation:<br />
<br />
<pre><br />
"description" => clienttranslate('${actplayer} can take some actions'),<br />
"descriptionmyturn" => clienttranslate('${you} can take some actions'),<br />
</pre><br />
<br />
Note: you can use ${you} in descriptionmyturn so the description will display "You" instead of the name of the player.<br />
<br />
=== action ===<br />
<br />
('''Mandatory''' when the state type is "game.")<br />
<br />
"action" specifies a PHP method to call when entering this game state.<br />
<br />
Example:<br />
<pre><br />
In states.inc.php:<br />
28 => array(<br />
"name" => "startPlayerTurn",<br />
"description" => '',<br />
"type" => "game",<br />
"action" => "stStartPlayerTurn",<br />
<br />
In mygame.game.php:<br />
function stStartPlayerTurn()<br />
{ <br />
// ... do something at the beginning of this game state<br />
</pre><br />
<br />
Usually, for a "game" state type, the action method is used to perform automatic functions specified by the rules (for example: check victory conditions, deal cards for a new round, go to the next player, etc.) and then jump to another game state.<br />
<br />
Note: a BGA convention specifies that PHP methods called with "action" are prefixed by "st".<br />
<br />
Note: this field CAN be used for player states to set something up; e.g., for multiplayer states, it can make all players active.<br />
<br />
=== transitions ===<br />
<br />
('''Mandatory''')<br />
<br />
With "transitions" you specify which game state(s) you can jump to from a given game state.<br />
<br />
Example:<br />
<pre><br />
25 => array(<br />
"name" => "myGameState",<br />
"transitions" => array( "nextPlayer" => 27, "endRound" => 39 ),<br />
....<br />
}<br />
</pre><br />
<br />
In the example above, if "myGameState" is the current active game state, I can jump to the game state with ID 27 or the game state with ID 39.<br />
<br />
Example to jump to ID 27:<br />
<pre><br />
In mygame.game.php:<br />
$this->gamestate->nextState( "nextPlayer" );<br />
</pre><br />
<br />
Important: "nextPlayer" is the name of the transition, and NOT the name of the target game state. Multiple transitions can lead to the same game state.<br />
<br />
Note: If there is only 1 transition, you may give it an empty name.<br />
<br />
Example:<br />
<pre><br />
In states.inc.php:<br />
"transitions" => array( "" => 27 ),<br />
<br />
In mygame.game.php:<br />
$this->gamestate->nextState( ); // We don't need to specify a transition as there is only one here<br />
</pre><br />
<br />
=== possibleactions ===<br />
<br />
('''Mandatory''' when the game state is "activeplayer" or "multipleactiveplayer")<br />
<br />
"possibleactions" defines the actions possible by the players in this game state, and ensures they cannot cannot perform actions that are not allowed in this state.<br />
<br />
Example:<br />
<br />
<pre><br />
In states.game.php:<br />
"possibleactions" => array( "playCard", "pass" ),<br />
<br />
In mygame.game.php:<br />
function playCard( ...)<br />
{<br />
self::checkAction( "playCard" ); // Will fail if "playCard" is not specified in "possibleactions" in the current game state.<br />
<br />
....<br />
<br />
In mygame.js:<br />
playCard: function( ... )<br />
{<br />
if( this.checkAction( "playCard" ) ) // Will fail if "playCard" is not specified in "possibleactions" in the current game state.<br />
{ return ; }<br />
<br />
....<br />
<br />
</pre><br />
<br />
=== args ===<br />
<br />
(optional)<br />
<br />
Sometimes it happens that you need some information on the client side (i.e., for your game interface) only for a specific game state.<br />
<br />
Example 1 : in ''Reversi'', the list of possible moves during the playerTurn state.<br />
Example 2 : in ''Caylus'', the number of remaining king's favors to choose in the state where the player is choosing a favor.<br />
Example 3 : in ''Can't Stop'', the list of possible die combinations to be displayed to the active player so that he can choose from among them.<br />
<br />
In such a situation, you can specify a method name as the « args » argument for your game state. This method must retrieve some piece of information about the game (example: for ''Reversi'', the list of possible moves) and return it.<br />
<br />
Thus, this data can be transmitted to the clients and used by the clients to display it. It should always be an associative array.<br />
<br />
Let's see a complete example using args with « Reversi » game :<br />
<br />
In states.inc.php, we specify an « args » argument for gamestate « playerTurn » :<br />
<pre><br />
10 => array(<br />
"name" => "playerTurn",<br />
"description" => clienttranslate('${actplayer} must play a disc'),<br />
"descriptionmyturn" => clienttranslate('${you} must play a disc'),<br />
"type" => "activeplayer",<br />
"args" => "argPlayerTurn", <================================== HERE<br />
"possibleactions" => array( 'playDisc' ),<br />
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )<br />
),<br />
</pre><br />
<br />
It corresponds to a « argPlayerTurn » method in our PHP code (reversi.game.php):<br />
<pre><br />
function argPlayerTurn() {<br />
return array(<br />
'possibleMoves' => self::getPossibleMoves()<br />
);<br />
}<br />
</pre><br />
<br />
Then, when we enter into the « playerTurn » game state on the client side, we can highlight the possible moves on the board using information returned by argPlayerTurn :<br />
<br />
<pre><br />
onEnteringState: function( stateName, args ) {<br />
console.log( 'Entering state: '+stateName );<br />
<br />
switch( stateName ) {<br />
case 'playerTurn':<br />
this.updatePossibleMoves( args.args.possibleMoves );<br />
break;<br />
}<br />
},<br />
</pre><br />
<br />
Note: you can also use values returned by your "args" method to have some custom values in your "description"/"descriptionmyturn" (see above).<br />
<br />
Note: as a BGA convention, PHP methods called with "args" are prefixed by "arg" (example: argPlayerTurn).<br />
<br />
'''Warning''': the "args" method can be called before the "action" method so don't expect data modifications by the "action" method to be available in the "args" method!<br />
<br />
==== Private info in args ====<br />
<br />
By default, all data provided through this method are PUBLIC TO ALL PLAYERS. Please do not send any private data with this method, as a cheater could see it even it is not used explicitly by the game interface logic.<br />
<br />
However, it is possible to specify that some data should be sent to specific players only.<br />
<br />
Example 1: send information to active player(s) only:<br />
<br />
<pre><br />
function argPlayerTurn() {<br />
return array(<br />
'_private' => array( // Using "_private" keyword, all data inside this array will be made private<br />
<br />
'active' => array( // Using "active" keyword inside "_private", you select active player(s)<br />
'somePrivateData' => self::getSomePrivateData() // will be send only to active player(s)<br />
)<br />
),<br />
<br />
'possibleMoves' => self::getPossibleMoves() // will be sent to all players<br />
);<br />
}<br />
</pre><br />
<br />
Inside the js file, these variables will be available through `args._private`. (e.g. `args._private.somePrivateData` -- it is not `args._private.active.somePrivateData` nor is it `args.somePrivateData`)<br />
<br />
Example 2: send information to a specific player (<specific_player_id>) only:<br />
<br />
<pre><br />
function argPlayerTurn() {<br />
return array(<br />
'_private' => array( // Using "_private" keyword, all data inside this array will be made private<br />
<br />
<specific_player_id> => array( // select one specific player by id<br />
'somePrivateData' => self::getSomePrivateData() // will be sent only to <specific_player_id><br />
)<br />
),<br />
<br />
'possibleMoves' => self::getPossibleMoves() // will be sent to all players<br />
);<br />
}<br />
</pre><br />
<br />
IMPORTANT: in certain situations (example: "multipleactiveplayer" game state) these "private data" features can have a significant impact on performance. Please do not use if not needed.<br />
<br />
=== updateGameProgression ===<br />
<br />
(optional)<br />
<br />
If you specify "updateGameProgression => true" in a game state, your "getGameProgression" PHP method will be called at the beginning of this game state - and thus the game progression of the game will be updated.<br />
<br />
''At least one'' of your game states (any one) must specify "updateGameProgression=>true".<br />
<br />
== Implementation Notes ==<br />
<br />
<br />
=== Using Named Constants for States ===<br />
<br />
Using numeric constants is prone to errors. If you want you can declare state constants as PHP named constants. This way you can<br />
use them in the states file and in game.php as well<br />
<br />
EXAMPLE:<br />
<br />
states.inc.php:<br />
<br />
<pre><br />
// define contants for state ids<br />
if (!defined('STATE_END_GAME')) { // ensure this block is only invoked once, since it is included multiple times<br />
define("STATE_PLAYER_TURN", 2);<br />
define("STATE_GAME_TURN", 3);<br />
define("STATE_PLAYER_TURN_CUBES", 4);<br />
define("STATE_END_GAME", 99);<br />
}<br />
<br />
$machinestates = array(<br />
<br />
...<br />
<br />
STATE_PLAYER_TURN => array(<br />
"name" => "playerTurn",<br />
"description" => clienttranslate('${actplayer} must select an Action Space or Pass'),<br />
"descriptionmyturn" => clienttranslate('${you} must select an Action Space or Pass'),<br />
"type" => "activeplayer",<br />
"args" => 'arg_playerTurn',<br />
"possibleactions" => array( "selectWorkerAction", "pass" ),<br />
"transitions" => array( <br />
"loopback" => STATE_PLAYER_TURN,<br />
"playCubes" => STATE_PLAYER_TURN_CUBES,<br />
"pass" => STATE_GAME_TURN )<br />
),<br />
</pre><br />
<br />
=== Example of multipleactiveplayer state ===<br />
<br />
This is an example of a multipleactiveplayer state:<br />
<br />
2 => array (<br />
'name' => 'playerTurnSetup',<br />
'type' => 'multipleactiveplayer',<br />
'description' => clienttranslate('Other players must choose one Objective'),<br />
'descriptionmyturn' => clienttranslate('${you} must choose one Objective card to keep'),<br />
'possibleactions' => array ('playKeep' ),<br />
'transitions' => array ( 'next' => 5, 'loopback' => 2, ),<br />
'action' => 'st_MultiPlayerInit',<br />
'args' => 'arg_playerTurnSetup',<br />
),<br />
<br />
In game.php:<br />
// this will make all players multiactive just before entering the state<br />
function st_MultiPlayerInit() {<br />
$this->gamestate->setAllPlayersMultiactive();<br />
}<br />
<br />
When ending the player action, instead of a state transition, deactivate player.<br />
<br />
function action_playKeep($cardId) {<br />
$this->checkAction('playKeep');<br />
$player_id = $this->getCurrentPlayerId(); // CURRENT!!! not active<br />
... // some logic here<br />
$this->gamestate->setPlayerNonMultiactive($player_id, 'next'); // deactivate player; if none left, transition to 'next' state<br />
}<br />
<br />
<br />
=== Diffrence between Single active and Multi active states ===<br />
In a classic "activePlayer" state:<br />
<br />
* You cannot change the active player DURING the state. This is to ensure that during 1 activePlayer state, only ONE player is active<br />
* As a consequence, you must set the active player BEFORE entering the activePlayer state<br />
* Finally, during onEnteringState, on JS side, the active player is signaled as active and the information is reliable and usable.<br />
<br />
In a "multiplePlayer" state:<br />
<br />
* You can (and must) change the active players DURING the state<br />
* During such a state, players can be activated/desactivated anytime during the state, giving you the maximum of possibilities.<br />
* You shouldn't set actives player before entering the state. But you can set it in "state initialized" php function (see example above st_MultiPlayerInit)<br />
* Finally, during onEnteringState, on JS side, the active players are NOT actives yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/unactive status.</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Main_game_logic:_yourgamename.game.php&diff=4010
Main game logic: yourgamename.game.php
2020-04-15T21:01:06Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This is the main file for your game logic. Here you initialize the game, persist data, implement the rules and notify the client interface of changes.<br />
<br />
== File Structure ==<br />
<br />
The details of how the file is structured are described directly with comments in the code skeleton provided to you.<br />
<br />
Here is the basic structure:<br />
<br />
* EmptyGame (constructor): where you define global variables.<br />
* setupNewGame: initial setup of the game.<br />
* getAllDatas: where you retrieve all game data during a complete reload of the game.<br />
* getGameProgression: where you compute the game progression indicator.<br />
* Utility functions: your utility functions.<br />
* Player actions: the entry points for players actions. <br />
* Game state arguments: methods to return additional data on specific game states ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#args more info here]).<br />
* Game state actions: the logic to run when entering a new game state ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#action more info here]).<br />
* zombieTurn: what to do it's the turn of a zombie player.<br />
<br />
== Accessing player information ==<br />
<br />
'''Important''': In the following methods, be mindful of the difference between the "active" player and the "current" player. The '''active''' player is the player whose turn it is - not necessarily the player who sent a request! The '''current''' player is the player who sent the request and will see the results returned by your methods: not necessarily the player whose turn it is!<br />
<br />
<br />
; getPlayersNumber()<br />
: Returns the number of players playing at the table<br />
: Note: doesn't work in setupNewGame (use count($players) instead).<br />
<br />
; getActivePlayerId()<br />
: Get the "active_player", whatever what is the current state type.<br />
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multiplayer"<br />
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.<br />
<br />
; getActivePlayerName()<br />
: Get the "active_player" name<br />
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.<br />
<br />
; loadPlayersBasicInfos()<br />
: Get an associative array with generic data about players (ie: not game specific data).<br />
: The key of the associative array is the player id. The returned table is cached, so ok to call multiple times without performance concerns.<br />
: The content of each value is:<br />
: * player_name - the name of the player<br />
: * player_color (ex: ff0000) - the color code of the player<br />
: * player_no - the position of the player at the start of the game in natural table order, i.e. 1,2,3<br />
<br />
; getCurrentPlayerId()<br />
: Get the "current_player". The current player is the one from which the action originated (the one who sent the request).<br />
: '''Be careful''': This is not necessarily the active player!<br />
: In general, you shouldn't use this method, unless you are in "multiplayer" state.<br />
: '''Very important''': in your setupNewGame and zombieTurn function, you must never use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message (these actions are triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to these actions).<br />
<br />
; getCurrentPlayerName()<br />
: Get the "current_player" name<br />
: Be careful using this method (see above).<br />
<br />
; getCurrentPlayerColor()<br />
: Get the "current_player" color<br />
: Be careful using this method (see above).<br />
<br />
; isCurrentPlayerZombie()<br />
: Check the "current_player" zombie status. If true, player is zombie, i.e. left or was kicked out of the game.<br />
<br />
== Accessing the database ==<br />
<br />
The main game logic should be the only point from which you should access the game database. You access your database using SQL queries with the methods below.<br />
<br />
'''IMPORTANT'''<br />
<br />
BGA uses [http://dev.mysql.com/doc/refman/5.0/en/sql-syntax-transactions.html database transactions]. This means that your database changes WON'T BE APPLIED to the database until your request ends normally. Using transactions is in fact very useful for you; at any time, if your game logic detects that something is wrong (example: a disallowed move), you just have to throw an exception and all changes to the game situation will be removed.<br />
<br />
; DbQuery( $sql )<br />
: This is the generic method to access the database.<br />
: It can execute any type of SELECT/UPDATE/DELETE/REPLACE query on the database.<br />
: You should use it for UPDATE/DELETE/REPLACE queries. For SELECT queries, the specialized methods below are much better.<br />
<br />
; getUniqueValueFromDB( $sql )<br />
: Returns a unique value from DB or null if no value is found.<br />
: $sql must be a SELECT query.<br />
: Raise an exception if more than 1 row is returned.<br />
<br />
; getCollectionFromDB( $sql, $bSingleValue=false )<br />
: Returns an associative array of rows for a sql SELECT query.<br />
: The key of the resulting associative array is the first field specified in the SELECT query.<br />
: The value of the resulting associative array if an associative array with all the field specified in the SELECT query and associated values.<br />
: First column must be a primary or alternate key.<br />
: The resulting collection can be empty.<br />
: If you specified $bSingleValue=true and if your SQL query request 2 fields A and B, the method returns an associative array "A=>B"<br />
<br />
Example 1:<br />
<pre><br />
self::getCollectionFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );<br />
<br />
Result:<br />
array(<br />
1234 => array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),<br />
1235 => array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )<br />
)<br />
</pre><br />
Example 2:<br />
<pre><br />
self::getCollectionFromDB( "SELECT player_id id, player_name name FROM player", true );<br />
<br />
Result:<br />
array(<br />
1234 => 'myuser0',<br />
1235 => 'myuser1'<br />
)<br />
<br />
</pre><br />
<br />
; getNonEmptyCollectionFromDB( $sql )<br />
: Idem than previous one, but raise an exception if the collection is empty<br />
<br />
; getObjectFromDB( $sql )<br />
: Returns one row for the sql SELECT query as an associative array or null if there is no result<br />
: Raise an exception if the query return more than one row<br />
<br />
Example:<br />
<pre><br />
self::getObjectFromDB( "SELECT player_id id, player_name name, player_score score FROM player WHERE player_id='$player_id'" );<br />
<br />
Result:<br />
array(<br />
'id'=>1234, 'name'=>'myuser0', 'score'=>1 <br />
)<br />
</pre><br />
<br />
; getNonEmptyObjectFromDB( $sql )<br />
: Idem than previous one, but raise an exception if no row is found<br />
<br />
; getObjectListFromDB( $sql, $bUniqueValue=false )<br />
: Return an array of rows for a sql SELECT query.<br />
: the result if the same than "getCollectionFromDB" except that the result is a simple array (and not an associative array).<br />
: The result can be empty.<br />
: If you specified $bUniqueValue=true and if your SQL query request 1 field, the method returns directly an array of values.<br />
<br />
Example 1:<br />
<pre><br />
self::getObjectListFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );<br />
<br />
Result:<br />
array(<br />
array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),<br />
array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )<br />
)<br />
</pre><br />
Example 2:<br />
<pre><br />
self::getObjectListFromDB( "SELECT player_name name FROM player", true );<br />
<br />
Result:<br />
array(<br />
'myuser0',<br />
'myuser1'<br />
)<br />
<br />
</pre><br />
<br />
; getDoubleKeyCollectionFromDB( $sql, $bSingleValue=false )<br />
: Return an associative array of associative array, from a SQL SELECT query.<br />
: First array level correspond to first column specified in SQL query.<br />
: Second array level correspond to second column specified in SQL query.<br />
: If bSingleValue = true, keep only third column on result<br />
<br />
<br />
; DbGetLastId()<br />
: Return the PRIMARY key of the last inserted row (see PHP mysql_insert_id function).<br />
<br />
; DbAffectedRow()<br />
: Return the number of row affected by the last operation<br />
<br />
; escapeStringForDB( $string )<br />
: You must use this function on every string type data in your database that contains unsafe data.<br />
: (unsafe = can be modified by a player).<br />
: This method makes sure that no SQL injection will be done through the string used.<br />
: Note: if you using standard types in ajax actions, like AT_alphanum it is sanitized before arrival,<br />
: this is only needed if you manage to get unchecked string, like in the games where user has to enter text as a response.<br />
<br />
<pre><br />
<br />
<br />
</pre><br />
<br />
Note: see Editing [[Game database model: dbmodel.sql]] to know how to define your database model.<br />
<br />
== Use globals ==<br />
<br />
Sometimes, you want a single global integer value for your game, and you don't want to create a DB table specifically for it.<br />
<br />
You can do this with the BGA framework "global." Your value will be stored in the "global" table in the database, and you can access it with simple methods.<br />
<br />
'''initGameStateLabels'''<br />
<br />
This method should be located at the beginning of ''yourgamename.php.'' This is where you define the globals used in your game logic, by assigning them IDs.<br />
<br />
You can define up to 79 globals, with IDs from 10 to 89 (inclusive). You must '''not''' use globals outside this range, as those values are used by other components of the framework.<br />
<br />
<pre><br />
self::initGameStateLabels( array( <br />
"my_first_global_variable" => 10,<br />
"my_second_global_variable" => 11<br />
) );<br />
</pre><br />
<br />
'''setGameStateInitialValue( $value_label, $value_value )'''<br />
<br />
Initialize your global value. Must be called before any use of your global, so you should call this method from your "setupNewGame" method.<br />
<br />
'''getGameStateValue( $value_label )'''<br />
<br />
Retrieve the current value of a global.<br />
<br />
'''setGameStateValue( $value_label, $value_value )'''<br />
<br />
Set the current value of a global.<br />
<br />
'''incGameStateValue( $value_label, $increment )'''<br />
<br />
Increment the current value of a global. If increment is negative, decrement the value of the global.<br />
<br />
Return the final value of the global.<br />
<br />
== Game states and active players ==<br />
<br />
<br />
=== Activate player handling ===<br />
<br />
; $this->activeNextPlayer()<br />
: Make the next player active in the natural player order.<br />
: Note: you CANT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->activePrevPlayer()<br />
: Make the previous player active (in the natural player order).<br />
: Note: you CANT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->gamestate->changeActivePlayer( $player_id )<br />
: You can call this method to make any player active.<br />
: Note: you CANT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->getActivePlayerId()<br />
: Return the "active_player" id<br />
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multiplayer"<br />
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.<br />
<br />
=== Multiactivate player handling ===<br />
<br />
; $this->gamestate->setAllPlayersMultiactive()<br />
: All playing players are made active. Update notification is sent to all players (triggers onUpdateActionButtons).<br />
: Usually, you use this method at the beginning (ex: "st" action method) of a multiplayer game state when all players have to do some action.<br />
<br />
; $this->gamestate->setAllPlayersNonMultiactive( $next_state )<br />
: All playing players are made inactive. Transition to next state<br />
<br />
; $this->gamestate->setPlayersMultiactive( $players, $next_state, $bExclusive = false )<br />
: Make a specific list of players active during a multiactive gamestate. Update notification is sent to all players who's state changed.<br />
: "players" is the array of player id that should be made active.<br />
: If "exclusive" parameter is not set or false it doesn't deactivate other previously active players. If its set to true, the players who will be multiactive at the end are only these in "$layers" array<br />
<br />
: In case "players" is empty, the method trigger the "next_state" transition to go to the next game state.<br />
: returns true if state transition happened, false otherwise<br />
<br />
; $this->gamestate->setPlayerNonMultiactive( $player_id, $next_state )<br />
: During a multiactive game state, make the specified player inactive.<br />
: Usually, you call this method during a multiactive game state after a player did his action.<br />
: If this player was the last active player, the method trigger the "next_state" transition to go to the next game state.<br />
: returns true if state transition happened, false otherwise<br />
<br />
; $this->gamestate->updateMultiactiveOrNextState( $next_state_if_none )<br />
: Sends update notification about multiplayer changes. All multiactive set* functions above do that, however if you want to change state manually using db queries for complex calculations, you have to call this yourself after. Do not call this if you calling one of the other setters above.<br />
Example: you have player teams and you want to activate all players in one team<br />
<pre><br />
$sql = "UPDATE player SET player_is_multiactive='0'";<br />
self::DbQuery( $sql );<br />
$sql = "UPDATE player SET player_is_multiactive='1' WHERE player_id='$player_id' AND player_team='$team_no'";<br />
self::DbQuery( $sql );<br />
<br />
$this->gamestate->updateMultiactiveOrNextState( 'error' );<br />
</pre><br />
<br />
; $this->gamestate->getActivePlayerList()<br />
: With this method you can retrieve the list of the active player at any time.<br />
: During a "game" type gamestate, it will return a void array.<br />
: During a "activeplayer" type gamestate, it will return an array with one value (the active player id).<br />
: During a "multipleactiveplayer" type gamestate, it will return an array of the active players id.<br />
: Note: you should only use this method in the latter case.<br />
<br />
=== States functions ===<br />
; $this->gamestate->nextState( $transition )<br />
: Change current state to a new state. Important: the $transition parameter is the name of the transition, and NOT the name of the target game state, see [[Your game state machine: states.inc.php]] for more information about states.<br />
<br />
; $this->checkAction( $actionName, $bThrowException=true )<br />
: Check if an action is valid for the current game state, and optionally, throw an exception if it isn't.<br />
: The action is valid if it is listed in the "possibleactions" array for the current game state (see game state description).<br />
: This method MUST be the first one called in ALL your PHP methods that handle player actions, in order to make sure a player doesn't perform an action not allowed by the rules at the point in the game.<br />
: If "bThrowException" is set to "false", the function returns '''false''' in case of failure instead of throwing an exception. This is useful when several actions are possible, in order to test each of them without throwing exceptions.<br />
<br />
; $this->gamestate->checkPossibleAction( $action )<br />
: (rarely used)<br />
: This works exactly like "checkAction" (above), except that it does NOT check if the current player is active.<br />
: This is used specifically in certain game states when you want to authorize additional actions for players that are not active at the moment.<br />
: Example: in ''Libertalia'', you want to authorize players to change their mind about the card played. They are of course not active at the time they change their mind, so you cannot use "checkAction"; use "checkPossibleAction" instead.<br />
<br />
; $this->gamestate->state()<br />
: Get an associative array of current game state attributes, see [[Your game state machine: states.inc.php]] for state attributes.<br />
$state=$this->gamestate->state(); if( $state['name'] == 'myGameState' ) {...}<br />
<br />
== Players turn order ==<br />
<br />
'''getNextPlayerTable()'''<br />
<br />
Return an associative array which associate each player with the next player around the table.<br />
<br />
In addition, key 0 is associated to the first player to play.<br />
<br />
Example: if three player with ID 1, 2 and 3 are around the table, in this order, the method returns:<br />
<pre><br />
array( <br />
1 => 2, <br />
2 => 3, <br />
3 => 1, <br />
0 => 1 <br />
);<br />
</pre><br />
<br />
'''getPrevPlayerTable()'''<br />
<br />
Same as above, but the associative array associate the previous player around the table.<br />
<br />
'''getPlayerAfter( $player_id )'''<br />
<br />
Get player playing after given player in natural playing order.<br />
<br />
'''getPlayerBefore( $player_id )'''<br />
<br />
Get player playing before given player in natural playing order.<br />
<br />
Note: There is no API to modify this order, if you have custom player order you have to maintain it in your database<br />
and have custom function to access it.<br />
<br />
== Notify players ==<br />
<br />
To understand notifications, please read [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] first.<br />
<br />
'''IMPORTANT'''<br />
<br />
Notifications are sent at the very end of the request, when it ends normally. It means that if you throw an exception for any reason (ex: move not allowed), no notifications will be sent to players.<br />
Notifications sent between the game start (setupNewGame) and the end of the "action" method of the first active state will never reach their destination.<br />
<br />
'''notifyAllPlayers( $notification_type, $notification_log, $notification_args )'''<br />
<br />
Send a notification to all players of the game.<br />
<br />
* notification_type:<br />
A string that defines the type of your notification.<br />
<br />
Your game interface Javascript logic will use this to know what is the type of the received notification (and to trigger the corresponding method).<br />
<br />
* notification_log:<br />
A string that defines what is to be displayed in the game log.<br />
<br />
You can use an empty string here (""). In this case, nothing is displayed in the game log.<br />
<br />
If you define a real string here, you should use "clienttranslate" method to make sure it can be translate.<br />
<br />
You can use arguments in your notification_log strings, that refers to values defines in the "notification_args" argument (see below). <br />
Note: Make sure you only use single quotes ('), otherwise PHP will try to interpolate the variable and will ignore the values in the args array.<br />
<br />
<br />
<br />
* notification_args:<br />
The arguments of your notifications, as an associative array.<br />
<br />
This array will be transmitted to the game interface logic, in order the game interface can be updated.<br />
<br />
Complete notifyAllPlayers example (from "Reversi"):<br />
<br />
<pre><br />
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),<br />
array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'returned_nbr' => count( $turnedOverDiscs ),<br />
'x' => $x,<br />
'y' => $y<br />
) );<br />
</pre><br />
<br />
You can see in the example above the use of the "clienttranslate" method, and the use of 2 arguments "player_name" and "returned_nbr" in the notification log.<br />
<br />
'''Important''': NO private data must be sent with this method, as a cheater could see it even it is not used explicitly by the game interface logic. If you want to send private information to a player, please use notifyPlayer below.<br />
<br />
'''Important''': this array is serialized to be sent to the browsers, and will be saved with the notification to be able to replay the game later. If it is too big, it can make notifications slower / less reliable, and replay archives very big (to the point of failing). So as a general rule, you should send only the minimum of information necessary to update the client interface with no overhead in order to keep the notifications as light as possible.<br />
<br />
Note: you CAN use some HTML inside your notification log, however it not recommended for many reasons:<br />
* Its bad architecture, ui elements leak into server now you have to manage ui in many places<br />
* If you decided to change something in ui in future version, old games reply and tutorials may not work, since they use stored notifications<br />
* When you read log preview for old games its unreadable (this is log before you enter the game reply, useful for troubleshooting or game analysis)<br />
* Its more data to transfer and store in db<br />
* Its nightmare for translators, at least don't put HTML tags inside the "clienttranslate" method. You can use a notification argument instead, and provide your HTML through this argument.<br />
<br />
If you still want to have pretty pictures in the log check this [[BGA_Studio_Cookbook#Inject_images_and_styled_html_in_the_log]].<br />
<br />
If your notification contains some phrases that build programmatically you may need to use recursive notifications. In this case the argument can be not only the string but<br />
an array itself, which contains 'log' and 'args', i.e.<br />
<br />
$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name_rec}'),<br />
['token_name_rec'=>['log'=>'${token_name} #${token_number}',<br />
'args'=> ['token_name'=>clienttranslate('Boo'), 'token_number'=>$number, 'i18n'=>['token_name'] ]<br />
]<br />
]);<br />
<br />
<br />
<br />
'''notifyPlayer( $player_id, $notification_type, $notification_log, $notification_args )'''<br />
<br />
Same as above, except that the notification is sent to one player only.<br />
<br />
This method must be used each time some private information must be transmitted to a player.<br />
<br />
Important: the variable for player name must be ${player_name} in order to be highlighted with the player color in the game log<br />
<br />
== About random and randomness ==<br />
<br />
A large number of board games rely on random, most often based on dice, cards shuffling, picking some item in a bag, and so on. This is very important to ensure a high level of randomness for each of these situations.<br />
<br />
Here's are a list of techniques you should use in these situations, from the best to the worst.<br />
<br />
=== Dices and bga_rand ===<br />
<br />
'''bga_rand( min, max )''' <br />
This is a BGA framework function that provides you a random number between "min" and "max" (included), using the best available random method available on the system.<br />
<br />
This is the preferred function you should use, because we are updating it when a better method is introduced.<br />
<br />
At now, bga_rand is based on the PHP function "random_int", which ensure a cryptographic level of randomness.<br />
<br />
In particular, it is '''mandatory''' to use it for all '''dice throw''' (ie: games using other methods for dice throwing will be rejected by BGA during review).<br />
<br />
Note: rand() and mt_rand() are deprecated on BGA and should not be used anymore, as their randomness is not as good as "bga_rand".<br />
<br />
=== shuffle and cards shuffling ===<br />
<br />
To shuffle items, like a pile of cards, the best way is to use the BGA PHP [[Deck]] component and to use "shuffle" method. This ensure you that the best available shuffling method is used, and that if in the future we improve it your game will be up to date.<br />
<br />
At now, the Deck component shuffle method is based on PHP "shuffle" method, which has a quite good randomness (even it is not as good as bga_rand). In consequence, we accept other shuffling methods during reviews, as long as their are based on PHP "shuffle" function (or similar, like "array_rand").<br />
<br />
=== Other methods ===<br />
<br />
Mysql "RAND()" function has not enough randomness to be a valid method to get a random element on BGA. This function has been used in some existing games and has given acceptable results, but now it should be avoided and you should use other methods instead.<br />
<br />
== Game statistics ==<br />
<br />
There are 2 types of statistics:<br />
* a "player" statistic is a statistic associated to a player<br />
* a "table" statistics is a statistic not associated to a player (global statistic for this game).<br />
<br />
See [[Game statistics: stats.inc.php]] to see how you defines statistics for your game.<br />
<br />
<br />
'''initStat( $table_or_player, $name, $value, $player_id = null )'''<br />
<br />
Create a statistic entry with a default value.<br />
This method must be called for each statistics of your game, in your setupNewGame method.<br />
<br />
'$table_or_player' must be set to "table" if this is a table statistics, or "player" if this is a player statistics.<br />
<br />
'$name' is the name of your statistics, as it has been defined in your stats.inc.php file.<br />
<br />
'$value' is the initial value of the statistics. If this is a player statistics and if the player is not specified by "$player_id" argument, the value is set for ALL players.<br />
<br />
<br />
'''setStat( $value, $name, $player_id = null )'''<br />
<br />
Set a statistic $name to $value.<br />
<br />
If "$player_id" is not specified, setStat consider it is a TABLE statistic.<br />
<br />
If "$player_id" is specified, setStat consider it is a PLAYER statistic.<br />
<br />
<br />
'''incStat( $delta, $name, $player_id = null )'''<br />
<br />
Increment (or decrement) specified statistic value by $delta value. Same behavior as setStat function.<br />
<br />
<br />
'''getStat( $name, $player_id = null )'''<br />
<br />
Return the value of statistic specified by $name. Useful when creating derivative statistics such as average.<br />
<br />
== Translations ==<br />
<br />
See [[Translations]]<br />
<br />
== Manage player scores and Tie breaker ==<br />
<br />
=== Normal scoring ===<br />
<br />
At the end of the game, players automatically get a rank depending on their score: the player with the biggest score is #1, the player with the second biggest score is #2, and so on...<br />
<br />
During the game, you update player's score directly by updating "player_score" field of "player" table in database.<br />
<br />
Examples:<br />
<pre><br />
<br />
// +2 points to active player<br />
self::DbQuery( "UPDATE player SET player_score=player_score+2 WHERE player_id='".self::getActivePlayerId()."'" );<br />
<br />
// Set score of active player to 5<br />
self::DbQuery( "UPDATE player SET player_score=5 WHERE player_id='".self::getActivePlayerId()."'" );<br />
<br />
</pre><br />
<br />
Note: don't forget to notify the client side in order the score control can be updated accordingly.<br />
<br />
=== Tie breaker ===<br />
<br />
Tie breaker is used when two players get the same score at the end of a game.<br />
<br />
Tie breaker is using "player_score_aux" field of "player" table. It is updated exactly like the "player_score" field.<br />
<br />
Tie breaker score is displayed only for players who are tied at the end of the game. Most of the time, it is not supposed to be displayed explicitly during the game.<br />
<br />
When you are using "player_score_aux" functionality, you must describe the formula to use in your gameinfos.inc.php file like this:<br />
<br />
<pre><br />
'tie_breaker_description' => totranslate("Describe here your tie breaker formula"),<br />
</pre><br />
<br />
This description will be used as a tooltip to explain to players how this auxiliary score has been calculated.<br />
<br />
=== Co-operative game ===<br />
<br />
To make everyone lose in full-coop game:<br />
<br />
Add the following in gameinfos.inc.php :<br />
'is_coop' => 1, // full cooperative<br />
<br />
And score zero to everyone.<br />
<br />
=== Semi-coop ===<br />
<br />
If the game is not full-coop, then everyone lose = everyone is tie. I.e. set score to 0 to everybody.<br />
<br />
=== Only "winners" and "losers ===<br />
<br />
For some games, there is only a group (or a single) "winner", and everyone else is a "loser", with no "end of game rank" (1st, 2nd, 3rd...).<br />
<br />
Examples:<br />
* Coup<br />
* Not Alone<br />
* Werewolves<br />
* Quantum<br />
<br />
In this case:<br />
* Set the scores so that the winner has the best score, and the other players have the same (lower) score.<br />
* Add the following lines to gameinfos.php:<br />
<br />
<pre><br />
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true <br />
// The game end result will display "Winner" for the 1st player and "Loser" for all other players<br />
'losers_not_ranked' => true,<br />
</pre><br />
<br />
Werewolves and Coup are implemented like this, as you can see here:<br />
* https://boardgamearena.com/#!gamepanel?game=werewolves&section=lastresults<br />
* https://boardgamearena.com/#!gamepanel?game=coupcitystate&section=lastresults<br />
<br />
Adding this has the following effects:<br />
* On game results for this game, "Winner" or "Loser" is going to appear instead of the usual "1st, 2nd, 3rd, ...".<br />
* When a game is over, the result of the game will be "End of game: Victory" or "End of game: Defeat" depending on the result of the CURRENT player (instead of the usual "Victory of XXX").<br />
* When calculating ELO points, if there is at least one "Loser", no "victorious" player can lose ELO points, and no "losing" player can win ELO point. Usually it may happened because being tie with many players with a low rank is considered as a tie and may cost you points. If losers_not_ranked is set, we prevent this behavior and make sure you only gain/loss ELO when you get the corresponding results.<br />
<br />
Important: this SHOULD NOT be used for cooperative games (see is_coop parameter), or for 2 players games (it makes no sense in this case).<br />
<br />
=== Solo ===<br />
<br />
If game supports solo variant, a negative score means defeat, a positive score means victory.<br />
<br />
=== Player elimination ===<br />
<br />
In some games, this is useful to eliminate a player from the game in order he/she can start another game without waiting for the current game end.<br />
<br />
This case should be rare. Please don't use player elimination feature if some player just has to wait the last 10% of the game for game end. This feature should be used only in games where players are eliminated all along the game (typical examples: "Perudo" or "The Werewolves of Miller's Hollow").<br />
<br />
Usage:<br />
<br />
* Player to eliminate should NOT be active anymore (preferably use the feature in a "game" type game state).<br />
* In your PHP code:<br />
self::eliminatePlayer( <player_to_eliminate_id> );<br />
* the player is informed in a dialog box that he no longer have to played and can start another game if he/she wants too (whith buttons "stay at this table" "quit table and back to main site"). In any case, the player is free to start & join another table from now.<br />
* When your game is over, all players who have been eliminated before receive a "notification" (the small "!" icon on the top right of the BGA interface) that indicate them that "the game has ended" and invite them to review the game results.<br />
<br />
=== Scoring Helper functions ===<br />
<br />
// get score<br />
function dbGetScore($player_id) {<br />
return $this->getUniqueValueFromDB("SELECT player_score FROM player WHERE player_id='$player_id'");<br />
}<br />
<br />
// set score<br />
function dbSetScore($player_id, $count) {<br />
$this->DbQuery("UPDATE player SET player_score='$count' WHERE player_id='$player_id'");<br />
}<br />
<br />
// set aux score (tie breaker)<br />
function dbSetAuxScore($player_id, $score) {<br />
$this->DbQuery("UPDATE player SET player_score_aux=$score WHERE player_id='$player_id'");<br />
}<br />
<br />
// increment score (can be negative too)<br />
function dbIncScore($player_id, $inc) {<br />
$count = $this->dbGetScore($player_id);<br />
if ($inc != 0) {<br />
$count += $inc;<br />
$this->dbSetScore($player_id, $count);<br />
}<br />
return $count;<br />
}<br />
<br />
== Reflexion time ==<br />
<br />
; function giveExtraTime( $player_id, $specific_time=null )<br />
: Give standard extra time to this player.<br />
: Standard extra time depends on the speed of the game (small with "slow" game option, bigger with other options).<br />
: You can also specify an exact time to add, in seconds, with the "specified_time" argument (rarely used).<br />
<br />
<br />
== Undo moves ==<br />
<br />
Please read our [[BGA Undo policy]] before.<br />
<br />
<br />
'''Important''': Before using these methods, you must also add the following to your "gameinfos.inc.php" file, otherwise these methods are ineffective:<br />
'db_undo_support' => true<br />
<br />
<br />
; function undoSavepoint( )<br />
: Save the whole game situation inside an "Undo save point".<br />
: There is only ONE undo save point available (see BGA Undo policy).<br />
<br />
<br />
; function undoRestorePoint()<br />
: Restore the situation previously saved as an "Undo save point".<br />
: You must make sure that the active player is the same after and before the undoRestorePoint (ie: this is your responsibility to ensure that the player that is active when this method is called is exactly the same than the player that was active when the undoSavePoint method has been called).<br />
<br />
== Managing errors and exceptions ==<br />
<br />
Note: when you throw an exception, all database changes and all notifications are cancelled immediately. This way, the game situation that existed before the request is completely restored.<br />
<br />
; throw new BgaUserException ( $error_message)<br />
: Base class to notify a user error<br />
: You must throw this exception when a player wants to do something that he is not allowed to do.<br />
: The error message will be shown to the player as a "red message", so it must be translated.<br />
: Throwing such an exception is NOT considered a bug, so it is not traced in BGA error logs.<br />
<br />
Example from Gomoku:<br />
<pre><br />
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );<br />
</pre><br />
<br />
<br />
; throw new BgaVisibleSystemException ( $error_message)<br />
: You must throw this exception when you detect something that is not supposed to happened in your code.<br />
: The error message is shown to the user as an "Unexpected error", in order that he can report it in the forum.<br />
: The error message is logged in BGA error logs. If it happens regularly, we will report it to you.<br />
<br />
; throw new BgaSystemException ( $error_message)<br />
: Base class to notify a system exception. The message will be hidden from the user, but show in the logs. Use this if the message contains technical information.<br />
: You shouldn't use this type of exception except if you think the information shown could be critical. Indeed: a generic error message will be shown to the user, so it's going to be difficult for you to see what happened.<br />
<br />
== Zombie mode ==<br />
<br />
When a player leaves a game for any reason (expelled, quit), he becomes a "zombie player". In this case, the results of the game won't count for statistics, but this is cool if the other players can finish the game anyway. That's why zombie mode exists: allow the other player to finish the game, even if the situation is not ideal.<br />
<br />
While developing your zombie mode, keep in mind that:<br />
* Do not refer to the rules, because this situation is not planned by the rules.<br />
* Try to figure that you are playing with your friends and one of them has to leave: how can we finish the game without killing the spirit of the game?<br />
* The idea is NOT to develop an artificial intelligence for the game.<br />
<br />
Most of the time, the best thing to do when it is zombie player turn is to jump immediately to a state where he is not active anymore. For example, if he is in a game state where he has a choice between playing A and playing B, the best thing to do is NOT to choose A or B, but to pass. So, even if there's no "pass" action in the rules, add a "zombiepass" transitition in your game state and use it.<br />
<br />
Each time a zombie player must play, your "zombieTurn" method is called.<br />
<br />
Parameters:<br />
* $state: the name of the current game state.<br />
* $active_player: the id of the active player.<br />
<br />
Most of the time, your zombieTurn method looks like this:<br />
<br />
<pre><br />
function zombieTurn( $state, $active_player )<br />
{<br />
$statename = $state['name'];<br />
<br />
if( $statename == 'myFirstGameState'<br />
|| $statename == 'my2ndGameState'<br />
|| $statename == 'my3rdGameState'<br />
....<br />
)<br />
{<br />
$this->gamestate->nextState( "zombiePass" );<br />
}<br />
else<br />
throw new BgaVisibleSystemException( "Zombie mode not supported at this game state: ".$statename );<br />
}<br />
</pre><br />
<br />
Note that in the example above, all corresponding game state should implement "zombiePass" as a transition.<br />
<br />
'''Very important''': your zombie code will be called when the player leaves the game. This action is triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to this action. In your zombieTurn function, you must '''never''' use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message.<br />
<br />
== Player color preferences ==<br />
<br />
<br />
BGA players (Club members) may now choose their preferred color for playing. For example, if they are used to play green for every board game, they can select "green" in their BGA preferences page.<br />
<br />
Making your game compatible with colors preferences is very easy and requires only 1 line of PHP and 1 configuration change :<br />
<br />
On your gameinfos.inc.php file, add the following lines :<br />
<br />
// Favorite colors support : if set to "true", support attribution of favorite colors based on player's preferences (see reattributeColorsBasedOnPreferences PHP method)<br />
'favorite_colors_support' => true,<br />
<br />
Then, on your main <your_game>.game.php file, find the "reloadPlayersBasicInfos" call in your "setupNewGame" method and replace :<br />
<br />
$sql .= implode( $values, ',' );<br />
self::DbQuery( $sql );<br />
self::reloadPlayersBasicInfos();<br />
<br />
By :<br />
<br />
$sql .= implode( $values, ',' );<br />
self::DbQuery( $sql );<br />
self::reattributeColorsBasedOnPreferences( $players, array( /* LIST HERE THE AVAILABLE COLORS OF YOUR GAME INSTEAD OF THESE ONES */"ff0000", "008000", "0000ff", "ffa500", "773300" ) );<br />
self::reloadPlayersBasicInfos();<br />
<br />
<br />
The "reattributeColorsBasedOnPreferences" method reattributes all colors, taking into account players color preferences and available colors.<br />
<br />
Note that you must update the colors to indicate the colors available for your game.<br />
<br />
2 important remarks :<br />
* for some games (ex : Chess), the color has an influence on a mechanism of the game, most of the time by giving a special advantage to a player (ex : Starting the game). Color preference mechanism must NOT be used in such a case.<br />
* your logic should NEVER consider that the first player has the color X, that the second player has the color Y, and so on. If this is the case, your game will NOT be compatible with reattributeColorsBasedOnPreferences as this method attribute colors to players based on their preferences and not based as their order at the table.<br />
<br />
Colours currently listed as a choice in preferences:<br />
<br />
* #ff0000 Red<br />
* #008000 Green<br />
* #0000ff Blue<br />
* #ffa500 Yellow<br />
* #000000 Black<br />
* #ffffff White<br />
* #e94190 Pink<br />
* #982fff Purple<br />
* #72c3b1 Cyan<br />
* #f07f16 Orange<br />
* #bdd002 Khaki green<br />
* #7b7b7b Gray<br />
<br />
== Debugging and Tracing ==<br />
<br />
To debug php code you can use some tracing functions available from the parent class such as debug, trace, error, warn, dump.<br />
<br />
self::debug("Ahh!");<br />
self::dump('my_var',$my_var);<br />
<br />
See [[Practical_debugging]] section for complete information about debugging interfaces and where to find logs.</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Studio_file_reference&diff=4009
Studio file reference
2020-04-15T21:00:48Z
<p>Tutchek: Added navigation</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This is a quick reference for the files used to implement a game. For more information, follow the wiki links.<br />
<br />
=== img/ ===<br />
<br />
This directory contains the images for your game (the game art). <br />
<br />
See [[Game art: img directory]]<br />
<br />
=== gameinfos.inc.php ===<br />
<br />
In this file you describe the meta-information for your game: game name, publisher name, number of player, game categories, etc...<br />
<br />
See [[Game_meta-information:_gameinfos.inc.php]].<br />
<br />
=== dbmodel.sql ===<br />
<br />
File for creating specific database tables that you will need to persist data during the game (for example a table for cards).<br />
<br />
See [[Game database model: dbmodel.sql]]<br />
<br />
=== gameoptions.inc.php ===<br />
<br />
File for describing your game options (or game variants).<br />
<br />
See [[Game options and preferences: gameoptions.inc.php]].<br />
<br />
=== <gamename>.action.php ===<br />
<br />
File used to describe methods that can be called from the client interface through javascript, get parameters and call the appropriate game functions.<br />
<br />
See [[Players actions: yourgamename.action.php]].<br />
<br />
=== <gamename>.css ===<br />
<br />
CSS styles specific to your game.<br />
<br />
See [[Game interface stylesheet: yourgamename.css]].<br />
<br />
=== <gamename>.game.php ===<br />
<br />
This is the main file for your game logic. Here you initialize the game, persist data, implement the rules and notify changes to the client interface. <br />
<br />
See [[Main game logic: yourgamename.game.php]].<br />
<br />
=== <gamename>.js ===<br />
<br />
This is the main file for your game interface. Here you will define:<br />
* which actions on the page will generate calls to the server<br />
* what happens when you get a notification for change from the server and how it will show in the browser.<br />
<br />
See [[Game interface logic: yourgamename.js]].<br />
<br />
=== <gamename>.view.php and <gamename>_<gamename>.tpl ===<br />
<br />
Files used to set up the page layout ('view') for the game.<br />
<br />
See [[Game layout: view and template: yourgamename.view.php and yourgamename yourgamename.tpl]].<br />
<br />
=== material.inc.php ===<br />
<br />
File used to describe all the game material (cards with their description, dices, tokens...). You can also use it to define game constants.<br />
<br />
See [[Game material description: material.inc.php]].<br />
<br />
=== states.inc.php ===<br />
<br />
This file describes the game states machine of your game (all the game states properties, and the transitions to get from one state to another).<br />
<br />
See [[Your game state machine: states.inc.php]].<br />
<br />
=== stats.inc.php ===<br />
<br />
File used to list statistics that you want to update during the game to be presented to players at the end of the game.<br />
<br />
See [[Game statistics: stats.inc.php]].<br />
<br />
=== version.php ===<br />
<br />
Don't edit this file. It is used internally by the build system.<br />
<br />
<br />
=== modules/ ===<br />
<br />
Modules directory can contain additional php files which can be included in main game.php via include or require. This directory is checked in version control.<br />
<br />
=== misc/ ===<br />
<br />
Directory containing files you would like to keep with project but not needed on production server. This directory is checked in version control. Total limit is 1 Mb for this directory.<br />
<br />
=== <other files> ===<br />
<br />
You can use other files but they won't be checked in source control and published in production. That includes any additional .js or .php files. If you need them use modules/ directory.</div>
Tutchek
https://en.doc.boardgamearena.com/index.php?title=Template:Studio_Framework_Navigation&diff=4008
Template:Studio Framework Navigation
2020-04-15T21:00:06Z
<p>Tutchek: Useful navigation box</p>
<hr />
<div>__NOTOC__<br />
<br />
<div style="float: right; width: 300px; border: solid #000 1px; padding: 1em;"><br />
<br />
=== Studio Framework Navigation ===<br />
<br />
This part of the documentation focuses on the development framework itself: functions and methods available to build your game.<br />
<br />
[[Studio file reference|File structure of a BGA game]]<br />
<br />
==== Game logic (Server side) ====<br />
<br />
* [[Main game logic: yourgamename.game.php]]<br />
* [[Your game state machine: states.inc.php]]<br />
* [[Game database model: dbmodel.sql]]<br />
* [[Players actions: yourgamename.action.php]]<br />
* [[Game material description: material.inc.php]]<br />
* [[Game statistics: stats.inc.php]]<br />
<br />
==== Game interface (Client side) ====<br />
<br />
* [[Game interface logic: yourgamename.js]]<br />
* [[Game art: img directory]]<br />
* [[Game interface stylesheet: yourgamename.css]]<br />
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl]]<br />
* [[Your game mobile version]]<br />
<br />
==== Other components ====<br />
<br />
* [[Translations]] (how to make your game translatable)<br />
* [[Game options and preferences: gameoptions.inc.php]]<br />
* [[Game meta-information: gameinfos.inc.php]]<br />
* [[Game replay]]<br />
* [[3D]]<br />
* [[Some usual board game elements image ressources]]<br />
<br />
=== BGA Studio game components reference ===<br />
<br />
Game components are useful tools you can use in your game adaptations.<br />
<br />
* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).<br />
* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).<br />
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).<br />
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.<br />
* [[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).<br />
<br />
Undocumented component (if somebody knows please help with docs)<br />
* [[Draggable]]: a JS component to manage drag'n'drop actions.<br />
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.<br />
* [[Wrapper]]: a JS component to wrap a &lt;div&gt; element around its child, even if these elements are absolute positioned.<br />
<br />
=== BGA Studio user guide ===<br />
<br />
This part of the documentation is a user guide for the BGA Studio online development environment.<br />
<br />
* [[BGA game Lifecycle]]<br />
* [[First steps with BGA Studio]]<br />
* [[Tutorial reversi]] <br />
* [[Tutorial gomoku]] <br />
* [[Tutorial hearts]]<br />
* [[Create a game in BGA Studio: Complete Walkthrough]]<br />
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment<br />
* [[Practical debugging]] - Tips focused on debugging<br />
* [[Studio logs]] - Instructions for log access<br />
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks<br />
* [[BGA Studio Guidelines]]<br />
* [[Troubleshooting]] - Most common "I am really stuck" situations<br />
* [[Studio FAQ]]<br />
* [[Pre-release checklist]] - Go throught this list if you think you done development<br />
* [[Post-release phase]]<br />
* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links<br />
<br />
<br />
</div></div>
Tutchek