https://en.doc.boardgamearena.com/api.php?action=feedcontributions&user=BrianLovesMarvel&feedformat=atom
Board Game Arena - User contributions [en]
2024-03-29T04:40:16Z
User contributions
MediaWiki 1.39.0
https://en.doc.boardgamearena.com/index.php?title=Practical_debugging&diff=15601
Practical debugging
2022-12-23T17:50:53Z
<p>BrianLovesMarvel: /* Debugging setupNewGame */ Added hint about errors you may see from setupNewGame, and reinforced suggestion for initTables().</p>
<hr />
<div>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 />
__TOC__<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 />
=== Save & Restore ===<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 />
=== Refresh ===<br />
<br />
If something does not seems to work properly even you "fixed it", it may be refresh issue. Not all files born equal. Some require a lot more steps to get into the game.<br />
<br />
See https://en.doc.boardgamearena.com/Studio_file_reference for information on how to "refresh" each files.<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 />
However errors and logs generated by setupNewGame not always (almost never) there, so see Debug setupNewGame session.<br />
More cases of why game can't start are described on the [[Troubleshooting]] page.<br />
<br />
== Debugging an issue with the waiting screen ==<br />
<br />
BGA displays a waiting screen during a few seconds inviting free players to become premium when they are playing a lot.<br />
<br />
This waiting screen should not in principle impact your game, but in some cases it might.<br />
<br />
To test the waiting screen on the studio, you can set the desired duration by adding the get parameter studioLockingDuration with the number of seconds for the lock screen to be displayed. For example to have a 10 seconds waiting screen when you launch a game on the studio:<br />
https://studio.boardgamearena.com?studioLockingDuration=10<br />
<br />
Then you can just set it back to zero in the same way with https://studio.boardgamearena.com?studioLockingDuration=0 (or restart your browser to clear the session value).<br />
<br />
== Debugging my PHP game logic (or my view) ==<br />
<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 />
'''WARNING''': tracing does not work in constructor, setupNewGame and game states immediately following starting state (not sure why). Use other method described below in this case (seciton "Debugging setupNewGame").<br />
<br />
=== Call php functions from chat ===<br />
<br />
This is best feature ever, you can call individual function in your game.php from chat window, see details<br />
at https://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#Run_PHP_functions_from_the_chat<br />
<br />
<br />
=== Dump data and die ===<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 />
Now since this text will be returned back to client it will usually choke on this, but you can actually see it better if you wrap it some html, i.e.<br />
<pre><br />
echo "<pre>";<br />
var_dump( $my_variable );<br />
echo "&lt;/pre>";<br />
</pre><br />
<br />
=== Debug at home ===<br />
<br />
If you develop some complex logic it is better sometimes to stub all external calls and debug it locally using command line or IDE debugger for php.<br />
You can get some basic stubs here https://github.com/elaskavaia/bga-sharedcode/raw/master/misc/module/table/table.game.php<br />
<br />
To run php locally you need to wrap it into test or something, see example https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Creating_a_test_class_to_run_PHP_locally<br />
<br />
=== Debugging setupNewGame ===<br />
<br />
This is separate section because tracing method do not work in this function.<br />
Recommended way to debug it <br />
* leave setupNewGame exactly as in template (inlcuding setting up player table and activating first player), and add a single call at the end<br />
$this->initTables();<br />
This will be your own function which you will be changing, so you don't touch setupNewGame anymore.<br />
<br />
Remember that this function cannot send notification or query active or current player. If you need to get player data use $this->loadPlayersBasicInfos().<br />
<br />
function initTables() {<br />
try {<br />
$players = $this->loadPlayersBasicInfos();<br />
// ... code the function<br />
} catch ( Exception $e ) {<br />
// logging does not actually work in game init :(<br />
// but if you calling from php chat it will work<br />
$this->error("Fatal error while creating game");<br />
$this->dump('err', $e);<br />
}<br />
}<br />
<br />
Create a code for this function, and if it does not work run it from the chat window of the just created game (i.e. 'initTables()' without quotes). That way you can see debug output!<br />
The only trick is you have to clear all your tables in the begging so when you run it multiple times your db does not puke.<br />
If your game does not start at all - do not even call it from setupNewGame, comment it out and only call from chat window until it works.<br />
Don't forget you can also look at tables in db using php-admin tool (link at the bottom of the game table in studio).<br />
<br />
The same problem exists if you game state immediately follow starting state (problem of debugging it without the logs), in this case create a dummy player state in which player just press OK that will transition<br />
to you game state, after you done debugging it remove the state and shortcut the transition to your game state.<br />
<br />
Instead of calling initTables directly you can call helper function instead from chat window which will also reset the client, i.e.<br />
<pre><br />
function debug_initTables() {<br />
$this->deleteAllTables(); // this suppose to delete/reset all data - you have to implement this function<br />
$this->initTables();<br />
$newGameDatas = $this->getAllTableDatas(); // this is framework function<br />
$this->notifyPlayer($this->getActivePlayerId(), 'resetInterfaceWithAllDatas', '', $newGameDatas); // this is notification to reset all data <br />
$this->notifyAllPlayers("message",'setup called',[]);<br />
}<br />
</pre>HINT: This is a great suggestion. If you make any simple mistake in any code in setupNewGame, you may see "BGA Service Exception" instead of anything very useful, since setupNewGame failed. For example, even sending a bad SQL string to self:dbQuery() will generate this error. Very hard to debug! <br />
<br />
=== Debugging endOfGame ===<br />
<br />
Debugging end of game is hard if game ends! Make sure it does not end, then you can restore to previous state using saved states.<br />
In php file:<br />
<br />
$this->processEndOfGame();<br />
if ($this->getBgaEnvironment() == 'studio')<br />
$this->gamestate->nextState('debuglast'); // debug end<br />
else<br />
$this->gamestate->nextState('last'); // real end<br />
<br />
You have to end a special user state in states file for debug in states file<br />
<br />
<pre><br />
STATE_GAME_TURN_NEXT_PLAYER => array( // normal state<br />
"name" => "gameTurnNextPlayer",<br />
"description" => '',<br />
"type" => "game",<br />
"action" => "st_gameTurnNextPlayer",<br />
"updateGameProgression" => true,<br />
"transitions" => array(<br />
"next" => STATE_PLAYER_TURN_ACTION,<br />
"loopback" => STATE_GAME_TURN_NEXT_PLAYER,<br />
"last" => STATE_END_GAME,<br />
"debuglast" => STATE_PLAYER_GAME_END // for debugging on studio<br />
), <br />
),<br />
// for debugging end of game<br />
STATE_PLAYER_GAME_END => array(<br />
"name" => "playerGameEnd",<br />
"description" => clienttranslate('Game Over'),<br />
"descriptionmyturn" => clienttranslate('Game Over'),<br />
"type" => "activeplayer",<br />
"args"=>"arg_playerTurnAction",<br />
"possibleactions" => array( "end"),<br />
"transitions" =><br />
array(<br />
"next" => STATE_END_GAME,<br />
"loopback"=> STATE_PLAYER_GAME_END)<br />
),<br />
</pre><br />
<br />
<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 />
When changing css you have to force reload (Ctrl+R). But it also reloads all images which is long, if you want it faster you can define this function in js file, and call it from Browser js console<br />
<pre><br />
// this goes outside dojo class - before or after<br />
function reloadCss() {<br />
var links = document.getElementsByTagName("link");<br />
for (var cl in links) {<br />
var link = links[cl];<br />
if (link.rel === "stylesheet" && link.href.includes("99999")) {<br />
var index = link.href.indexOf("?timestamp=");<br />
var href = link.href;<br />
if (index >= 0) {<br />
href = href.substring(0, index);<br />
}<br />
<br />
link.href = href + "?timestamp=" + Date.now();<br />
<br />
console.log("reloading " + link.href);<br />
}<br />
}<br />
}<br />
<br />
</pre><br />
<br />
For mobile its also handy to have this as button (studio only), this goes to setup() function in js:<br />
<pre><br />
// add reload Css debug button<br />
var parent = document.querySelector('.debug_section');<br />
if (parent) {<br />
var butt = dojo.create('a', { class: 'bgabutton bgabutton_gray', innerHTML: "Reload CSS" }, parent);<br />
dojo.connect(butt, 'onclick', () => reloadCss());<br />
}<br />
</pre><br />
=== Debugging Toolips CSS/Layout ===<br />
<br />
To inspect tooltip you need to pin it so it does not disappear.<br />
* Chrome tools:<br />
** Open dev tools and switch to Source tab to engage with debugger<br />
** Hover over you element until tooltip showing<br />
** Press F8 - that stops the JS, so tooltip should freeze<br />
** Now you can go to Elements tab and find your tooltip at the botton in dijitTooltip div<br />
** Don't forget to resume it again to continue (F8 again or resume button)<br />
* Other method: Open the console (dev tools) large enough window, hover to make the tooltip appear and alt + tab to focus the console that will cover the tooltip. That way the onmouseout will never be triggered.<br />
<br />
=== Debugging my Javascript game interface logic ===<br />
<br />
To debug javascript you just use embedded browser debugger, usually found in Source tab of dev tools (F12)<br />
<br />
Modern browsers also allow you to put breakpoints in your js code. It is in source tab, but its a bit difficult to find (your code that is), see picture below on how to insert breakpoints.<br />
<br />
[[File:Bga-debug.jpg]]<br />
<br />
The easier method is to add breakpoint directly into your code and reload.<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 />
An alternative to adding a <code>debugger</code> statement in your code is to set a breakpoint directly in the dev tools window. You can do this by pressing Ctrl + B when your cursor is on the line where you want to set the breakpoint, or by clicking just to the left of the line number. One thing to be aware of is that refreshing via F5 removes set breakpoints, due to some cache busting values added to the URL. This can be remedied by adding this line to the end of your javascript source file, which enables the proper source mapping:<br />
<br />
<pre>//# sourceURL=myjsfile.js</pre><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 />
== 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 />
Checks for proper attributes values and browser's compatibility<br />
<br />
CSS: http://jigsaw.w3.org/css-validator/<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 />
* Before you load Slot1, open a second tab with the table, because after loading the slot, that tab will be unusable. In the second tab you can call LoadDebug() in the chat window<br />
<br />
<pre><br />
public function LoadDebug()<br />
{<br />
// These are the id's from the BGAtable I need to debug.<br />
// you can get them by running this query : SELECT JSON_ARRAYAGG(`player_id`) FROM `player`<br />
$ids = [<br />
86107517,<br />
86872172,<br />
85086097,<br />
84380410,<br />
11000525<br />
];<br />
<br />
// Id of the first player in BGA Studio<br />
$sid = 2296755;<br />
<br />
foreach ($ids as $id) {<br />
// basic tables<br />
self::DbQuery("UPDATE player SET player_id=$sid WHERE player_id = $id" );<br />
self::DbQuery("UPDATE global SET global_value=$sid WHERE global_value = $id" );<br />
self::DbQuery("UPDATE stats SET stats_player_id=$sid WHERE stats_player_id = $id" );<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=$sid WHERE card_location_arg = $id" );<br />
<br />
++$sid;<br />
}<br />
}<br />
</pre><br />
<br />
=== Fully automated version===<br />
Thanks to quietmint for [https://boardgamearena.com/forum/viewtopic.php?f=12&t=16454#p63167 coming up] with that!<br />
(updated and working on 05/06/2922)<br />
<br />
; In ggg.php<br />
<pre><br />
/*<br />
* loadBug: in studio, type loadBug(20762) into the table chat to load a bug report from production<br />
* client side JavaScript will fetch each URL below in sequence, then refresh the page<br />
*/<br />
public function loadBug($reportId)<br />
{<br />
$db = explode('_', self::getUniqueValueFromDB("SELECT SUBSTRING_INDEX(DATABASE(), '_', -2)"));<br />
$game = $db[0];<br />
$tableId = $db[1];<br />
self::notifyAllPlayers('loadBug', "Trying to load <a href='https://boardgamearena.com/bug?id=$reportId' target='_blank'>bug report $reportId</a>", [<br />
'urls' => [<br />
// Emulates "load bug report" in control panel<br />
"https://studio.boardgamearena.com/admin/studio/getSavedGameStateFromProduction.html?game=$game&report_id=$reportId&table_id=$tableId",<br />
<br />
// Emulates "load 1" at this table<br />
"https://studio.boardgamearena.com/table/table/loadSaveState.html?table=$tableId&state=1",<br />
<br />
// Calls the function below to update SQL<br />
"https://studio.boardgamearena.com/1/$game/$game/loadBugSQL.html?table=$tableId&report_id=$reportId",<br />
<br />
// Emulates "clear PHP cache" in control panel<br />
// Needed at the end because BGA is caching player info<br />
"https://studio.boardgamearena.com/admin/studio/clearGameserverPhpCache.html?game=$game",<br />
]<br />
]);<br />
}<br />
<br />
/*<br />
* loadBugSQL: in studio, this is one of the URLs triggered by loadBug() above<br />
*/<br />
public function loadBugSQL($reportId)<br />
{<br />
$studioPlayer = self::getCurrentPlayerId();<br />
$players = self::getObjectListFromDb("SELECT player_id FROM player", true);<br />
<br />
// Change for your game<br />
// We are setting the current state to match the start of a player's turn if it's already game over<br />
$sql = [<br />
"UPDATE global SET global_value=2 WHERE global_id=1 AND global_value=99"<br />
];<br />
foreach ($players as $pId) {<br />
// All games can keep this SQL<br />
$sql[] = "UPDATE player SET player_id=$studioPlayer WHERE player_id=$pId";<br />
$sql[] = "UPDATE global SET global_value=$studioPlayer WHERE global_value=$pId";<br />
$sql[] = "UPDATE stats SET stats_player_id=$studioPlayer WHERE stats_player_id=$pId";<br />
$sql[] = "UPDATE gamelog SET gamelog_player=$studioPlayer WHERE gamelog_player=$pId";<br />
$sql[] = "UPDATE gamelog SET gamelog_current_player=$studioPlayer WHERE gamelog_current_player=$pId";<br />
$sql[] = "UPDATE gamelog SET gamelog_notification=REPLACE(gamelog_notification, $pId, $studioPlayer)";<br />
<br />
// TODO Add game-specific SQL updates for the tables, everywhere players ids are used in your game <br />
$sql[] = "UPDATE deck SET card_location_arg=$studioPlayer WHERE card_location_arg=$pId";<br />
$sql[] = "UPDATE card SET card_location_arg=$studioPlayer WHERE card_location_arg=$pId";<br />
$sql[] = "UPDATE piece SET player_id=$studioPlayer WHERE player_id=$pId";<br />
$sql[] = "UPDATE log SET player_id=$studioPlayer WHERE player_id=$pId";<br />
$sql[] = "UPDATE log SET action_arg=REPLACE(action_arg, $pId, $studioPlayer)";<br />
<br />
// This could be improved, it assumes you had sequential studio accounts before loading<br />
// e.g., quietmint0, quietmint1, quietmint2, etc. are at the table<br />
$studioPlayer++;<br />
}<br />
$msg = <nowiki>"<b>Loaded <a href='https://boardgamearena.com/bug?id=$reportId' target='_blank'>bug report $reportId</a></b><hr><ul><li>" . implode(';</li><li>', $sql) . ';</li></ul>';</nowiki><br />
self::warn($msg);<br />
self::notifyAllPlayers('message', $msg, []);<br />
<br />
foreach ($sql as $q) {<br />
self::DbQuery($q);<br />
}<br />
self::reloadPlayersBasicInfos();<br />
$this->gamestate->reloadState();<br />
}<br />
</pre><br />
<br />
; In ggg.action.php<br />
<pre><br />
public function loadBugSQL() {<br />
self::setAjaxMode();<br />
$reportId = (int) self::getArg('report_id', AT_int, true);<br />
$this->game->loadBugSQL($reportId);<br />
self::ajaxResponse();<br />
}<br />
</pre><br />
<br />
; In ggg.js<br />
<pre><br />
// Load production bug report handler<br />
const self = this; // save the `this` context in a variable<br />
dojo.subscribe("loadBug", this, function loadBug(n) {<br />
function fetchNextUrl() {<br />
var url = n.args.urls.shift();<br />
console.log("Fetching URL", url, "...");<br />
// all the calls have to be made with ajaxcall in order to add the csrf token, otherwise you'll get "Invalid session information for this action. Please try reloading the page or logging in again"<br />
self.ajaxcall(url,<br />
{<br />
lock: true,<br />
},<br />
self,<br />
function (success) {<br />
console.log("=> Success ", success);<br />
<br />
if (n.args.urls.length > 1) {<br />
fetchNextUrl();<br />
}<br />
else if (n.args.urls.length > 0) {<br />
//except the last one, clearing php cache<br />
url = n.args.urls.shift();<br />
dojo.xhrGet({<br />
url: url,<br />
load: function (success) {<br />
console.log("Success for URL", url, success);<br />
console.log("Done, reloading page");<br />
window.location.reload();<br />
},<br />
handleAs: "text",<br />
error: function (error) {<br />
console.log("Error while loading : ", error);<br />
}<br />
});<br />
}<br />
}<br />
,<br />
function (error) {<br />
if (error)<br />
console.log("=> Error ", error);<br />
}<br />
);<br />
}<br />
console.log("Notif: load bug", n.args);<br />
fetchNextUrl();<br />
});<br />
</pre><br />
<br />
== Studio environment ==<br />
<br />
Some developers have requested a method allowing to know which environment the module is running on. While in general, your code should be the same on all environments so that the validation process makes sense, this may allow for example to display some helpers for testing during development while being sure that they'll never show up outside of the studio.<br />
<br />
From your <gamename>.game.php file you can use:<br />
<br />
<pre>if ($this->getBgaEnvironment() == 'studio') { ... }</pre><br />
<br />
Or if needed from your <gamename>.view.php file:<br />
<br />
<pre>if ($this->game->getBgaEnvironment() == 'studio') { ... }</pre><br />
<br />
<br />
<br />
[[Category:Studio]]</div>
BrianLovesMarvel
https://en.doc.boardgamearena.com/index.php?title=Deck&diff=15591
Deck
2022-12-20T17:32:39Z
<p>BrianLovesMarvel: /* Create a new Deck component */ Added hints about where to create the deck object, where to initialize it, where to createCards, and the return value of the pickCard being an array.</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 />
In particular, if you are going to have deck locations specific to individual players, you may wish to use their player IDs in the card_location field. Those IDs can be 8+ characters long, leaving only 8 characters for the rest of the name if you use the varchar(16). If you exceed the size of the field, it will get silently truncated, which can be very difficult to troubleshoot!<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 />
Note that you need to create a table for each "Deck", table name should be "first_kind_card" but the fields must remain "card_id", "card_type" and so on.<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":<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 cards to create ("nbr"). "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 />
HINT: Create the deck object self::getNew and do the init call in the constructor or you will get "$this->cards" as an invalid reference later. <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 />
HINT: Be sure to do the createCards in setupNewGame. Doing createCards in the constructor will throw database errors.<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 />
The return value is an array of the card data elements (id, type, type_arg...) for that card.<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 (indexed by the card ID), 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=0 )'''<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. (Lower numbers: bottom of the deck. Higher numbers: top of the deck.)<br />
<br />
(note: Filling an empty location this way with N cards creates "location_arg"s from 1 to N if "$bOnTop" is true and -1 to -N if "$bOnTop" is false. This can cause off-by-one errors for code intended to run on a deck generated by "shuffle( $location )" which generates "location_arg"s from 0 to N - 1.)<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. If null, cards from all locations will be move.<br />
* to_location: where to put the cards<br />
* from_location_arg (optional): if specified, only cards with given "location_arg" are moved.<br />
* to_location_arg (optional): if specified, cards moved "location_arg" is set to given value. Otherwise "location_arg" is set to 0.<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 card IDs.<br />
<br />
If some cards are not found or if some card 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 (often in the ''_construct'' function when you ''init()'' the Deck object).<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).<br />
<br />
[[Category:Studio]]</div>
BrianLovesMarvel
https://en.doc.boardgamearena.com/index.php?title=Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl&diff=7092
Game layout: view and template: yourgamename.view.php and yourgamename yourgamename.tpl
2021-01-28T05:48:23Z
<p>BrianLovesMarvel: Added overview diagram</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
== Overview ==<br />
[[File:bga-pages-from-templates.PNG|700px]]<br />
<br />
There are two files involved in overall game layout: yourgamename.view.php and yourgamename_yourgamename.tpl.<br />
<br />
These 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 .tpl file 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 />
Things is curly braces are template variables. You cannot put any engish text directly there.<br />
<br />
Your view and your template 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 />
* The tokens which are always on the board (but JS code may move them around during setup)<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 />
== 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 />
https://web.archive.org/web/20170506065401/http://www.phpbuilder.com:80/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 values.<br />
<br />
In the example above, "{MY_HAND}" is a variable. As you can see, a variable is uppercase characters surrounded by "{" and "}".<br />
<br />
This is example of how to assign values to these variables in .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 />
WARNING: do not use a variable called {LB_[whatever]} as any variable starting with LB_ will interfere with the translation system.<br />
<br />
== Template 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 />
for( $y=1; $y<=8; $y++ ) {<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 as xml comment. 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 />
// 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 />
$this->page->insert_block( "card_place", array( <br />
'PLAYER_ID' => $player_id,<br />
'PLACE_ID' => $i<br />
)<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 />
These will allow to separate all html from javascript and php files and keep it strictly in template file.<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 />
Note that '''you must translate''' any text arguments passed to ''this.format_block()'' that will be rendered on the screen, for example [[Translations#On_client_side_.28Javascript.29|using "_()"]].<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></div>
BrianLovesMarvel
https://en.doc.boardgamearena.com/index.php?title=File:Bga-pages-from-templates.PNG&diff=7091
File:Bga-pages-from-templates.PNG
2021-01-28T05:38:56Z
<p>BrianLovesMarvel: Overview of generating BGA web pages from HTML and Javascript templates.
Brian Hanna brianhannamn@gmail.com 01/27/2021</p>
<hr />
<div>== Summary ==<br />
Overview of generating BGA web pages from HTML and Javascript templates. <br />
Brian Hanna brianhannamn@gmail.com 01/27/2021</div>
BrianLovesMarvel
https://en.doc.boardgamearena.com/index.php?title=Create_a_game_in_BGA_Studio:_Complete_Walkthrough&diff=7023
Create a game in BGA Studio: Complete Walkthrough
2021-01-23T23:31:33Z
<p>BrianLovesMarvel: /* Create State Machine */</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 your 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 are stuck or have questions about this page post on [https://forum.boardgamearena.com/viewforum.php?f=12 BGA Developers forum].<br />
If you're uncomfortable posting on the public forum you can send messages 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 [https://en.studio.boardgamearena.com/licensing 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 a game you really want to do or you can request a license yourself. You can read more about game licenses on [[BGA Game licenses]] page.<br />
<br />
Once you selected the game but before creating a new project, please take a 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 a few projects with name of the game they may not be active. There are a lot of abandoned game projects. If it's not clear by the status, post to Developers forum asking if anybody actively working on the project or send a message to developers listed for the abandoned projects, and at the same time ask admins on the same forum post to send you graphics for that game if they have them (there a button on [https://en.studio.boardgamearena.com/licensing Available Licenses] page to request graphics, but it will just send email).<br />
<br />
If your goal was to fix bugs in an existing project, first try to locate on studio, projects developed by bga admins are not in the studio. Then get read only access to the project and you can create your own as a copy of the existing one. Contact existing project admin about getting write access to the original project or if they willing to take your patches - apply them.<br />
<br />
If you want to take over an 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''' and '''you don't include a file with your sftp password''' (github is automatically crawled for passwords by hackers; a hacking attempt occurred on BGA studio for this reason in June 2020).<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 by contacting studio@boardgamearena.com. While that request is being processed (it can take time, as it often requires some back and forth between the admins and the publishers) 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 />
== Reduce the Rules ==<br />
<br />
Programming a game will take a lot more time than you may think. Most of the projects in the studio are abandoned because of lack of patience or skill.<br />
To keep sane, start the game with *reduced* rules and try to complete that first.<br />
<br />
* If it has any expansions - do not even attempt to deal with them, not even - "I will just add graphics for them now and not use" - waste of time if you don't complete basic<br />
* If it has advanced rules - start with basic rules only, i.e. "beginner game"<br />
* If it has special rules for 2 player vs 4, start with most basic form (i.e. 4), restrict to 4 players <br />
* If it has 50 unique cards of 2 each - start with 2 unique cards with 25 each (just to keep it moving)<br />
* Any sort of rules that you think can be removed and not included in base - set aside for now <br />
* Ignore any sort of cool animations - dice rolling, card flipping, choo-choo sounds of the trains - all this fluff can be added later<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 you moral satisfaction!<br />
<br />
There are a few ways how the html could have been generated. You could have started with nothing and generate<br />
it 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 also provides a third way, which is mix of both, plus a template engine to generate HTML using php. The only thing that is really annoying about the template engine is<br />
that you cannot put any translatable strings in the template (which means any visible text at all). If you are using the template approach all stings have to extracted as variables and injected through php (.view.php). This page explains the template engine in great detail:[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl|Template Engine]].<br />
<br />
The other disadvantage of the template engine is you cannot run and debug it locally, in the beginning of development it's 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 a few classes that already exist 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 when trying write than 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 />
Start by creating and mapping all games assets, best way is probably to open rule book on "boardgame contents" page and go through every piece. Every pieces of boardgame would have its "print" in multiple files in your game:<br />
* Some sort if "div" in html, where id of element match id of element in database (easiest way)<br />
* Css for the element (either unique or for class), usually with background propery refering to part of sprite image<br />
* Entry in material.inc.php referring to static properties of the element, i.e. name, tooltip, rules, etc<br />
* Entry in .tpl file to represent static or initial location on the table OR creation template<br />
<br />
Here are some specific examples:<br />
<br />
'''Game Board'''<br />
<br />
Create entry in .tpl file for the board, it will be static entry as we never need to create this dynamically<br />
<pre><br />
<div id="board" class="board shadow board4p"> ... </div><br />
</pre><br />
Create entry in .css file for this board and other board variants (in example below we have 4 ppl board whcih is diffrent than 2 ppl board)<br />
<pre><br />
.board {<br />
position: relative;<br />
width: 980px;<br />
height: 433px;<br />
margin-bottom: 5px;<br />
}<br />
<br />
.board4p {<br />
background-image: url(img/board4p.jpg);<br />
}<br />
</pre><br />
That wold be pretty much it for the board itself, as it does not really tooltip on the whole things so we don't need entry in material.inc.php<br />
<br />
<br />
'''Game Board Slots'''<br />
<br />
These are interactive areas on the board, usually illustrated as such. In most cases you can get away with rectangular shapes, but sometimes you have to create circle or oval shapes (and in really advanced case would be some svg paths). For slots you can do the following:<br />
<br />
Entry in material.inc.php<br />
<pre><br />
$this->token_types = array(<br />
...<br />
'slot_action_2' => array(<br />
'type' => 'slot_action',<br />
'name' => clienttranslate("2 Gray Track Advancements"),<br />
'tooltip' => clienttranslate("This action gives you two advancements of gray track. You cannot use this action if you cannot complete all advancements."),<br />
'o'=>"1,0,0,gg", // automatic rules<br />
),<br />
...<br />
</pre><br />
<br />
Entry in template inside the "board" div<br />
<pre><br />
<div id="slot_action_2" class="slot_action_2 slot_action slot_w_1 slot"></div><br />
</pre><br />
<br />
Entry in .css with absolute position within the board (its actually better to use percentage - would be easier to scale later)<br />
<pre><br />
.slot_action_2 {<br />
top: 83px;<br />
left: 37px;<br />
}<br />
.slot_action {<br />
position: absolute;<br />
width: 46px;<br />
height: 26px;<br />
padding: 9px 7px 6px 4px;<br />
}<br />
</pre><br />
<br />
'''Meeples''' - also cards, tokens, other mobile stuff<br />
<br />
In css these guys will use "sprite" images with transparency, so it will look like this this<br />
<pre><br />
.meeple {<br />
background-image: url(img/tokens.png);<br />
width: 25px;<br />
height: 25px;<br />
}<br />
.meeple_ff0000 { /* red */<br />
background-position: 14% 0%;<br />
}<br />
</pre><br />
As for creation you can either generate them using template (where whole thing wrapped in template block and {COLOR} replace with all possible colors in .view.php<br />
<pre><br />
<div id="meeple_{COLOR}_1" class="meeple meeple_{COLOR} meepleable"></div><br />
<div id="meeple_{COLOR}_2" class="meeple meeple_{COLOR} meepleable"></div><br />
...<br />
</pre><br />
<br />
Or you can declare a template js var in .tpl file <br />
<pre><br />
var jstpl_mepple = '<div id="meeple_${color}_${num}" class="meeple meeple_${color} meepleable"></div>'; // this is in .tpl file at the bottom<br />
</pre><br />
and create in js, like this<br />
<pre><br />
var tokenDiv = this.format_block('jstpl_mepple', {<br />
"color" : color,<br />
"num" : i<br />
}); // this in js code somewhere before placing it<br />
</pre><br />
If you dealing with cards and decks, there are pre-build components that can generate stuff for you.<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 and "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 />
So at the end of this stage you should complete the following:<br />
* Create a 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're not supposed 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 />
* Create material.inc.php and populate with initial values (names, tooltips, rules) for all relevant game elements or classes of elements<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 />
<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 (in general, 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 the pieces are connected together.<br />
The state machine states.inc.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 first 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]].<br />
<br />
Finally, visit the game page for your alpha game (https://boardgamearena.com/gamepanel?game=…) to add the following information if you can:<br />
* Links to the rules (in multiple languages if available).<br />
* Links to teaching videos.<br />
* In the "On the web" section, links to:<br />
** The official website for the game (if there is one).<br />
** The BoardGameGeek page for the game.<br />
* Consider writing a summary of the rules.</div>
BrianLovesMarvel
https://en.doc.boardgamearena.com/index.php?title=Troubleshooting&diff=7014
Troubleshooting
2021-01-23T18:46:51Z
<p>BrianLovesMarvel: /* This game action is impossible right now */</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 />
Check if you're calling self::getActivePlayerName () during setupNewGame()<br />
<br />
Check if you're NOT calling self::activeNextPlayer() at the end of your game setup. You must always have at least one active player.<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 />
=== 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 />
=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: BGA main website do not respond ===<br />
<br />
Check if other games work; if not, it's a problem with BGA Studio; if so, your game likely reaches an end state immediately. Check your states.inc.php and your transitions.<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 />
== Game starts but I can't make a move ==<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..." then 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 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 />
=== 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, (event)=>{})<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 />
=== "This is not your turn" error when I click on a possible move ===<br />
<br />
You need to change to the active player by clicking the red arrow next to their name in the player panel (right side of the page).<br />
<br />
[[File:Change_active_player.jpg]]<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 'possibleactions' array.<br />
<br />
Also check your onActionName javascript function. Make sure you are calling the right "actionname.html".<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 />
If you have "dojo.publish is not defined" or something similar, this could be caused by another error earlier. For example, a syntax error caused by a malformed generated file (such as using newlines in tiebreaker description). Also you might have left some images in the /img directory with special characters in the name which must be removed. If you edited images for the game box and website, ensure that you have not left any unnecessary files there.<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 />
=== Unable to find table database (1): ebd_yourgame_112222 ===<br />
<br />
Its either temporarily server error especially on studio it timeouts sometimes, just try reloading again.<br />
Or check if you have syntax errors in your php game file or sql.<br />
<br />
== Type conversion / juggling errors ==<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'.<br />
<br />
=== Integer columns in the database are returned as strings ===<br />
<br />
This is normal PHP behavior. All fields are returned as string type, regardless of their actual type in the database. This also applies to global variables accessed via getGameStateValue(), since they are stored in a database table.<br />
<br />
You can use type-casting to convert them to the correct type after they come out of the database.<br />
<br />
$myValueInt = (int)self::getGameStateValue(GLOBAL_ROUND_NUMBER);<br />
<br />
or<br />
<br />
$myValueInt = self::getGameStateValue(GLOBAL_ROUND_NUMBER) + 0; // adding 0 casts to int<br />
<br />
<br />
same with direct qdb ueries<br />
$sql = "SELECT my_int_column FROM my_table WHERE my_condition";<br />
$myResult = self::getUniqueValueFromDB($sql); <-- this is a string<br />
$myResultAsInt = (int)$myResult;<br />
<br />
https://stackoverflow.com/questions/5323146/mysql-integer-field-is-returned-as-string-in-php<br />
<br />
== Zombie mode ==<br />
<br />
=== Unexpected error: Propagating error from GS 1 (method: zombie): Not logged ===<br />
<br />
You are probably calling getCurrentPlayerId() or getCurrentPlayerName() in your zombieTurn method or any of the methods it uses. Instead, use the $active_player_id provided as parameter to zombieTurn().<br />
<br />
=== Unexpected error: Can't manage zombie player in this game state ===<br />
<br />
Despite what the message suggests, this error has nothing to do with your state machine. It is caused by an exception in the zombie code. It could be an undefined value sent to a database query. Check the unexpected exceptions log. It could also be the same problem as above, so look for getCurrentPlayerId() or getCurrentPlayerName() in your zombieTurn method.<br />
<br />
=== Unexpected error: Wrong formatted data from BGA gameserver 1 (method: zombie): ===<br />
<br />
This is almost certainly an undefined value in PHP code. Look for a warning or error message in the game replay log on the right side of the table UI.<br />
<br />
=== Unexpected error: BGA gameserver 1 do not respond (method: zombie) (timeout: cluster) ===<br />
<br />
You are trying to end the game from a zombie method. This is not allowed. The zombie logic must continue the game as best it can. See [[Main_game_logic:_yourgamename.game.php#Zombie_mode|Zombie mode]] for more info.<br />
<br />
=== Game unexpectedly ends when one player becomes zombie ===<br />
<br />
There is an error in handling zombie mode, check error log. Example: if the zombie turn is called again, framework detects a infinite loop and cancels the game. On the studio there is a notification called ZombieTurnFailed<br />
<br />
== Other errors ==<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 />
}</div>
BrianLovesMarvel