Board Game Arena - User contributions [en]

Tutorials checklist

2024-02-20T09:24:03Z

Archduke:

In order to allow for a full-fledged tutorial to be built for the game you have adapted on BGA studio:
# the game replay archive generated for the game must be valid (you should be able to run the replay from start to finish without errors using the "Replay game" function on a finished table)
# each action of the replay should be replayable by triggering it manually (i.e. by reproducing the exact same sequence as done played originally during the game
# each element of the game interface should be available for attaching a comment or a highlight component on it.

You can read more about building tutorials in practice here: https://boardgamearena.com/tutorialfaq

If a player trying to create a tutorial reports you an issue about 1) or 2), the most likely reasons for the issue are:
* that you have triggered this.ajaxcall() programmatically in a notification handling function or a callback instead of only on a user interface action.
* or (for 2) ), that there are several way to trigger the next action with different URL/arguments. You should make sure that the same game actions are triggered with the same "ajaxcall" whatever the UX path used.

If a player trying to create a tutorial reports you an issue about 3):
* you might have some overlapping elements preventing to access the "div" tag of an important interface element to attach tutorial content to it.
* you might have some missing "ID" on elements of the interface, preventing the tutorial author to attach elements to them.

== Publishing Tutorials ==
Tutorials, in general, are only published if they satisfy these conditions:

* They have an average rating of 4.2 or higher
* They have been rated at least 10 times (for moving to BETA)
* They have been rated at least 100 times (for moving to LIVE)

If a tutorial should be published, but does not meet these requirements, the help of a BGA admin is required.

== Tutorial Game release override ==

In case someone already wrote a tutorial that did not work well because something small must be changed in the game adaptation code, it may be possible to make the existing tutorial works with a newer version of the game adaptation.

Example:
* You wrote 90% of a tutorial for game Carcassonne, based on a game replay which is using BGA version V1.
* Because of a problem in the game adaptation, you cannot write the remaining 10%.
* The developer of the Carcassonne adaptation fixes the issue in a new version of Carcassonne for BGA: version V2.
* You will have to rewrite the entire tutorial using a replay based on a game played with this new version V2.
* HOWEVER, using Tutorial game release override, you can ask a BGA admin to switch your tutorial to the newer version of the game.

Important: This can only works if the game release updates are limited. To be more specific: the new version must be compatible with the moves notifications sent by the previous version. For example, if on the new version you expect on Client side a new parameter in a move notification, the version override will just break the replay and make your tutorial unplayable.

As a tutorial author, if you want to do this switch, please write an email to studio(at)boardgamearena.com specifying:
* The tutorial ID (you must be the tutorial author or the game adaptation developer)
* The game version that the tutorial should use
* "Tutorial game release override" as email subject

Template:Studio Framework Navigation

2023-12-12T11:18:54Z

Archduke:

<div class="studio-framework-navigation" style="float: right; width: 300px; border: solid #000 1px; padding: 1em; margin-left: 1em; background: #fff;">

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game File Reference'''</center></div>

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''[[Studio file reference|Overview]]'''</center></div>

* [[Game database model: dbmodel.sql|<b>dbmodel.sql</b>]] - database model
* [[Game meta-information: gameinfos.inc.php|<b>gameinfos.inc.php</b>]] - meta-information
* [[Options and preferences: gameoptions.json, gamepreferences.json|<b>gameoptions.json</b>]] - game options & user preferences
* [[Game art: img directory|<b>img/</b>]] - game art
* [[Game_metadata_manager|<b>Game Metadata Manager</b>]] - tags and metadata media
* [[Game material description: material.inc.php|<b>material.inc.php</b>]] - static data
* <b>misc/</b> - studio-only storage
* <b>modules/</b> - additional game code
* [[Your game state machine: states.inc.php|<b>states.inc.php</b>]] - state machine
* [[Game statistics: stats.json|<b>stats.json</b>]] - statistics
* [[Players actions: yourgamename.action.php|X.<b>action.php</b>]] - player actions
* [[Game interface stylesheet: yourgamename.css|X<b>.css</b>]] - interface stylesheet
* [[Main game logic: yourgamename.game.php|X.<b>game.php</b>]] - main logic
* [[Game interface logic: yourgamename.js|X.<b>js</b>]] - interface logic
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X.<b>view.php</b>]] - dynamic game layout
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X_X.<b>tpl</b>]] - static game layout
<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Useful Components'''</center></div>

'''Official'''

* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
* [[Draggable]]: a JS component to manage drag'n'drop actions.
* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.
* [[Zone]]: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).

Undocumented component (if somebody knows please help with docs)
* [[Wrapper]]: a JS component to wrap a <div> element around its child, even if these elements are absolute positioned.

'''Unofficial'''

* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks
* [[Some usual board game elements image ressources]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game Development Process'''</center></div>

* [[First steps with BGA Studio]]
* [[Create a game in BGA Studio: Complete Walkthrough]]
* [[Tutorial reversi]]
* [[Tutorial gomoku]]
* [[Tutorial hearts]]
* [[BGA Studio Guidelines]]
* [[BGA game Lifecycle]]
* [[Pre-release checklist]]
* [[Post-release phase]]
* [[Help|Player Resources]] - add player help/rules to your game page

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Guides for Common Topics'''</center></div>

* [[Translations]] - make your game translatable
* [[Game replay|Game Replay]]
* [[Your game mobile version|Mobile Users]]
* [[3D]]
* [[Compatibility]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Miscellaneous Resources'''</center></div>

* [[Studio FAQ]]
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment
* [[Studio logs]] - Instructions for log access
* [[Practical debugging]] - Tips focused on debugging
* [[Troubleshooting]] - Most common "I am really stuck" situations
* [https://studio.boardgamearena.com/bugs Studio Bugs] - Reports against Studio itself (not BGA!)
</div>

Troubleshooting

2023-11-15T12:48:39Z

Archduke:

Describing common errors which are hard to understand and debug. This may be useful for troubleshooting.

__TOC__

== Game does not start at all ==

=== Undefined offset: 0 in table/table.game.php on line 1417 ===

Do not call self::getActivePlayerName() during setupNewGame()

Ensure you're calling $this->gamestate->changeActivePlayer() at the end of your game setup. You must always have at least one active player.

=== Javascript error: During pageload n is null ===

When calling dojo.place(), the name of the container (second parameter) to place the new block into is not defined in the page template.

=== Unexpected error: Wrong formatted data from BGA gameserver 1 (method: createGame): ... ===

This is generic message usually followed by exact position in your source code, and usually its syntax error in one of yours php script

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Not logged ===

Calling self::getCurrentPlayerId () or using $g_user from 'args' state function, see also below

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Unknow player statistic: ===

Calling self::incStat() with second parameter which is an empty string

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Error while processing SQL request: INSERT INTO stats ... ===

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')
Duplicate entry '10-2300663' for key 'stats_table_id'

Why? In the stats.inc.php you declared two keys with the same integer "id"

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: BGA main website do not respond ===

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.

=== Unexpected error: Propagating error from GS 1 (method: createGame): BGA service error ===

You may have a syntax error in your dbmodel.sql.

Or, you may be calling self::initStat() for a statistic that does not exist. Check the statistic name, and make sure you clicked "Reload statistics configuration" button in the admin console after making changes to stats.inc.php

Or you may not have your states.inc.php set up correctly.

You may have an error in your table.game.php file in setupNewGame (such as <code>$result['x'] = y;</code> when $result is not an array).

=== Unexpected error: Table status of a starting game should be 'setup' ===

This error message appears when you start a one player game using the "Express Start" button.

In normal situation, the game starts just after this message and everything should works normally. In this case, you can just ignore this message.

If the games does not start, it is most probable that there is a syntax error in any of your php code (Check your states.inc.php and X.game.php)

=== Fatal error during creation of database ebd_quoridor_389 Not logged ===

Check that you didn't use $g_user or getCurrentPlayerId() in setupNewGame() function or in an 'args' function of your state.

As these functions are not consequences of a user action, there is no current player defined.

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.

=== Warning: Invalid argument supplied for foreach() in table.game.php ===

Warning: Invalid argument supplied for foreach() in /var/tournoi/release/tournoi-151226-1240-gs/www/game/module/table/table.game.php on line 129
Fatal error: Cannot unset string offsets in /var/tournoi/release/tournoi-151226-1240-gs/www/game/module/table/table.game.php on line 143

That appears when your arg* function that suppose to return array of state arguments returns a scalar (a non-array) value

=== The server reported an error ===

During table creation: "The server reported an error" error shown and nothing else.

If you cannot even create a table - there is syntax error in gameinfos.php, check it, reload it from management panel.
If still no luck copy clean version from template https://github.com/elaskavaia/bga-sharedcode/blob/master/gameinfos.inc.php

=== Unexpected Error : Invalid player number for this game : 4 ===

This error may comes when trying to change the player number configuration in gameinfos.inc.php from a higher to lower number of players (for example from 4 to 2).

The following steps will help to change a player config from array(4) to array(2) :

* change in gameinfos.inc.php the entry to 'players' => array( 2,3,4 )
* In game management page (Control Panel > Manage Games > "Your Game"), press the "Reload Game information" button
* create a new table
* reduce the number of players to 2 and start the game
* (express) Stop the game
* change in gameinfos.inc.php the entry to 'players' => array( 2 )
* press again the "Reload Game information" button

=== Blank page ===
If you see no html at all check
* if you have syntax error in your view.php file
* class name of your view.php file does not match the project name (should be view_foo_foo if project is foo)
* game name return by getGameName() does not match the project name (should be "foo" if project is foo)

class view_russianrailroads_russianrailroads extends game_view {
function getGameName() {
return "russianrailroads";
}

=== "Ooooops, this page does not exists :/" ===
If your table is created, but you are redirected to <code><nowiki>https://studio.boardgamearena.com/1/index.php</nowiki></code> when you try to launch your table, then you are most likely missing the [[Players actions: yourgamename.action.php|action PHP file]].

No other error is displayed or logged, meaning this can be tough to debug.

Make sure the file is correctly named, as any typo means the studio won't be able to find the file.

== Game starts but I can't make a move ==

=== When I do a move, I got "Move recorded, waiting for update ..." forever ===

"Move recorded" means that your ajaxcall request has been sent to the server and returned normally.

"Waiting for update" means that your client interface is waiting for some notifications from the server that correspond to the move we just did.

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.

=== When I do a move, I get "Sending move to server..." then nothing and game resets to state before the move ===

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
to trace where it hangs.

You may also see this error in the log in this case: "Error (2006) while processing SQL request: MySQL server has gone away"

=== When I do a move, I get "Ajaxcall error: empty answer" ===

You either have missing self::ajaxResponse(); in your [[Players actions: yourgamename.action.php|game.action.php]] method, or there is some problem with getting arguments (check that you are using btoa() on client when using AT_base64 arg type in action.php)

=== When I do a move, I get "Gameserver is locked by configuration". ===

You may have an error in your AJAX path, such as /reversi/reversi when your game's name is different.

=== Some player action is triggered randomly when I click somewhere on the game area ===

You probably used "dojo.connect" on a null object. In this case, dojo.connect associate the event (ex: "onclick") to the whole game area.

Most of the time it happens in this situation, when my_object element does not exists:
<pre>
dojo.connect( $("my_object"), "onclick", this, (event)=>{})
</pre>

To determine if this is the case, place "alert( $("my_object") )" before the dojo.connect to check if the object exists or not.

=== Error: This is not your turn ===

This happens when checkAction() is called and current player is NOT the active player.

You can change the active player in studio by clicking the red arrow next to their name in the player panel (right side of the page).

[[File:Change_active_player.jpg]]

=== Error: Please wait, an action is already in progress ===
Its followed by error "(Generated by checkAction / XXX)" on studio.

This error is triggered in the JS by the checkAction function for XXX action.

This can happen when the player sent an Ajax request action earlier, and:
* action is not complete yet - i.e. takes some time, and user clicked something again
* if there is bug in interface where MULTIPLE handlers are fired on same click. To debug this add some console.trace() in place this specific checkAction is called.
* did not get any notification from the PHP side. To avoid this, put an empty notifyPlayer in the PHP side of the Ajax handler to ensure the client receives a response. This line of code should do it:
<pre>
$this->notifyPlayer($this->getCurrentPlayerId(), 'message', '', []); // sent to current player, who originated the action
</pre>

=== Error: This move is not authorized now ===
This is generic error message generated by this.showMoveUnauthorized() function. If you did not call this function yourself, check the console log, it may have additional information.
If you see "Move not authorized now : XXX" in the log, where XXX is your action name - this means that action XXX is not defined in list of possible actions for your current state. This error generated by checkAction() function.

=== Error: You are not connected - after waiting for the submitted move ===
In the log you may find:
Query execution was interrupted, maximum statement execution time exceeded - Request: SELECT global_id, global_value FROM global WHERE 1

The error message above is because of failed attempt to lock a table, which happens because of infinite loop in you game.
* Check that don't enter same game state over and over again
* Check that you reverse for loop actually descrease counter or other loop issues
* Check that recursive function ends

== Predefined server errors ==

=== Unexpected error: Unexpected final game state (XX) ===

The action function does not transition to any state, i.e.
function selectField($field) {
self::checkAction ( 'selectField' );
if ($field!=0) $this->gamestate->nextState ( 'next' );
}
Here if $field is 0 there is no transition

=== This game action is impossible right now ===

Check the game log. Usually your state does not define the action you trying to perform in 'possibleactions' array.

Also check your onActionName javascript function. Make sure you are calling the right "actionname.html".

=== Unexpected error: This transition (playerTurn) is impossible at this state (42) ===

This is pretty self explanatory. Function nextState() takes transition name not a state name, so you probably did not
define this transition that the given state

== Game interface hangs during reload or on start ==

Showing "Application Loading..."

=== Javascript error: During pageload undefined no_stack_avail Script: ===

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
in dojo.connect, this.connectClass, dojo.subscribe, etc

this.connectClass('field', 'onclick', 'onField'); // <-- onField is not defined

=== Other errors with "Application loading..." ===

You probably have a syntax error in your Javascript code, and the interface refuses to load.

To find this error, check if there is an error message in the Javascript console (F12).

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.

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.

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.

=== Unexpected Syntax Error: ===

No further details in the log. When log is filling with some social connect errors.

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.

=== Game interface spins in a loop throwing error ===

Errors is something like "Cannot read property 'is_ai' of undefined". Cannot restart the game because cannot access UI to stop.
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
(can copy from row 5 for example).

=== Unable to find table database (1): ebd_yourgame_112222 ===

Its either temporarily server error especially on studio it timeouts sometimes, just try reloading again.
Or check if you have syntax errors in your php game file or sql.

== Type conversion / juggling errors ==

=== On php side I get a number instead of string I expect ===

$num = 3;
$meeple = "meeple_" + $num; // <-- suppose to be "meeple_3"!

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!),
in php + means integer arithmetic. So change + to . (dot)

=== On php side my string comparison does not work ===

if ($color == '4baae2' || $color == '000000') {
}

Apparently you should not be using '==' in php to compare strings! You should use '==='. The (==) operator will typecast the strings
to numbers then do comparison!
Its not very apparent because usually you can get away with it, but not when strings resemble numbers like hex 'colors'.

=== Integer columns in the database are returned as strings ===

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.

You can use type-casting to convert them to the correct type after they come out of the database.

$myValueInt = (int)self::getGameStateValue(GLOBAL_ROUND_NUMBER);

or

$myValueInt = self::getGameStateValue(GLOBAL_ROUND_NUMBER) + 0; // adding 0 casts to int

same with direct qdb ueries
$sql = "SELECT my_int_column FROM my_table WHERE my_condition";
$myResult = self::getUniqueValueFromDB($sql); <-- this is a string
$myResultAsInt = (int)$myResult;

https://stackoverflow.com/questions/5323146/mysql-integer-field-is-returned-as-string-in-php

== Zombie mode ==

=== Unexpected error: Propagating error from GS 1 (method: zombie): Not logged ===

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

If you do not see these commands within "function zombieTurn( $state, $active_player ){}", check all the functions called from zombieTurn, also "function getGameProgression(){}" and all the functions THAT calls.

=== Unexpected error: Can't manage zombie player in this game state ===

The state the game was in at the time the error was generated didn't have "transitions" => array( "zombiePass" => 27 )" in states.inc.php (27 was an arbitrary example, but everything else must be spelled exactly that way.)

To correct this error, either add "zombiePass" => ## to the transitions array or work out why the game is in a state it should not be in.

=== Unexpected error: Wrong formatted data from BGA gameserver 1 (method: zombie): ===

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.

=== Unexpected error: BGA gameserver 1 do not respond (method: zombie) (timeout: cluster) ===

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.

=== Game unexpectedly ends when one player becomes zombie ===

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

== Dead locks ==

=== Database dead lock in multiplayer state ===
You normally won't see this error until game is released because to reproduce game it have to be hit with 2 players doing an action simultaneosly.
You only can reprodoce this on studio if you either very fast or you use a script (with direct REST calls).

There is few types of deadlocks
I) Try-lock - this one you don't need to worry about even it does appear in the log, this is 2 player doing the action and second cannot lock db, it will re-try up to 3 times and hopefully it be ok
II) Real dead lock - when 2 tables are locked in reversed by 2 actions, its unclar if this really happen but workaround number 2 theorically should solved it (but it will increase number of deadlocks of type I)

There are two known workarounds:

1) Use $this->bIndependantMultiactiveTable=true in constructor which will force usage of playermultiactive table, but this does not eliminate dead lock completely.

2) Before every action explictly lock tables in specific order (add this code in your game.php file)
<pre>
// Due to deadlock issues involving the playersmultiactive and player tables,
// standard tables are queried FOR UPDATE when any operation occurs -- AJAX or refreshing a game table.
//
// Otherwise at least two situations have been observed to cause deadlocks:
// * Multiple players in a live game with tabs open, two players trading multiactive state back and forth.
// * Two players trading multiactive state back and forth, another player refreshes their game page.
private function queryStandardTables() {
// Query the standard global table.
$this->DbQuery("SELECT global_id, global_value FROM global WHERE 1 ORDER BY global_id FOR UPDATE");
// Query the standard player table.
$this->DbQuery("SELECT player_id id, player_score score FROM player WHERE 1 ORDER BY player_id FOR UPDATE");
// Query the playermultiactive table. DO NOT USE THIS is you don't use $this->bIndependantMultiactiveTable=true
$this->DbQuery("SELECT ma_player_id player_id, ma_is_multiactive player_is_multiactive FROM playermultiactive ORDER BY player_id FOR UPDATE");

// TODO should the stats table be queried as well?
}

/** This is action function that canbe called from multiplayer state */
protected function actionXXX() {
$this->queryStandardTables();
... // your arg function code
}
/** This is arg function of multiplayer state, XXX is replaced by actual name of state.
You need to do it for EVERY arg function in multiplayer states which accesses the database.
You don't need to do it for arg function for single player states
*/
protected function argXXX() {
$this->queryStandardTables();
... // your arg function code
}
</pre>

== Other errors ==

=== Javascript does not know how to sum two numbers ===

Be careful when you manipulate integers returned by notifications: most of the time, Javascript considers they are Strings and not Integers.

As a result:
<pre>
var i=1;
i += notif.args.increment; // With notif.args.increment='1'
alert( i ); // i=11 instead of 2 !! Javascript concatenate 2 strings !
</pre>

To solve this, you should use the "toint" function:
<pre>
var i=1;
i += toint( notif.args.increment ); // With notif.args.increment='1'
alert( i ); // i=2 :)
</pre>

=== Javascript: do not use substr with negative numbers ===

To get the last characters of a string, use "slice" instead of "substr" which has a bug on IE:
<pre>
var three_last_characters = string.substr( -3 ); // Wrong
var three_last_characters = string.slice( -3 ); // Correct
</pre>

=== Game "spontaneously" transition to a new state without user input ===

Make sure on php side you have no code after $this->gamestate->nextState(...) code.
Because if you do accidentally have code that goes to another state it will cause another state transition without user interaction.

function selectField($field) {
self::checkAction ( 'selectField' );
if ($field!=0) $this->gamestate->nextState ( 'next' );
$this->gamestate->nextState ( 'last' ); // <-- here is missing else, so it will cause double state transition
}

=== Message "Invalid or missing substitution argument for log message: ${actplayer} ... " when entering a state ===

You probably have an args function defined for that state that does '''not''' return an array

=== Server syntax error: Warning: count(): Parameter must be an array or an object that implements Countable in /var/tournoi/release/tournoi-220308-1000-gs/www/game/module/table/gamestate.game.php on line 823 ===

Generally comes with that syntax error : Warning: implode(): Invalid arguments passed in /var/tournoi/release/tournoi-220308-1000-gs/www/game/module/table/gamestate.game.php on line 845

It is most probable that you used setPlayersMultiactive method with id of a single player not included in an array -> you should use: ... setPlayersMultiactive( array($player_id), ...

=== Red banner "Uncaught EvalError: Possible side-effect in debug-evaluate" ===

This is a known issue that can be ignored (for most of case). Generally happening when working on devtool.
A workaround is to disable the "error" event listener. To do so, you can temporarily disable the event listener in DevTools, like this:

- At the top of DevTools, open the "Elements" tab
- Press "»", on the right of "Styles", "Computed", "Layout"
- Choose "Event listeners"
- Find and expand "error"
- Click "Remove"

This will remove the event listener, but the issue will return after you refresh the page.

[[Category:Studio]]

Game replay

2023-11-15T10:42:32Z

Archduke:

{{Studio_Framework_Navigation}}

Game replay is managed by the framework. You do not need to do anything special about it in your code, except taking care of updating the client interface through the framework notification system (and not for example, by using the callback function of an ajaxcall).

The game replay works like this:
* The static files for the game at the time of the game start are archived
* All notifications sent to the browser are added to the archive
* When replaying, the static files are loaded in the browser, then notifications are sent back to replay the game moves.

So in essence, the replay works like an exact recording.

NB: the game replay feature is now available on the studio (since December 2020). Please note that there may be a delay before the replay becomes available.

=== Preview Videos ===
Example games are periodically selected from which videos are generated to show off the game on the game panel.

Wingspan: https://x.boardgamearena.net/data/gamepreviews/1635/en-w640.webm

=== Hiding UI elements from preview video ===

Some games have pop-up modals which are displayed in some cases, these should be hidden for the replay video so you can show off the gameplay right from the game page!

[[File:Mycity-with-modal.png|500px]]

Previews are generated with a query variable set <code>target=video</code>. You can check for this query param in the following way:

const searchParams = new URLSearchParams(window.location.search);
if (searchParams) {
const target = searchParams.get('target');
if (target === "video") {
// Hide modal popups...
}
}

[[Category:Studio]]

File:Mycity-with-modal.png

2023-11-15T10:39:59Z

Archduke:

Preview video with obstructing modal

Compatibility

2023-11-14T08:48:19Z

Archduke:

{{Studio_Framework_Navigation}}

The mainsite is built with compatibility for several old browsers.

We use a [https://browsersl.ist/#q=last+2+versions%2C+not+dead%2C+%3E+0.2%25 browserslist] config to define the targeted browsers: <code>last 2 versions, not dead, > 0.2%, safari >= 11</code>.

There are currently no hard rules about what you should target, but it is recommended to follow the same targets as the mainsite. You can use [https://babeljs.io/ babel] to compile your modern JavaScript code into backwards compatible code. Babel accepts a browserslist targets string, so you can use the targets above.

== Current list ==

As of November 2023, <code>last 2 versions, not dead, > 0.2%, safari >= 11</code> corresponds to:

* and_chr 113
* and_ff 113
* and_qq 13.1
* and_uc 13.4
* android 113
* android 4.4.3-4.4.4
* chrome 113
* chrome 112
* chrome 111
* chrome 110
* chrome 109
* chrome 108
* chrome 103
* chrome 79
* edge 113
* edge 112
* edge 111
* firefox 113
* firefox 112
* firefox 111
* ios_saf 16.4
* ios_saf 16.3
* ios_saf 16.2
* ios_saf 16.1
* ios_saf 16.0
* ios_saf 15.6
* ios_saf 15.5
* ios_saf 14.5-14.8
* ios_saf 14.0-14.4
* ios_saf 12.2-12.5
* kaios 3.0-3.1
* kaios 2.5
* op_mini all
* op_mob 73
* opera 98
* opera 97
* opera 96
* safari 16.4
* safari 16.3
* safari 16.2
* safari 16.1
* safari 16.0
* safari 15.6
* safari 15.5
* safari 15.4
* safari 15.2-15.3
* safari 15.1
* safari 15
* safari 14.1
* safari 14
* safari 13.1
* safari 13
* safari 12.1
* safari 12
* safari 11.1
* safari 11
* samsung 20
* samsung 19.0

[[Category:Studio]]

Template:Studio Framework Navigation

2023-11-13T16:25:28Z

Archduke:

<div class="studio-framework-navigation" style="float: right; width: 300px; border: solid #000 1px; padding: 1em; margin-left: 1em; background: #fff;">

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game File Reference'''</center></div>

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''[[Studio file reference|Overview]]'''</center></div>

* [[Game database model: dbmodel.sql|<b>dbmodel.sql</b>]] - database model
* [[Game meta-information: gameinfos.inc.php|<b>gameinfos.inc.php</b>]] - meta-information
* [[Options and preferences: gameoptions.json, gamepreferences.json|<b>gameoptions.json</b>]] - game options & user preferences
* [[Game art: img directory|<b>img/</b>]] - game art
* [[Game_metadata_manager|<b>Game Metadata Manager</b>]] - tags and metadata media
* [[Game material description: material.inc.php|<b>material.inc.php</b>]] - static data
* <b>misc/</b> - studio-only storage
* <b>modules/</b> - additional game code
* [[Your game state machine: states.inc.php|<b>states.inc.php</b>]] - state machine
* [[Game statistics: stats.inc.php|<b>stats.inc.php</b>]] - statistics
* [[Players actions: yourgamename.action.php|X.<b>action.php</b>]] - player actions
* [[Game interface stylesheet: yourgamename.css|X<b>.css</b>]] - interface stylesheet
* [[Main game logic: yourgamename.game.php|X.<b>game.php</b>]] - main logic
* [[Game interface logic: yourgamename.js|X.<b>js</b>]] - interface logic
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X.<b>view.php</b>]] - dynamic game layout
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X_X.<b>tpl</b>]] - static game layout
<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Useful Components'''</center></div>

'''Official'''

* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
* [[Draggable]]: a JS component to manage drag'n'drop actions.
* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.
* [[Zone]]: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).

Undocumented component (if somebody knows please help with docs)
* [[Wrapper]]: a JS component to wrap a <div> element around its child, even if these elements are absolute positioned.

'''Unofficial'''

* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks
* [[Some usual board game elements image ressources]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game Development Process'''</center></div>

* [[First steps with BGA Studio]]
* [[Create a game in BGA Studio: Complete Walkthrough]]
* [[Tutorial reversi]]
* [[Tutorial gomoku]]
* [[Tutorial hearts]]
* [[BGA Studio Guidelines]]
* [[BGA game Lifecycle]]
* [[Pre-release checklist]]
* [[Post-release phase]]
* [[Help|Player Resources]] - add player help/rules to your game page

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Guides for Common Topics'''</center></div>

* [[Translations]] - make your game translatable
* [[Game replay|Game Replay]]
* [[Your game mobile version|Mobile Users]]
* [[3D]]
* [[Compatibility]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Miscellaneous Resources'''</center></div>

* [[Studio FAQ]]
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment
* [[Studio logs]] - Instructions for log access
* [[Practical debugging]] - Tips focused on debugging
* [[Troubleshooting]] - Most common "I am really stuck" situations
* [https://studio.boardgamearena.com/bugs Studio Bugs] - Reports against Studio itself (not BGA!)
</div>

Your game state machine: states.inc.php

2023-10-04T08:57:12Z

Archduke: /* Private parallel states */

{{Studio_Framework_Navigation}}

This file describes the state machine of your game (all the game states properties, and the transitions to get from one state to another).

Important: to understand the game state machine, it's recommended that you read this presentation first:

[http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine]

== Overall structure ==

The machine states are described by a PHP associative array.

Example:

<pre>
$machinestates = array(

// The initial state. Please do not modify.
1 => array(
"name" => "gameSetup",
"description" => clienttranslate("Game setup"),
"type" => "manager",
"action" => "stGameSetup",
"transitions" => array( "" => 2 )
),

// Note: ID=2 => your first state

2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a card or pass'),
"descriptionmyturn" => clienttranslate('${you} must play a card or pass'),
"type" => "activeplayer",
"possibleactions" => array( "playCard", "pass" ),
"transitions" => array( "playCard" => 2, "pass" => 2 )
),
</pre>

== Syntax ==

=== id ===

The keys determine game state IDs (in the example above: 1 and 2).

IDs must be positive integers.

ID=1 is reserved for the first game state and should not be used (and you must not modify it).

ID=99 is reserved for the last game state (end of the game) (and you must not modify it).

Note: you may use any ID, even an ID greater than 100. But you cannot use 1 or 99.

Note²: You must not use the same ID twice.

Note³: When a game is in prod and you change the ID of a state, all active games (including many turn based) will behave unpredictably.

=== name ===

('''Mandatory''')

The name of a game state is used to identify it in your game logic.

Several game states can share the same name; however, this is not recommended.

Warning! Do not put spaces in the name. This could cause unexpected problems in some cases.

PHP example:
<pre>

// Get current game state
$state = $this->gamestate->state();
if( $state['name'] == 'myGameState' )
{
...
}

</pre>

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

switch( stateName )
case 'myGameState':

// Do some stuff at the beginning at this game state
....

break;
</pre>

=== type ===

('''Mandatory''')

You can use 3 types of game states:
* activeplayer (1 player is active and must play.)
* multipleactiveplayer (1..N players can be active and must play.)
* private (during multiactive states players can independently move to different private parallel states. See more details [[#Private_parallel_states|here]].
* game (No player is active. This is a transitional state to do something automatic specified by the game rules.)

'''Note:''' Make sure you don't mistype the value of this attribute. If you do (e.g. 'multiactiveplayer' instead of 'multipleactiveplayer'), things won't work, and you might have a hard time figuring out why.

=== description ===

('''Mandatory''')

The description is the string that is displayed in the main action bar (top of the screen) when the state is active.

When a string is specified as a description, you must use "clienttranslate" in order for the string to be translated on the client side:

<pre>
"description" => clienttranslate('${actplayer} must play a card or pass'),
</pre>

In the description string, you can use ${actplayer} to refer to the active player.

You can also use custom arguments in your description. These custom arguments correspond to values returned by your "args" PHP method (see below "args" field).

Example of custom field:
<pre>

In states.inc.php:
"description" => clienttranslate('${actplayer} must choose ${nbr} identical energies'),
"args" => "argMyArgumentMethod"

In mygame.game.php:
function argMyArgumentMethod()
{
return array(
'nbr' => 2 // In this case ${nbr} in the description will be replaced by "2"
);
}
</pre>

Note: You may specify an empty string ("") here if it never happens that the game remains in this state (i.e., if this state immediately jumps to another state when activated).

Note²: Usually, you specify a string for "activeplayer" and "multipleactiveplayer" game states, and you specify an empty string for "game" game states. BUT, if you are using synchronous notifications, the client can remain on a "game" type game state for a few seconds, and in this case it may be useful to display a description in the status bar while in this state.

=== descriptionmyturn ===

('''Mandatory''' when the state type is "activeplayer" or "multipleactiveplayer")

"descriptionmyturn" has exactly the same role and properties as "description", except that this value is displayed to the current active player - or to all active players in case of a multipleactiveplayer game state.

In general, we have this situation:

<pre>
"description" => clienttranslate('${actplayer} can take some actions'),
"descriptionmyturn" => clienttranslate('${you} can take some actions'),
</pre>

Note: you can use ${you} in descriptionmyturn so the description will display "You" instead of the name of the player.

Note 2: you can use ${otherplayer} to refer to some other player if you want this to be shown in player's color, but you must provide otherplayer_id as argument (along with otherplayer) to specify this player's id in this case or game won't load.

I.e.

"descriptionmyturn" => clienttranslate('${you} can follow action of ${otherplayer}'),

And this will have to be state arguments for this
<pre>
function arg_playerTurnFollow(){
return ['otherplayer'=> $this->getLeaderPlayerName(),
'otherplayer_id'=> $this->getLeaderPlayerId()
];
}
</pre>

=== action ===

('''Mandatory''' when the state type is "game.")

"action" specifies a PHP method to call when entering this game state.

Example:
In states.inc.php:
<pre>
28 => array(
"name" => "gameTurnNextPlayer",
"description" => clienttranslate('Updating some stuff...'),
"type" => "game",
"action" => "st_gameTurnNextPlayer",
</pre>
In mygame.game.php:
<pre>
function st_gameTurnNextPlayer() {
$player_id = $this->getActivePlayerId();
$next_player_id = $this->getPlayerAfter($player_id);
$this->giveExtraTime($next_player_id);
$this->incStat(1, 'turns_number', $next_player_id);
$this->incStat(1, 'turns_number');
$this->gamestate->changeActivePlayer($next_player_id);
$this->gamestate->nextState('next');
}
</pre>

Usually, for a "game" state type, the action method is used to perform automatic functions specified by the rules (for example: check victory conditions, deal cards for a new round, go to the next player, etc.) and then jump to another game state.

Note: a BGA convention specifies that PHP methods called with "action" are prefixed by "st".

Note: this field CAN be used for player states to set something up; e.g., for multiplayer states, it can make all players active.

Example for action in player state:
in states.inc.php:
<pre>
2 => array(
"name" => "playerTurnPlace",
"description" => clienttranslate('Other player must place ships'),
"descriptionmyturn" => clienttranslate('${you} must place ships (click on YOUR SHIPS board to place)'),
"type" => "multipleactiveplayer",
'action' => 'st_MultiPlayerInit',
'args' => 'arg_playerTurnPlace',
"possibleactions" => array( "playPlace" ),
"transitions" => array( "next" => 4, "last" => 99)
),
</pre>
in mygame.game.php:
<pre>
function st_MultiPlayerInit() {
$this->gamestate->setAllPlayersMultiactive();
}
</pre>

=== transitions ===

('''Mandatory''')

With "transitions" you specify which game state(s) you can jump to from a given game state.

Example:
<pre>
25 => array(
"name" => "myGameState",
"transitions" => array( "nextPlayer" => 27, "endRound" => 39 ),
....
}
</pre>

In the example above, if "myGameState" is the current active game state, I can jump to the game state with ID 27 or the game state with ID 39.

Example to jump to ID 27:
<pre>
In mygame.game.php:
$this->gamestate->nextState( "nextPlayer" );
</pre>

Important: "nextPlayer" is the name of the transition, and NOT the name of the target game state. Multiple transitions can lead to the same game state.

Note: If there is only 1 transition, you may give it an empty name.

Example:
<pre>
In states.inc.php:
"transitions" => array( "" => 27 ),

In mygame.game.php:
$this->gamestate->nextState( ); // We don't need to specify a transition as there is only one here
</pre>

=== possibleactions ===

('''Mandatory''' when the game state is "activeplayer" or "multipleactiveplayer")

"possibleactions" defines the actions possible by the players in this game state, and ensures they cannot perform actions that are not allowed in this state.

Example:

<pre>
In states.game.php:
"possibleactions" => array( "playCard", "pass" ),

In mygame.game.php:
function playCard( ...)
{
self::checkAction( "playCard" ); // Will fail if "playCard" is not specified in "possibleactions" in the current game state.

....

In mygame.js:
playCard: function( ... )
{
if( this.checkAction( "playCard" ) ) // Will fail if "playCard" is not specified in "possibleactions" in the current game state.
{ return ; }

....

</pre>

=== args ===

(optional)

Sometimes it happens that you need some information on the client side (i.e., for your game interface) only for a specific game state.

Example 1: in ''Reversi'', the list of possible moves during the playerTurn state.

Example 2: in ''Caylus'', the number of remaining king's favors to choose in the state where the player is choosing a favor.

Example 3: in ''Can't Stop'', the list of possible die combinations to be displayed to the active player so that he can choose from among them.

In such a situation, you can specify a method name as the « args » argument for your game state. This method must retrieve some piece of information about the game (example: for ''Reversi'', the list of possible moves) and return it.

Thus, this data can be transmitted to the clients and used by the clients to display it. It should always be an associative array.

Let's see a complete example using args with ''Reversi'' game:

In states.inc.php, we specify an '''args''' argument for gamestate '''playerTurn''':
<pre>
10 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a disc'),
"descriptionmyturn" => clienttranslate('${you} must play a disc'),
"type" => "activeplayer",
"args" => "argPlayerTurn", // <==== HERE
"possibleactions" => array( 'playDisc' ),
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )
),
</pre>

It corresponds to a '''argPlayerTurn''' method in our PHP code (reversi.game.php):
<pre>
function argPlayerTurn() {
return array(
'possibleMoves' => self::getPossibleMoves()
);
}
</pre>

Then, when we enter into the '''playerTurn''' game state on the client side, we can highlight the possible moves on the board using information returned by '''argPlayerTurn''':

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

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

==== Naming and API conventions ====

As a BGA convention, PHP methods called with "args" are prefixed by "arg" followed by state name (example: '''argPlayerTurn''').

All "arg*" methods are put into corresponding section of .game.php file commented as
//////////// Game state arguments

Arg method MUST return array. Return integer or string will result in some undebuggable exceptions.

Arg method MUST be defined in php if it is declared in state description, if you don't need it comment it out from the states.inc.php file (the '''args''' parameter). If you not sure if you need it or not you can keep it returning empty array until you figure it out.

function argPlayerTurn() {
return array(); // must be an array
}

'''Warning''': the "args" method can be called before the "action" method so don't expect data modifications by the "action" method to be available in the "args" method!
Also don't modify database in this method!

You should NOT be calling getCurrentPlayer() in the context of this function, since state transitions are broadcasted to all player independent of who initiated it. Instead you should send information on per player basis (Note: if this is private info see section below).

If you using this function in multi-player state, you should not call getActivePlayer() either, you should send per player info:

function arg_playerTurn() {
$res = array ();
$players = $this->loadPlayersBasicInfos();
foreach ( $players as $player_id => $player_info ) {
$color = $player_info ['player_color'];
$res [$player_id] = array("color"=>$color);
}
return $res;
}

Note: you never need to send player color like this, this is just an example.

Note 2: you CAN call methods that return all active players if multi-player states if its relevant.

==== Other usages ====

You can use values returned by your "args" method to have some custom values in your "description"/"descriptionmyturn", i.e. in states.inc.php:

"descriptionmyturn" => clienttranslate('${you} must play ${color} disc'),

So arg function will be something like:

function argPlayerTurn() {
return array('color'=>$this->getActivePlayerColor());
}

You can use args also in '''onUpdateActionButtons''' function on js side, however two important notes:
* it is just '''args''' (not args.args like in '''onEnteringState''')
* it is args of the current state, which may not be state you think it will be! This method is called during change of active player, which happens in some weird place especially during "multipleactiveplayer" states. If you pulling your hair thinking why its "undefined" on js side - check the current state.

==== Private info in args ====

By default, all data provided through this method are PUBLIC TO ALL PLAYERS. Please do not send any private data with this method, as a cheater could see it even it is not used explicitly by the game interface logic.

However, it is possible to specify that some data should be sent to specific players only.

'''Note: You cannot use Example 1 and Example 2 together. If you have to send private args to multiple players, use Example 2.'''

Example 1: send information to active player(s) only:

<pre>
function argPlayerTurn() {
return array(
'_private' => array( // Using "_private" keyword, all data inside this array will be made private
'active' => array( // Using "active" keyword inside "_private", you select active player(s)
'somePrivateData' => self::getSomePrivateData() // will be send only to active player(s)
)
),
'possibleMoves' => self::getPossibleMoves() // will be sent to all players
);
}
</pre>

Inside the js file, these variables will be available through `args.args._private`. (e.g. `args.args._private.somePrivateData` -- it is not `args._private.active.somePrivateData` nor is it `args.somePrivateData`)

Example 2: send information to a specific player (<specific_player_id>) only:

<pre>
function argPlayerTurn() {
$specific_player_id = ...; // calculate some-how
return array(
'_private' => array( // all data inside this array will be private
$specific_player_id => array( // will be sent only to that player
'somePrivateData' => self::getSomePrivateData()
)
),

'possibleMoves' => self::getPossibleMoves() // will be sent to all players
);
}
</pre>

IMPORTANT: in certain situations (i.e. "multipleactiveplayer" game state) these "private data" features can have a significant impact on performance. Please do not use if not needed.

It is also possible to use these private args in the "description" messages, like "${you} have to play ${_private.count} cards".

==== Translations in args ====
You can do the same as in notification by adding i18n parameter, i.e
<pre>
function argPlayerTurn() {
return [
'i18n' => ['terrainName' ],
'terrainName' => ($this->token_types[$terrain]['name']), // this should be defined in material.inc.php and with clienttranslate
'terrain' => $terrain,
];
}
</pre>

Than you can do something like this in state:
"descriptionmyturn" => clienttranslate('${you} must place a house on ${terrainName}'),

See more in [[Translations]]

=== updateGameProgression ===

(optional)

If you specify "updateGameProgression => true" in a game state, your "getGameProgression" PHP method will be called at the beginning of this game state - and thus the game progression of the game will be updated.

''At least one'' of your game states (any one) must specify "updateGameProgression=>true".

=== initialprivate ===

(optional)

This parameter will enable private parallel states in a multiplayer state. Parameter should be set to first private parallel state a player will be transitioned to.
See more details about Private parallel states [[#Private_parallel_states|here]].

== Implementation Notes ==

=== Private parallel states ===

Private parallel states are useful when multiple players are active and their turn is very complex. In that case it is possible with parallel states for each player to be in a independent state.

Lets say that players need to do three complex action one after another in multiactive state. With parallel states each player can independently be in a different state (i.e. one player still need to decide about first action while some players are deciding their second action and the fastest player is already on their third action. Normally this can be handled with two simple, but limited, approaches:

* Moving all players to different states together - this is limiting for faster players as they need to wait other players for each separate action. The more problematic thing is that it would be hard to implement an undo feature when one player wants to change their previous action. In that case all players should be moved back to previous state which will interrupt their flow.
* Using client states, by changing the state in which the player is in javascript - the problem with this approach is that players will lose their progress on browser refresh (F5). Furthermore the validation logic of specific actions should be implemented on both server side and client side and we cannot have specific args for each different action, but they should be calculated only at the beginning of the first action and possibly calculated on client side after each action, which again duplicates logic on client and server.

With private parallel states, each specific action can be implemented as a parallel state. Parallel states are defined with the type 'private' and players are moved to those private states during one master multiactive state. Lets look at the example:

<pre>
10 => [
"name" => "playerTurn",
"description" => clienttranslate('Waiting for other players to end their turn.'),
"descriptionmyturn" => clienttranslate('${you} must do your turn'), // Won't be displayed anyway since each private state has its own description
"type" => "multipleactiveplayer",
"initialprivate" => 50, // This makes this state a master multiactive state and enables private states, this is also a first private state
"action" => "stPlayerTurn",
"args" => "argPlayerTurn",
"possibleactions" => ["changeMind"], //this action is possible if player is not in any private state which usually happens when they are inactive
"transitions" => ["playersDecide" => 11] // this is normal next transition which will happen after all players finish their turns
],

50 => [
"name" => "chooseFirst",
"descriptionmyturn" => clienttranslate('${you} must make your first choice'), // just this parameter is needed. description is not needed as no player is inactive in this state
"type" => "private", // this state is reachable only as a private state
"args" => "argChooseFirst", //this method will be called with playerId as a parametar and is used to calculate arguments for this action for specific player
"action" => "stChooseFirst", // this method will be called with playerId as a parameter and can be used to make some changes when player enters this private state
"possibleactions" => ["toSecond"],
"transitions" => [
'chooseSecond' => 51, // transition to another private state
]
],

51 => [
"name" => "chooseSecond",
"descriptionmyturn" => clienttranslate('${you} must make your second choice'),
"type" => "private",
"args" => "argChooseSecond",
"possibleactions" => ["finish", "back"],
"transitions" => [
'back' => 50,
]
],
</pre>

When entering the master state it is usually useful to set some players as multiactive and initialize their private state:

<pre>
function stPlayerTurn() {
$this->gamestate->setAllPlayersMultiactive();

//this is needed when starting private parallel states; players will be transitioned to initialprivate state defined in master state
$this->gamestate->initializePrivateStateForAllActivePlayers();

// in some cases you can move immediately some or all players to different private states
if ($someCondition) {
//move all players to different state
$this->gamestate->nextPrivateStateForAllActivePlayers("chooseSecond");
return;
}

if ($other condition) {
//move single player to different state
$this->gamestate->nextPrivateState($specificPlayerId, "chooseSecond");
return;
}
}
</pre>

When some action is done by a player, you can move them to the next private state:

<pre>
function toSecond() {
$this->checkAction("toSecond"); //the action must be defined in private state; actions defined in master state are not possible
$this->gamestate->nextPrivateState($this->getCurrentPlayerId(), "chooseSecond"); //moving current player to different state
}
</pre>

Please check the detailed API [[Main_game_logic:_yourgamename.game.php#Private_parallel_states|here]].

=== Client States ===
Client state almost have nothing to do with server states, except they can simulate same experience without actually changing server states.

See description here: https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Client_States

In many cases you can achive similar results by using client states vs private server states. The only caviat - when using client states during multiactive server state
other player will trigger state changes (multiactive player set) which will call onUpdateActionButtons. Some measures have to be taken to preserve client state in this case.

=== Using Named Constants for States ===

Using numeric constants is prone to errors. If you want you can declare state constants as PHP named constants. This way you can
use them in the states file and in game.php as well

EXAMPLE:

states.inc.php:

<pre>
// define contants for state ids
if (!defined('STATE_END_GAME')) { // ensure this block is only invoked once, since it is included multiple times
define("STATE_PLAYER_TURN", 2);
define("STATE_GAME_TURN", 3);
define("STATE_PLAYER_TURN_CUBES", 4);
define("STATE_END_GAME", 99);
}

$machinestates = array(

...

STATE_PLAYER_TURN => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must select an Action Space or Pass'),
"descriptionmyturn" => clienttranslate('${you} must select an Action Space or Pass'),
"type" => "activeplayer",
"args" => 'arg_playerTurn',
"possibleactions" => array( "selectWorkerAction", "pass" ),
"transitions" => array(
"loopback" => STATE_PLAYER_TURN,
"playCubes" => STATE_PLAYER_TURN_CUBES,
"pass" => STATE_GAME_TURN )
),
</pre>

=== Example of multipleactiveplayer state ===

This is an example of a multipleactiveplayer state:

2 => array (
'name' => 'playerTurnSetup',
'type' => 'multipleactiveplayer',
'description' => clienttranslate('Other players must choose one Objective'),
'descriptionmyturn' => clienttranslate('${you} must choose one Objective card to keep'),
'possibleactions' => array ('playKeep' ),
'transitions' => array ( 'next' => 5, 'loopback' => 2, ),
'action' => 'st_MultiPlayerInit',
'args' => 'arg_playerTurnSetup',
),

In game.php:
// this will make all players multiactive just before entering the state
function st_MultiPlayerInit() {
$this->gamestate->setAllPlayersMultiactive();
}

Note: if you want exact this function its already defined in table class its called 'stMakeEveryoneActive'

When ending the player action, instead of a state transition, deactivate player.

function action_playKeep($cardId) {
$this->checkAction('playKeep');
$player_id = $this->getCurrentPlayerId(); // CURRENT!!! not active
... // some logic here
$this->gamestate->setPlayerNonMultiactive($player_id, 'next'); // deactivate player; if none left, transition to 'next' state
}

=== Difference between Single active and Multi active states ===
In a classic "activePlayer" state:

* You cannot change the active player DURING the state. This is to ensure that during 1 activePlayer state, only ONE player is active
* As a consequence, you must set the active player BEFORE entering the activePlayer state
* In such states on JS side onUpdateActionButtons is called before onEnteringState during game play (but after during reload, i.e. F5)
* Finally, during onEnteringState, on JS side, the active player is signaled as active and the information is reliable and usable.

In a "multiplePlayer" state:

* You can (and must) change the active players DURING the state
* During such a state, players can be activated/desactivated anytime during the state, giving you the maximum of possibilities.
* You shouldn't set active player before entering the state. But you can set it in "state initializer" php function (see example above st_MultiPlayerInit)
* Finally, during onEnteringState, on JS side, the active players are NOT active yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/inactive status.

Note: in some off cases other players can perform special actions even if they are not active, see example https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Out-of-turn_actions%3A_Un-pass. Do not abuse this technique!

=== Designing states ===

As a general rule you state machine should resemble "round/turn overview" from the game rule-book. Normally if book say its player turn and player can do multiple things during their turn it is still only
one player state (plus a game to switch player), not muliple states.

In a classic game (i.e. chess), there is only active player at any time, so it is simple playerTurn/gameTurn sequence and you only need 2 states.

[[File:Simplestates.png]]

In complex euro game there can be multiple rounds, and each round have phases which can be distinctly unique, i.e. in first phase everybody draws card and discard (multi-player), then player have one turn each (single-active), then another is resolution of actions from players and some of them may become active again, then there is round upkeep/reset. This would require one multi-player state for phase 1, pair of states for phase2 (singel-active + game), pair of states for phase3 and finally round-end/unkeep game state.

For pair of active player/game states you can make player state first, which transitions to game state, or the other way around, you start with game state which transition to active player state, its loop in any case but depends on how you want to do "phase" initiazations.

[[File:Eurogamestates.png]]

=== Complete examples ===

Example of simple game where player take turns

<pre>
if ( !defined('STATE_END_GAME')) { // guard since this included multiple times
define("STATE_PLAYER_TURN", 2);
define("STATE_GAME_TURN_NEXT_PLAYER", 3);
define("STATE_PLAYER_GAME_END", 4);
define("STATE_END_GAME", 99);
}

$machinestates = [
1 => [ // The initial state. Please do not modify.
"name" => "gameSetup",
"description" => "",
"type" => "manager",
"action" => "stGameSetup",
"transitions" => [ "" => STATE_PLAYER_TURN ] ],
// Game states
STATE_PLAYER_TURN => [ // main active player state
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must do something or pass'),
"descriptionmyturn" => clienttranslate('${you} must do something or pass'),
"type" => "activeplayer",
"args" => "arg_playerTurn",
"possibleactions" => [ "dosomething","pass" ],
"transitions" => [ "next" => STATE_GAME_TURN_NEXT_PLAYER,"last" => STATE_PLAYER_GAME_END ] //
],
STATE_GAME_TURN_NEXT_PLAYER => [ // next player state
"name" => "gameTurnNextPlayer",
"description" => clienttranslate('Upkeep...'),
"type" => "game", //
"action" => "st_gameTurnNextPlayer", //
"updateGameProgression" => true,
"transitions" => [ "next" => STATE_PLAYER_TURN,"loopback" => STATE_GAME_TURN_NEXT_PLAYER,
"last" => STATE_PLAYER_GAME_END ], // TODO replace with STATE_END_GAME, its there to use undo/restore during dev
],

STATE_PLAYER_GAME_END => [ // active player state for debugging end of game
"name" => "playerGameEnd",
"description" => clienttranslate('${actplayer} Game Over'),
"descriptionmyturn" => clienttranslate('${you} Game Over'),
"type" => "activeplayer",
"args" => "arg_playerTurn",
"possibleactions" => ["endGame"],
"transitions" => ["next" => STATE_END_GAME,"loopback" => STATE_PLAYER_GAME_END ] //
],
// End of Game states
// Final state.
// Please do not modify (and do not overload action/args methods).
STATE_END_GAME => [
"name" => "gameEnd",
"description" => clienttranslate("End of game"),"type" => "manager",
"action" => "stGameEnd",
"args" => "argGameEnd" ]

];

</pre>

[[Category:Studio]]

BGA Studio Guidelines

2023-09-13T13:17:39Z

Archduke: /* IV-8 Namespace recommendations */

{{Studio_Framework_Navigation}}

= BGA Studio Guidelines =

Originally From: https://www.slideshare.net/boardgamearena/bga-studio-guidelines

== Why guidelines? ==
More and more game publishers are choosing Board Game Arena for their game adaptations because the quality of these adaptations is high.
If we want to continue to have nice games in the future, we have to make sure that every game published in the BGA platform is matching the quality standards of BGA.
These guidelines are here to help you to make your game easy to use by BGA players, and to make sure its going to be validated by the game publisher.

== General guidelines ==
The 3 main important guidelines
* If a player knows the real board game, they should be able to play your adaptation with no learning.
* Fidelity to the original game is an absolute requirement.
* Don't try to create a video game: make your game interface as close as possible to how the original board game looks like.

== Game layout ==
=== I-1 Don't hide game elements ===

Many board games have a lot of material to display, and computer screens are sometimes too small.
But you are lucky: your game will be on a webpage with a scrolling functionality.
Basically, you always have some more space available .
Don't hide game elements behind menus, submenus, dialogs, etc, but display them directly on the main page.

Tips: eventually, you can use HTML anchor link to jump between the different elements of the page if the page height is very big.

Examples:

In Amyitis, characters cards are elements you don't have to check all the time. Thus, we placed them at the bottom of the page and you have to scroll to see them.

In Madeira, additional game board are shown at the bottom, but when player needs to use it it moved up.

Rule:
* If real game has visible elements on the table it should be visible on the main screen or user mini boards on the right

Exceptions:
* Showing counts of same elements is sufficient
* For decks which can be inspected it permitted to show them on demand
* If some games you can cut off score track and replace with BGA scoring (stars), but keeping it will look nicer (but you have to keep track of score on it as well)
* Its not necessary to show helper cards such as turn overview or scoring overview. It is nice if you can incorporate that as well, but in most cases, '''such elements should not be displayed by default''' (as space should be given in priority to the game itself), and should be made available by '''a gray "Player aid" button (or help icon)''' displaying a popup when clicked, like for example in Marco Polo or Terra Mystica.

=== I-2 Make it fluid ===

BGA game interface is «fluid». It means the interface width can vary in order to use extra space on the screen when available.
HTML and CSS give us a lot of possibilities to adapt a web content to a given browser width.
You have to use HTML and CSS:
* To allow players owning a big screen to enjoy the game comfortably without scrolling the page.
* To allow players with a screen of just 1024px

Tips: for each element of the game, answer this question « how many times during a game do I need to check/use this element? ».Less frequently used elements can be placed below.
You can listen on display resize in JS to do more sophisticated layouts.

Examples:

Caylus: when we have a 1024px small width to play the game – even if they have to screen, available buildings are placed scroll on the the right and below the board.
On larger screen, these tiles are placed on the right of the board. This is a very basic usage of the others. « float:left » CSS property.

=== I-3 Use whiteblocks ===
White blocks are '''div''' HTML element with the '''whiteblock''' class (white and transparent background). This is the recommended way to gather game elements together in your game interface when they are not directly on a board. Whiteblocks helps you to organize the space in order it can be easily understood by players.

If game contains individual player boards with distinct colors or marking you don't need these boards inside the whiteblock.

''Tips: you can use a '''h3''' title inside the whiteblock to help players to understand what is inside or to who it belongs.''

In The Year of the Dragon game interface, with whiteblocks and h3 titles /picture here/

=== I-4 Use player panels ===

BGA players are used to look at player panels when they need an information about a player.
Using player panels can allow you to save a lot of space on the main game space. In general, the following information is placed in the player panel:
* Players resources (i.e. small game elements the player is keeping in front of him in the real game).
* Summary information about player (i.e. number of cards in hand, number of cards played...).
* « First player » token.
* Score.

Player panels in Seasons. /picture/ A lot of useful information can fit into these small spaces :)

Note: for all games, you must always use the standard BGA score counter (with the star). Players are used to check this counter to see who is winning the game.

=== I-5 Use status bar actions ===

When some game action is particular to a specific game state, the good practice is to use a status bar action (HTML link).
Don't try to place some icon in your main gameinterface that will be useless 95% of the time: it takes space and makes the interface more complex to understand.

Status bar actions in Tobago /picture/

== Game usability ==

=== II-1 Use tooltips ===

With BGA Studio its very easy to associate a tooltip on any element of the game. Each time this is possible: add a tooltip to explain to the players:
* What is this game element?
* What happens if I click on it?
However, tooltips should NOT be used to display dynamic information about the current game to save space on the game interface.
Typically, regular players should be able to play with no tooltips.
However you can display some dynamic stuff if it's available otherwise but just annoying to calculate. For example in Lewis and Clark author asked to put
tooltips of how many river space available ahead of explorer.
If you need to show user why they cannot interact with element show errors instead (when clicking on it).

Tips: you can place any HTML element in tooltips. So you can make them as rich and beautiful as you need :)

=== II-2 Use left click only ===
* The whole game should be playable with only simple left button mouse click.
* Context menus should not be used.
* Drag-n-drop should be avoided (if you want to use it anyway, you should make a click based alternative available).
* Mouse icon must change on clickable elements (« cursor:pointer » CSS property).

=== II-3 Make your interface intuitive ===
If your testers have different opinions about « how to trigger some game action », maybe
the best is to make several options possible for this game action. In the case there is a complex action to do by the player (ex: select some cards, then click on an action button), design your error messages in order they can guide the player(ex : « please select some cards first »).

''Tips: For complex games, it is simple and useful to highlight the area of the interface where player should focus his attention (using onEnteringState/onLeavingState and CSS class, i.e. 'active_slot').''

The Boss: when a player clicks on a card with no selected cubes, the interface tells us to select some cube first.

=== II-4 Use the gamelog ===
With BGA Studio it is very easy to place sometext (or HTML code) in the gamelog.
Don't hesitate to use the game log.
Players are not always in front of the game page when their opponents are making their moves.
In addition, the computer manipulates game elements faster than you usually do with the real board game and even regular players can get behind of what happened sometimes.
You should be able to understand the « game story » by reading the game log.

=== II-5 Tell players about automatic actions ===
Very often, during a game you are in a situation where:
* Only one action is possible for the activeplayer, or
* A series of action has to be done (according to the rules) without any players actions.
In these situation, you must or you may trigger these actions automatically.
In any case, you must make sure that players understand what is happening, otherwise they will probably report a bug.

Stone Age: people are fed automatically at the end of the turn, but players can always see what happened exactly in the gamelog.

* Use the game log to trace all actions performed automatically.
* Use synchronous notifications handlers to slow down the execution of automatic actions,so that players can understand what is happening.
=== II-6 Avoid move confirmations ===
As a rule of thumb, don't require move confirmation. Confirming a move slows down the user interface and thus, the game flow. You can allow a player to confirm a move if this is a very critical step in a game, and if it is possible to trigger an action by accident. If client interactions are very complex and allow cancellation, the final move can be confirmed with a "Done" button.

''Hawaii'': Ending a turn is a critical action that happens only 5 times per player in a game. In this case, it is acceptable (and a good idea) to have a confirmation dialog.

''Hive'': Each move has to be confirmed with click on the location because it is very easy to click by accident.

''Russian Railroads'': Each move involves multiple interactions and can contains dozens of subactions. When the player is done "planning" they presses a "Done" button to submit the move to the server.

''Race for the Galaxy'': There is a card that allows players to draw two cards and discard one card before the Development phase. This requires confirmation when the player selects a development card to discard, as they often means to build that development card instead.

=== II-7 Translatable interface ===
With BGA Studio its very easy to translate your game in any language, using BGA collaborative translation system. Check the FAQ and the example games to learn how to declare your strings so that every message in your code can be managed by the internationalization system.

Diams 100 % translated in Polish

=== II-8 Use interactive elements ===

Interactive elements are tiles, cubes or board areas user can click on to perform an action. The following guidance apply:
* If user click on interactive element either action happens or user get a error message. Try to process error message of client side and not send to server for simple errors, such as player is not active. Please be very specific why user cannot interact with element, i.e.
** This is not your turn
** You cannot build this building because you don't have enough resources
** To select this card you have to select resource first
If you cannot make errors for all elements at least tooltip should explaining when it interactive vs not

Rule: Every game element should give an explicit error message if clicked at the wrong moment rather than staying silent

Rule: When user can click on element during this turn it should be highlighted if possible (or non-active element de-highlighted in some way)

Hightlighting guidelines:
* Apply a class to all active/selectable element, i.e. class can be "selectable", "active_slot", "interactive"
* An CSS element with this class can have special rules, i.e
** outline (use outline, do not use "border" as this changes sizing)
** OR shadow/glow - use box-shadow or filter: drop-shadow for non-standard tokens
** recommended color - white, yellow or blue. Do not use red - this is indication of error rather than prompt for action
** change mouse cursor to action cursor, i.e. cursor: pointer

De-highlighting guidelines:
* Only use this strategy when there are less inactive element than active
* Apply a class to all non-interactive element, such as "non-interactive"
* In css set special rules
** opacity:0.7
** OR filter:contrast(0.6) or grayscale
* change cursor, i.e. cursor: not-allowed

Rule: If state prompt replaces the interaction with element but elements are visible its better to do both (i.e. can select a button OR they can move element on the board)
** Example: In Lewis & Clark game offers gain resources via buttons on state prompt, but user can also click on cubes in supply to do the same action

=== II-9 Animate moving elements ===
If real game have some elements moving during the game it should also animate in your adaptation
* User gets a resource - move a resource from main board to user mini board
* User buys a card - move card from main display to user board
* User draw a card which is revealed on the display - move card from deck to display, maybe add flippy animation to turn it face up (that requires 3d transformations - that is bonus)

It is also nice to animation points or coin collection from specific region of the board (even points collection is not normally visible).

Don't need to overdo animation - its not first player shooter

=== II-10 Slow down the end of game scoring ===

This is the climax of the game, building up suspense before revealing the winner... Don't make it too quick! :)

It's also very helpful if some end of game scoring animations can show where the points are gained, to help players understand (and trust) the scoring.

To achieve this, you can use synchronous notifications for each step of the scoring to slow down the process, and use this.displayScoring ([[Game_interface_logic:_yourgamename.js#Scoring_animated_display]]) to display a nice points animation in the color of the player over the element of the game granting points for this step of the scoring.

For a practical example of a game adaptation where scoring has been done with this idea in mind, you can check a game replay of Terra Mystica for the final scoring (this link will fast forward you right there: [https://boardgamearena.com/archive/replay/200901-1002/?table=112192856&player=84819187&comments=426;&goto=341 replay scoring])

== Original game representation ==
=== III-1 Use the original art===
The less you are modifying the original art of the game, the better.
Its important for publishers that a board game adaptation looks like the real board game. Sometimes it can be useful to modify some elements of the game to save some space on the screen – but try to avoid it.
Tips: if you have not enough space on the screen, reduce the size of the game elements.
Try to make sure they are recognizable for players who played regularly, and add a tooltip to help beginners to figure out what they are.
Gosu : the original cards are used, with tooltips.

=== III-2 Be careful about player assistance ===
As a rule of thumb, in order to respect the original board games, you should not introduce any player assistance feature.
An assistance must not be introduced if it directly helps the player to figure out if his move is good or bad.
An assistance may be introduced if it can help the player to figure out what moves are available.

Gygès: the assistance shows you available moves, but is not alerting you about stupid moves (like the upper left one).

Note: You can however do a single choice move for a player, i.e passing on a turn if there is nothing a user can do; It's quite annoying to wait on a player to pass, while it's the only action that they can do anyways.

=== III-3 Cancel a move ===
Most players want to have moves cancelled or undone. Use the following rules to implement it:
* If any information is revealed which was not known before the action is completed - You CANNOT cancel it.
* If this is the end of active player action - You CANNOT cancel it
* If during a player's turn multiple actions are required but don't violate the above two rules - You CAN cancel/undo it. i.e. A user picks cubes and drops on a building. Selecting the cubes and building - are two actions, so user should be able to cancel taking cube.
This can be implemented using client side states, so cancelling is easy by restoring last server state.

=== III-4 Available information ===
Every information visible by players in the real game should be accessible in the adaptation. Pay attention to some information like the number of cards in the opponents hand, or the number of remaining cards in the deck.
If it is explicitly forbidden to count cards in the discard pile, this information is not available.

== Game technical quality ==
=== IV-1 Don't use exotic stuff ===
BGA Studio provides a set of useful tools to build board games adaptations (i.e. card management, confirmation dialog, tooltips,…).
Use them, and don't use exotic libraries, plugins or tricks.
Why? Because BGA Framework will evolve in the future to provide new features to players, and it could make your game incompatible with the new version.
On the contrary, if you are using standard Haggis using BGA standard card stuff, you will enjoy these enhancements without any effort.
If you feel that you really need some exotic thing: don't hesitate to ask us.

=== IV-2 Make sure you can use what you use ===

In particular, do not build your game on top of a technical library without checking that licensing allows you (and BGA) to use it.
If you use a library, make sure first that its license is really open (MIT style). Otherwise, we may have to ask you to rework your code to use another library.
In general, please consider that it's always better to minimize dependencies, so if you can avoid using external libraries, all the better.

=== IV-3 Write in (simple) English ===
Some other person may have to look at your code, such as:
* We (the BGA team), who are here to help you if you need us.
* Some other BGA developer wanting to help you.
For all these reasons, your code must be written in English (variables, methods, comments...).
If English is not your mother tongue don't be afraid: the whole idea here is to be understood, not to write an essay :)

=== IV-4 Page refresh ===
A page refresh (F5) must allow players to reset the game interface to a stable state at any moment of the game.
BGA Studio framework allows you to do this with the « getAllDatas » PHP method and the « setup » Javascript method.
Note: this « refresh » feature is also quite useful during the development process:)

=== IV-5 Private information ===
A private game element must be visible only to the player owning it. It must not be visible by his opponents, by any means.
In particular:
* getAllDatas PHP method must not return any element that are hidden from current player, even if the Javascript « setup » method ignores them.
* you must not send via the « notifyAllPlayers » function some information that is hidden from one player (use « notifyPlayer » instead).

Hearts: each player is alerted about his new cards using notifyPlayer, and cards from the other players remains secret

=== IV-6 Game progression ===
Game progression should be as accurate as possible.
Of course, its not always easy (or even possible) to compute game progression, but a vague approximation is better than nothing.
Stone Age: there are 2 different end game conditions (building cards and civilization cards).
Both are taken into account to increase the accuracy of the game progression.

=== IV-7 Game statistics ===
Using BGA Studio you can define a set of statistics for your game. Statistics will be displayed at the end of the game, and help players to figure out why they win/lose a game,
and what they should improve. Try to choose interesting statistics that distinguish the different strategies for your game, in order it can help players to understand their game.

Seasons : statistics

=== IV-8 Namespace recommendations ===
Your game is not working in complete isolation, it's included in a page with a lot of elements around (header, footer, logs, chat, player panels, rankings...)

So you should pay attention to naming your DOM elements, CSS classes and PHP constants / classes in a way specific to your game in order to avoid namespace collisions (for example you use a selector for a "selected" class in your .js, and there is also an element of the framework outside of your game with a selected class).

It's recommended to have:
* a wrapper div around your game zone with an id specific to your game ('yourgamename_playzone' for example) and to use it in any xpath selector of your .js
* a prefix for example a trigram for your game that you append to all the css classes of your game ('yrg_selected' for example).
* a prefix or a namespace for your PHP constants or classes.

Even if everything is working fine today, otherwise your game may break in the future when the framework is updated.

You should not use any global variables (window scope) in your Javascript files. If you need something to be accessible globally, then you should use <code>window.gameui</code>. You could even make a <code>window.gameui.globals = {}</code> object to contain any global variables.

== Summary ==
These guidelines are here to help you to make sure that the players, the game publisher and the game author are going to enjoy your adaptation of the game. We created these guidelines based on our personal experience (which includes many mistakes along the way) implementing a lot of games on BGA platform. Don't hesitate to contact us if you feel uncomfortable with one of these guidelines in some particular context with your game: these guidelines are here to help and not to prevent you to do smart things, and have fun while programing your game ;)

[[Category:Studio]]

Logos for printing

2023-07-25T18:39:00Z

Archduke:

Board Game Arena logos for printing purposes.

For partnerships and events, you can find there the files and rules on how to use the BGA logo and it's assets.

For online logos and other assets, find them on this page : [[Logos]]

== Logo and lines ==

==== Presentation of the full vertical version ====
[[File:BGA logos.jpg|left|thumb|300x300px]]

For full-color prints/supports, the Board Game Arena logo is reproduced in four-color positive (BGA gradient) only.

For plain background colors matching any parts of the original gradient, the all-white version should be used.

For color composition, please refer to the corresponding page.

<div style="clear: both;"></div>

==== Protected Areas ====
[[File:Save space.jpg|left|thumb]]The Board Game Arena logo may be used within the protection zone.

The minimum space is represented by the height and width (shaft) of the bottom-left graphic element.

Exceptions: if the height/width of the protection zone is restricted, the minimum space can be reduced to half the height/width of the graphic element.

The full vertical version of the logo is the prefered one to be used for all needs (Print/Web/etc...).

<div style="clear: both;"></div>

==== Logo variations: ====
[[File:Exemple of both logos.jpg|left|thumb|Logo with a written baseline / Logo with a QR code included.]]
We offer 2 variations for simple logo display on boxes and rulebooks, the all-use logo print.

The horizontal one offers a text only version which you can change the baseline text, while the vertical one offers a QRcode space to display and to be scanned by users.

The choice is your, but you shouldn't display both of them in the same page/display space (different box sides or pages are ok)

<div style="clear: both;"></div>

== The different BGA logos ==
Depending on your display goals, there's different sizes and version of the logo you can use. Please refer to these informations whenever you want to promote your BGA version on your games, whether it's on the box, or in the rules (or anywhere else).

Having a BGA logo or QR code on your box, rules or anywhere helps players find informations about it online.

- Have it on your box sides to lead to your online version of the game directly, helping people try the game or play the tutorial to learn more about the game.

- Have it displayed on your rulebook so once users played it they can find more players to play online or to learn the game in another way.

Note that we provide a lot of informations on our pages about games, and that it's best for you to check if all languages / informations / packshots are up to date, so users would also find the latest informations about the game.

Don't hesitate to ask us if there's any issues.

== Printing a BGA logo on board game boxes ==
If your game is available (or soon to be) on Board Game Arena, you can use these files to add awareness and promotion about your game being playable on our plaform right from the shelves.

If your game is NOT already available on Board Game Arena, you can check this page or send us a message about how to make the best of both worlds (printed games and virtual ones).

Note that now that QR codes are quite common, it's better for you to use this specific version so users don't have to type anything to find your game online.

=== Box examples ===
Depending on your box size/ratio, there's a few options you can use to display the BGA logo as well as the QR codes which would lead directly to your game page.

==== The vertical box ====
[[File:Verticalbox example.jpg|left|thumb]]

Depending on the orientation of the box art and way it should be displayed on shelves, we recommend not to display the BGA logos/QR codes on the front face.

For the sides, you can use different display versions to fit your needs. We strongly recommend to use as little space as possible, and to have the long horizontal one on the tallest sides, while using the tallest ones on the horizontally-oriented spaces.

Bottom position/Right positions are prefered.

White background should be used on most cases, but you can use the variation to fit your box artwork.

Note that for boxes having a side of less than 3cm width, we don't recommend using the box sides but the box back.

<div style="clear: both;"></div>

==== The horizontal box ====
[[File:Horizontalboxexample.jpg|left|thumb]]Placement on horizontal-shaped boxes should be on right and bottom preferably, using our files.

<div style="clear: both;"></div>

== Generate a QR code for your game page on BGA: ==
In order to generate the right logo file and QR code, here is a few guidelines to help you do it effortlessly:
*Check twice your game page URL (Which should look like [https://boardgamearena.com/gamepanel?game=bunnykingdom https://boardgamearena.com/gamepanel?game=GAMENAME]) OR you can also ask for a tracked short url by contacting us.
*We use preferably QR codes generated from online websites (note that ADOBE offer this tool there https://express.adobe.com/fr-FR/tools/qr-code-generator, or this one https://www.the-qrcode-generator.com/ (entierely free) with the SIMPLE GRID eyes or rounded ones (eyes being the rounded shapes on the corners, see below for the screenshot example)[[File:QR code eyes.jpg|thumb|GRID EYES are styling option we would love to prefer, but you can use any QR code generator with regular rectangular shapes.]]Check twice about the offer you're using : some are paid and don't allow more than a few scan.
*Once generated, download an SVG version and remove the white parts so you can apply our gradient on your QR code, using Photoshop.
*'''You can download the QR code sample file for Photoshop (PSD) right here:''' https://drive.google.com/file/d/1TDkdqUVtAjsZqJ45LuTp0-zqytk5vPXp/view?usp=sharing
*Check with a phone that the code can be scanner (open camera app and point it to the QR code. If any links appears, click to check if it works properly.
*[[File:Alternative.jpg|thumb|Visuel de QR code carré utilisé comme alternative.]]Import to your printing files. File is provided as an example if you want to have an immediate recognition by users, but you can do any derivatives that would be a better fit for your brand if you feel the need to. WHITE Background is mandatory as it allows better scanning results. An height of a minimum of 2cms (for the QR code only) is mandatory to offer the best scanning results. Don't hesitate to print a sample to check the size before production.[[File:Effect.jpg|thumb|On our PSD file, you'll be able to find layers to apply effects or change the text depending on the language you'll be using.Take care to use the same gradients and sizings!]]

If you don't have enough vertical space for the QR code display, or for some horizontal placement, you can use the horizontal BGA banner that you can download directly here (Photoshop PSD) :

https://drive.google.com/file/d/1u-NDvzoK27UIxTomlZxZpvNMBBO8bI9e/view?usp=sharing

You can customize the bottom line using your own link details, and change the color contrast accordingly.

NOTE that on a white background, you don't need to import the white rounded frame we provide.

<div style="clear: both;"></div>

== Printing a BGA logo on rulebooks ==
Next to the mandatory logos you can have on the last page of your rules, you can add on the bottom right the same icons we have displayed here.

They're the exact same files that you can fit.

Note that a bigger QR code also implies a user scanning from a farther distance than a smaller one, and that a code being too small will not be scanned properly.

So we recommend to keep the QR code between 2cm height (QR Code zone only) up to 8cm height maximum.

Here is an example of what can be done:[[File:Last rule page.jpg|left|thumb|Last page display example. Note that the code can be as big as needed.]]

BGA Studio Cookbook

2023-07-18T08:16:48Z

Archduke: /* Irregular Shapes */

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

__TOC__

== Visual Effects, Layout and Animation ==

=== DOM manipulatons ===

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

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

Note: this method is recommended by BGA guildlines

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

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

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

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

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

'''Ingredients:''' ggg.js

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

or modern way

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

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

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

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

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

ggg.css:

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

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

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

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

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

=== Animation ===

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

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

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

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

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

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

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

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

The code is bit complex it can be found here

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

Game using it: century, ultimaterailroads

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

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

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

=== Logs ===

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

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

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

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

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

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

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

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

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

This is a bad idea for many reasons:

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

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

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

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

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

[[File:clientloginjection.png|left]]

ggg.js

<pre>

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

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

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

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

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

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

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

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

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

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

default:
break;
}

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

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

ggg.game.php:

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

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

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

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

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

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

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

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

===== Second way: rely on the <code>:formatFunction</code> option provided by <code>dojo.string.substitute</code> =====

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

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

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

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

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

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

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

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

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

<nowiki>[[ggg.js]]</nowiki>
constructor: function(){
console.log('progressevolutiontechnologyswh constructor');

// Here, you can init the global variables of your user interface
// Example:
// this.myGlobalValue = 0;
<'''let gameObject = this;''' //Needed as the this object in aspect.before will not refer to the game object in which the formatting function resides
'''aspect.before(dojo.string, "substitute", function(template, map, transform) {''' //This allows you to modify the arguments of the dojo.string.substitute method before they're actually passed to it
'''return [template, map, transform, gameObject];'''
'''});'''</span>

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

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

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

===== Third way: rely on the <code>transform</code> argument of <code>dojo.string.substitute</code> =====

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

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

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

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

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

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

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

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

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

<nowiki>[[ggg.js]]</nowiki>
constructor: function(){
console.log('progressevolutiontechnologyswh constructor');

// Here, you can init the global variables of your user interface
// Example:
// this.myGlobalValue = 0;
<'''let transformFunction = dojo.hitch(this, "getTokenDiv");''' //Needed as the this object in aspect.before will not refer to the game object in which the formatting function resides
'''aspect.before(dojo.string, "substitute", function(template, map, transform) {'''
'''if (undefined === transform) {''' //Check for a transform function presence, just in case
'''return [template, map, transformFunction];'''
'''}'''
'''});'''</span>

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

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

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

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

'''Ingredients:''' ggg.js

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

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

=== Player Panel ===

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

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

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

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

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

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

some hackery required in js

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

=== Images and Icons ===

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

'''Ingredients:''' ggg.js

<pre>
// your game resources

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

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

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

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

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

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

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

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

where ${color} - is color you want

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

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

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

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

return avatarURL;
},
</pre>

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

==== Adding Image buttons ====

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

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

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

=== Other Fluff ===

==== Use thematic fonts ====

'''Ingredients:''' ggg.css

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

[[File:Dragonline_font.png]]

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

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

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

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

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

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

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

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

=== Use player color in template ===

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

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

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

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

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

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

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

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

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

ggg.js:
<pre>
onZoomPlus: function() {
this.my_zoom+=0.1;
this.zoommy('thething',this.my_zoom);
},

zoommy: function(node, zoom) {
node=$(node);
var width = 100 / zoom;
node.style.transformOrigin = "0 0";
node.style.transform = "scale(" + zoom + ")";
node.style.width = width + "%";
},
</pre>

=== Dynamic tooltips ===

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

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

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

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

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

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

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

'''Ingredients:''' ggg.js

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

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

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

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

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

==== Rectangles and circles ====

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

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

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

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

==== Irregular Shapes ====

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

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

For instance:

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

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

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

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

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

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

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

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

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

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

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

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

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

== Game Model and Database design ==

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

[[File:Madeira board.png]]

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

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

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

Variant 1: Minimalistic

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

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

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

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

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

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

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

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

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

Variant 3: More normalised

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

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

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

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

=== Database for The card game ===

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

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

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

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

Variant 1: Minimalistic

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

Variant 2: More normalised

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

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

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

== Code Organization ==

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

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

});

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

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

use it

foo = new bgagame.other();

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

* Create ggg_other.js in modules/ folder and sync

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

* Modify ggg.js to include it

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

});

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

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

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

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

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

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

require_once ('modules/ggg_other.php');

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

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

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

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

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

</pre>

Run from command line like
php7 ggg_test.php

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

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

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

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

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

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

</pre>

=== More readable JS: onEnteringState ===

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

<pre>

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

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

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

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

</pre>

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

=== Frameworks and Preprocessors ===

* [[Using Vue]] - work-in-progress guide on using the modern framework Vue.js to create a game
* [[Using Typescript and Scss]] - How to auto-build Typescript and SCSS files to make your code cleaner

== Assorted Stuff ==

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

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

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

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

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

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

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

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

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

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

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

'''Ingredients:''' ggg.js

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

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

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

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

'''Ingredients:''' ggg.js

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

So lets do Select Worker/Place Worker

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

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

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

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

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

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

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

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

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

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

See definition of Action Stack above.

To implement you usually need another db table that has the following fields: index of effect - which is used for sorted access, type - which is essense of the effect (i.e. collect resource), some extra arguments (i.e. resource type and resource count), and usually owner of the effect (i.e. player id)
The flow is:
* There is some initial player state, where player can play card for example
* Player main action - pushes the card effect on stack, which also can cause triggered effects which also go on stack
* After action processing is finished switch to game state which is "dispatcher"
* Dispatcher pulls the top effect (whatever definition of the top is), changes the active player and changes the state to appropriate player state to collect response
* Player state knows about the stack and pulls arguments (argX) from the effect arguments of the db
* Player action should clear up the top effect, and can possibly add more effects, then switch to "dispatcher" state again
* If stack is empty, dispatcher can either pick next player itself or use another game state which responsible for picking next player

Code can be found in Tapestry.

=== Changing state prompt ===

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

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

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

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

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

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

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

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

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

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

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

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

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

'''Ingredients:''' ggg.js

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

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

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

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

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

'''Ingredients:''' ggg.php

Hack alert. This is a hack.

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

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

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

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

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

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

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

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

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

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

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

; In ggg.php
We intentionally throw BgaUserException to rollback database transaction and cancel all changes. Note that any notifications are also cancelled!
<pre>
function foo(bool $didConfirm = false): void
{
// do processing for the user's move
// afterwards, you determine this move will end the game
// so you want to rollback the transaction and require the user to confirm the move first

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

; In ggg.js
We define a global variable at the top to store the last error code
<pre>
var lastErrorCode = null;
return declare("bgagame.ggg", ebg.core.gamegui, {
</pre>

We override framework function showMessage to populate the last error code and suppress the red banner message and log message
<pre>
/* @Override */
showMessage: function (msg, type) {
if (type == "error") {
lastErrorCode = msg.startsWith("!!!") ? msg.substring(3) : null;
if (lastErrorCode) {
return; // suppress red banner and log message
}
}
this.inherited(arguments);
},
</pre>

Since the framework calls showMessage before your ajaxcall error handler, you can deal with the error in-place:
<pre>
fooAction: function (didConfirm) {
var data = {
foo: "bar",
didConfirm: !!didConfirm,
};
this.ajaxcallwrapper("fooAction", data, function (error) {
if (lastErrorCode == "endGameWarning") {
// your custom error handling goes here
// for example, show a confirmation dialog and repeat the action with additional param
this.confirmationDialog(
_("Doing the foo action now will end the game"),
() => {
this.fooAction(true);
}
);
}
});
},
</pre>

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

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

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

The solution? You can announce in your game group that you are locking table creation, and then in your new version, add an impossible startcondition to an existing option. Here is an example of an option with only 2 values:

; In gameoptions.inc.php
<pre>
// TODO NEXT remove after testing deploy to upgrade
'startcondition' => [
OPT_VALUE_DISABLE => [ [ 'type' => 'minplayers', 'value' => 32, 'message' => totranslate('Maintenance in progress. Table creation disabled.') ] ],
OPT_VALUE_ENABLE => [ [ 'type' => 'minplayers', 'value' => 32, 'message' => totranslate('Maintenance in progress. Table creation disabled.') ] ],
],
</pre>

'''Be sure to click "Reload game options configuration" after making this change.'''

Now, when a player attempts to create a new lobby, they will see a red error bar with your "Maintenance in progress" message. Once you confirm the new deploy looks good, you can revert the change in gameoptions.inc.php and do another deploy.

== Algorithms ==

=== Generate permutations in lexicographic order ===

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

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

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

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

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

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

[[Category:Studio]]

Studio

2023-07-05T09:11:08Z

Archduke: /* Software Versions */

{{Studio_Framework_Navigation}}

[[File:Bga_studio_small.jpg]]

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

__TOC__

== What is Board Game Arena Studio? ==

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

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

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

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

== Discover BGA Studio in 5 presentations ==

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

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

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

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

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

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

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

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

Then start editing files and see what happens! ;)

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

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

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

== BGA Studio documentation ==

=== BGA Studio Framework reference ===

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

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

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

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

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

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

==== Other components ====

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

=== BGA Studio game components reference ===

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

JS:

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

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

Reference for classes in game class hierarchy

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

=== BGA Studio user guide ===

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

Lifecycle

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

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

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

== Software Versions ==

Versions currently used by BGA framework:

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

=== PHP Extensions Used ===

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

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

== Other resources ==

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

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

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

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

[[Contact BGA Studio]]

[[Category:Studio]]

Template:Studio Framework Navigation

2023-05-31T08:13:59Z

Archduke:

<div class="studio-framework-navigation" style="float: right; width: 300px; border: solid #000 1px; padding: 1em; margin-left: 1em; background: #fff;">

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game File Reference'''</center></div>

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''[[Studio file reference|Overview]]'''</center></div>

* [[Game database model: dbmodel.sql|<b>dbmodel.sql</b>]] - database model
* [[Game meta-information: gameinfos.inc.php|<b>gameinfos.inc.php</b>]] - meta-information
* [[Game options and preferences: gameoptions.inc.php|<b>gameoptions.inc.php</b>]] - game options & user preferences
* [[Game art: img directory|<b>img/</b>]] - game art
* [[Game_metadata_manager|<b>Game Metadata Manager</b>]] - tags and metadata media
* [[Game material description: material.inc.php|<b>material.inc.php</b>]] - static data
* <b>misc/</b> - studio-only storage
* <b>modules/</b> - additional game code
* [[Your game state machine: states.inc.php|<b>states.inc.php</b>]] - state machine
* [[Game statistics: stats.inc.php|<b>stats.inc.php</b>]] - statistics
* [[Players actions: yourgamename.action.php|X.<b>action.php</b>]] - player actions
* [[Game interface stylesheet: yourgamename.css|X<b>.css</b>]] - interface stylesheet
* [[Main game logic: yourgamename.game.php|X.<b>game.php</b>]] - main logic
* [[Game interface logic: yourgamename.js|X.<b>js</b>]] - interface logic
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X.<b>view.php</b>]] - dynamic game layout
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X_X.<b>tpl</b>]] - static game layout
<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Useful Components'''</center></div>

'''Official'''

* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
* [[Draggable]]: a JS component to manage drag'n'drop actions.
* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.
* [[Zone]]: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).

Undocumented component (if somebody knows please help with docs)
* [[Wrapper]]: a JS component to wrap a <div> element around its child, even if these elements are absolute positioned.

'''Unofficial'''

* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks
* [[Some usual board game elements image ressources]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game Development Process'''</center></div>

* [[First steps with BGA Studio]]
* [[Create a game in BGA Studio: Complete Walkthrough]]
* [[Tutorial reversi]]
* [[Tutorial gomoku]]
* [[Tutorial hearts]]
* [[BGA Studio Guidelines]]
* [[BGA game Lifecycle]]
* [[Pre-release checklist]]
* [[Post-release phase]]
* [[Help|Player Resources]] - add player help/rules to your game page

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Guides for Common Topics'''</center></div>

* [[Translations]] - make your game translatable
* [[Game replay|Game Replay]]
* [[Your game mobile version|Mobile Users]]
* [[3D]]
* [[Compatibility]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Miscellaneous Resources'''</center></div>

* [[Studio FAQ]]
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment
* [[Studio logs]] - Instructions for log access
* [[Practical debugging]] - Tips focused on debugging
* [[Troubleshooting]] - Most common "I am really stuck" situations
* [https://studio.boardgamearena.com/bugs Studio Bugs] - Reports against Studio itself (not BGA!)
</div>

Compatibility

2023-05-31T08:13:45Z

Archduke:

{{Studio_Framework_Navigation}}

The mainsite is built with compatibility for several old browsers.

We use a [https://browsersl.ist/#q=last+2+versions%2C+not+dead%2C+%3E+0.2%25 browserslist] config to define the targeted browsers: <code>last 2 versions, not dead, > 0.2%</code>.

There are currently no hard rules about what you should target, but it is recommended to follow the same targets as the mainsite. You can use [https://babeljs.io/ babel] to compile your modern JavaScript code into backwards compatible code. Babel accepts a browserslist targets string, so you can use the targets above.

== Current list ==

At time of writing, <code>last 2 versions, not dead, > 0.2%</code> refers to:

* and_chr 113
* and_ff 113
* and_qq 13.1
* and_uc 13.4
* android 113
* android 4.4.3-4.4.4
* chrome 113
* chrome 112
* chrome 111
* chrome 110
* chrome 109
* chrome 108
* chrome 103
* chrome 79
* edge 113
* edge 112
* edge 111
* firefox 113
* firefox 112
* firefox 111
* ie 11
* ios_saf 16.4
* ios_saf 16.3
* ios_saf 16.2
* ios_saf 16.1
* ios_saf 16.0
* ios_saf 15.6
* ios_saf 15.5
* ios_saf 14.5-14.8
* ios_saf 14.0-14.4
* ios_saf 12.2-12.5
* kaios 3.0-3.1
* kaios 2.5
* op_mini all
* op_mob 73
* opera 98
* opera 97
* opera 96
* safari 16.4
* safari 16.3
* safari 16.2
* safari 16.1
* safari 15.6
* safari 14.1
* samsung 20
* samsung 19.0

[[Category:Studio]]

Compatibility

2023-05-31T08:12:12Z

Archduke:

{{Studio_Framework_Navigation}}

__TOC__

The mainsite is built with compatibility for several old browsers.

We use a [https://browsersl.ist/#q=last+2+versions%2C+not+dead%2C+%3E+0.2%25 browserslist] config to define the targeted browsers: <code>last 2 versions, not dead, > 0.2%</code>.

There are currently no hard rules about what you should target, but it is recommended to follow the same targets as the mainsite. You can use [https://babeljs.io/ babel] to compile your modern JavaScript code into backwards compatible code. Babel accepts a browserslist targets string, so you can use the targets above.

== Current list ==

At time of writing, <code>last 2 versions, not dead, > 0.2%</code> refers to:

and_chr 113
and_ff 113
and_qq 13.1
and_uc 13.4
android 113
android 4.4.3-4.4.4
chrome 113
chrome 112
chrome 111
chrome 110
chrome 109
chrome 108
chrome 103
chrome 79
edge 113
edge 112
edge 111
firefox 113
firefox 112
firefox 111
ie 11
ios_saf 16.4
ios_saf 16.3
ios_saf 16.2
ios_saf 16.1
ios_saf 16.0
ios_saf 15.6
ios_saf 15.5
ios_saf 14.5-14.8
ios_saf 14.0-14.4
ios_saf 12.2-12.5
kaios 3.0-3.1
kaios 2.5
op_mini all
op_mob 73
opera 98
opera 97
opera 96
safari 16.4
safari 16.3
safari 16.2
safari 16.1
safari 15.6
safari 14.1
samsung 20
samsung 19.0

[[Category:Studio]]

Compatibility

2023-05-31T08:07:20Z

Archduke: Created page with "{{Studio_Framework_Navigation}} __TOC__ The mainsite is built with compatibility for several old browsers. We use a browserslist config to define the targeted browsers: `last 2 versions, not dead, > 0.2%`. == File structure == Category:Studio"

{{Studio_Framework_Navigation}}

__TOC__

The mainsite is built with compatibility for several old browsers.

We use a browserslist config to define the targeted browsers: `last 2 versions, not dead, > 0.2%`.

== File structure ==

[[Category:Studio]]

Game replay

2023-05-09T13:18:13Z

Archduke:

{{Studio_Framework_Navigation}}

Game replay is managed by the framework. You do not need to do anything special about it in your code, except taking care of updating the client interface through the framework notification system (and not for example, by using the callback function of an ajaxcall).

The game replay works like this:
* The static files for the game at the time of the game start are archived
* All notifications sent to the browser are added to the archive
* When replaying, the static files are loaded in the browser, then notifications are sent back to replay the game moves.

So in essence, the replay works like an exact recording.

NB: the game replay feature is now available on the studio (since December 2020). Please note that there may be a delay before the replay becomes available.

=== Preview Videos ===
Example games are periodically selected from which videos are generated to show off the game on the game panel.

Wingspan: https://x.boardgamearena.net/data/gamepreviews/1635/en-w640.webm

These previews are generated with a query variable set <code>target=video</code> in order that you can hide parts of the UI for this video. This should only be done in specific cases, such as to remove modal popups which the player would normally manually dismiss. These modal popups will otherwise remain visible and obscure the video preview.
const searchParams = new URLSearchParams(window.location.search);
if (searchParams) {
const target = searchParams.get('target');
if (target === "video") {
// Hide modal popups...
}
}
[[Category:Studio]]

File:KoT Major Variant.png

2022-12-22T07:15:54Z

Archduke:

Example major variant image for KoT

Gamehelppuzzlestriketwo

2022-06-28T11:55:04Z

Archduke: Created blank page

Translations

2022-06-06T16:47:35Z

Archduke: /* On client side (Javascript) */

{{Studio_Framework_Navigation}}

Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.

__TOC__

== Localization Overview ==

Localization for BGA games happens largely on the CLIENT. Games must be developed in English and English strings are sent to the client.

It's only at the client that your English strings will be displayed with the translation for the user's language, when such a translation exists.

For anyone who has worked on a system where translation happens at the server and localized strings are sent to the client: you must unlearn what you have learned. Just stick with English and send the untranslated English strings. The magic happens at the client.

== How will my strings be translated? ==

When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.

Once your game enters Beta, the BGA player community will descend upon your game like a plague of locusts and translate it into dozens of languages before you can say "Je ne parle pas anglais".

== What do I have to do from a programming standpoint? ==

Not as much as you think. Read on for full details, but the golden rules are:

# Make sure that any string on the server side that needs to be translated on the client side is wrapped in a clienttranslate() function when defined. For example: $my_response = clienttranslate('Hey translators, please translate this string'). clienttranslate doesn't actually do anything at all (it just passes the text through) but the translation engine searches your code for strings wrapped in that function and uses them to build the list of strings that need to be translated.
# On the client side, just display your text, but wrap it in _().
## If you pass a string constant to _() - such as _('This is my string') then the parser will automatically detect and add your string to the list of strings that need to be translated, AND it will display the local translation for it when displaying.
## If you pass a variable to _() - such as _(args.my_message) then MAKE SURE that the variable is set to an English string that is either defined somewhere in your PHP code in a clienttranslate() function or somewhere else in your javascript code in a _() function. As long as it is, the translators will provide translations for it, and the _() function will display the local translation of your English string.
# A string used as the message for notifyAllPlayers or notifyPlayer will automatically have its translation displayed on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used as the "description" or "descriptionmyturn" for a state in your state machine will also be automatically translated on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used in the pre-games option screen will also automatically have any translation displayed at the client - you don't need to do anything EXCEPT make sure that it is wrapped in a totranslate() on the server (nota bene: you should not use clienttranslate() here as this file is processed specifically and those strings will not be included in the game translation file but in the main site translation file - with a prefix to keep translations isolated by module - as they have to be translated on main site pages. If you need exactly the same string in your game for a client side translation, it should be declared somewhere else in your code wrapped inside a clienttranslate() to be included in the game translation file.
# A string used in the statistics screen will operate like a string in the pre-game options screen. It will automatically have any translation displayed at the client as long as you make sure that it is wrapped in a totranslate() on the server.
# If you are using parameters for a call to notifyAllPlayers or notifyPlayers, or for a state's "description" or "descriptionmyturn" and those parameters contain text that needs to be translated, you will need to tell the system to display the translated versions of them by using the 'i18n' argument. See below for full details.

== What strings should be translated? ==

Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages.

This does NOT include error messages that are not supposed to happen (unexpected errors).

== What rules should I follow for the original English strings? ==

For a coherent and homogeneous interface, here are some rules about ending a sentence with a final period '.'

* As a general rule:
** If a sentence is displayed isolated in the interface => no final period
** If a sentence is followed or could be followed by another sentence in the same interface space => final period.

* In detail:
** No final period:
*** button labels
*** section titles
*** menu elements
*** links triggering an isolated action
*** anything that is not a full sentence
*** current actions in the status bar
** Final period:
*** complete sentences (e.g., explanations and descriptions) that can be chained with other sentences
** Either a period or no period is acceptable (but this should be consistent throughout the game) for:
*** isolated tooltips / small sentences
*** game logs (no period is usually preferable)
*** error messages (unless there is more than one sentence in the error message; final period is mandatory in this case)

Otherwise, you should try to follow as closely as possible the general style and format (including capitalization) used in the published English rulebook and game materials.

== Focus on translating notifications ==

Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.

However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.

== How to not make translators crazy ;) ==

* Try to reuse the exact same strings (with the same case, etc.) to minimize the number of strings to translate.
** '''Example''': Consider replacing <pre>self::_("Winner")</pre> and <pre>self::_("Winners")</pre> (two strings to translate) with <pre>self::_("Winner(s)")</pre>
** '''Example 2''': <pre>clienttranslate("play a card")</pre> and <pre>clienttranslate("Play a card")</pre> means there will be two strings to translate.
* Do not mark as translatable a game element that does not have to be translated (e.g., if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:
<pre>self::_("First part of the string, ").$argument.' '.self::_("second part of the string")</pre>
Write instead:
<pre>sprintf( self::_("First part of the string, %s second part of the string"), $argument )</pre>
(or the equivalent "dojo.string.substitute" in Javascript)
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The shorter the string is, the more difficult the task is for them. As a rule of thumb, try to avoid short, insignificant strings that require knowledge of their surrounding context. You can also leave a comment on the context of the string in the translation program (English to English) if you are the developer of the game.
* The BGA translation policy is to be flexible on grammar. We prefer to write "player gets 1 coin(s)" rather than write two versions of the same string for plural and singular - it reduces the number of strings to translate.
* Instead of writing elaborate strings like "With the effect of ZZZ, player XXX gains a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".
* Use present tense instead of past. E.g., "player gets wood" instead of "player got wood".
* Avoid using gender-specific wording as much as possible. If needed be aware that [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place, and cannot work if your use "their" as a singular genderless pronoun, as it removes the information that it's singular. E.g., you should write "playerX returns card to *his* hand" or "playerX returns card to *his/her* hand" and not "playerX returns card to *their* hand" as in the 2 first case the system will substitute the proper pronoun his/her/their depending on playerX declared/undeclared gender, but in the second case it will always stay "their" whatever the player preference setting.
* Where two strings are identical apart from (say) a number, use the same string with a ${parameter}, and call format_string_recursive (on the client) or use args (for notifications and state descriptions) to provide the details. But *never* do that for composing multiple sentences with words: other languages have different grammar and it would most likely create untranslatable strings.

== WARNING: Make sure your strings will be translated! ==

For each game, our translation tool does a full scan of the code, looking for translation markers like "_()" or "clienttranslate()". (See below for the full list of translation markers.)

If your original string is not completely contained inside one of these markers, it won't be translated.

<pre>
// Examples: the following strings will be translated:
var mystring_translated = _("my string"); // JS
$mystring_translated = self::_("my string"); // PHP
$mystring_translated = sprintf( self::_("my string with an %s argument"), $argument ); // PHP

// Examples: the following strings WILL NOT be translated:
$my_string = "my string";
$not_translated = self::_( $my_string ); // The original string is not contained within a translator marker => no translation
$not_translated = self::_( sprintf( "my string with a %s argument", $argument ) ); // Ditto
</pre>

== On client side (Javascript) ==

On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.

Examples:
<pre>
// Get a string in player's language:
var translated = _("original english string");

// Get a string in player's language with parameter:
var translated = dojo.string.substitute( _("You can pick ${p} cards and discard ${d}"), {
p: 2,
d: 4
} );
</pre>

'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.

'''ANOTHER WARNING:''' you cannot use this function _() in the javascript object constructor, but you can achieve the same if you use it the setup method

=== Formatting on client side ===

Sometimes you will want to apply some formatting on the client side, but don't want to put HTML tags within the source string (which may be confusing for translators).

This can be achieved with the <code>bga_format</code> function and Markdown-style syntax.

<pre>
/**
* @function bga_format
* Replaces delimiters with HTML tags in translated text
* @param {string} translated string
* @param {Object} map of replacements to make, should be of the form
* {
* '*': (t) => t,
* '_': 'classname',
* }
* keys are delimiters within the translated string
* values are either strings (classname of surrounding span) or function (flexible replacements)
* @returns {string} Returns the original string, with replacements made.
*/
</pre>

Example:
<pre>
// Get a string in player's language:
bga_format(_('You receive a *special* _tile_'), {
'*': (t) => '<b>' + t + '</b>',
'_': 'tile-name'
});
</pre>

The above will return something along the lines of:
<pre>
You receive a <b>special</b> <span class="tile-name">tile</span>
</pre>

Or, if the user is playing in Spanish, for example:
<pre>
Recibes una <span class="tile-name">loseta</span> <b>especial</b>
</pre>

Notes:
* The text passed to <code>bga_format</code> must still be translated using <code>_()</code>, don't forget it!
* Good characters to demarcate formatting are: <code>['*', '_']</code> (other single characters will work, just make sure it will be clear to a translator)
* If the replacements object is a string, the inner text will be placed within a <code><span></code> tag with the string as a class
* If the replacements object is a function, the inner text will be passed as an argument to the function, and the return value will replace the text and the delimiters

== On server side (PHP) ==

On PHP side, you can use 3 different functions to specify that a string must be translated.

=== Function clienttranslate ===

'''clienttranslate( 'string to translate' ):'''

This function is ''transparent'': it will return the original English string without any change. Its only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.

In general, you use clienttranslate:
* In your '''states.inc.php''', for the fields "description" and "descriptionmyturn".

<pre>
"description" => clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),
</pre>

* In '''material.inc.php''', when defining text for game materials that must be displayed on the client side.

<pre>
$this->card_types = array(

1 => array(
'name' => clienttranslate('Amulet of Air'), // Thus, we can use "_( card_name )" on Javascript side.
</pre>

* When sending a notification with ''notifyAllPlayers'' or ''notifyPlayer'', in the game log string and all game log arguments that need a translation.

<pre>
// A game log string with no argument:
self::notifyAllPlayers( 'pickLibraryCards', clienttranslate('Everyone draw cards from their library'), [] );
</pre>

As a consequence there is no point passing variables to this function. E.g.:

<pre>
notif="foo";
self::notifyAllPlayers( 'log', clienttranslate(notif),[]); // BAD

notif=clienttranslate("foo");
self::notifyAllPlayers( 'log', notif,[]); // GOOD

self::notifyAllPlayers( 'log', clienttranslate("player gains ${num} gems"),[num=>2]); // BAD it is dynamic string enterpreted by php
self::notifyAllPlayers( 'log', clienttranslate('player gains ${num} gems'),[num=>2]); // GOOD, difference is single quotes

self::notifyAllPlayers( 'log', clienttranslate("player gains ".${num}." gems"),[num=>2]); // BAD concatenation

</pre>

Translating arguments is a little bit more complex. This uses the '''i18n''' special argument as below:

<pre>
// In the following example, we translate the game log itself, but also the "card_name" argument:

self::notifyAllPlayers( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'points' => $points,
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.
) );
</pre>

To ensure the translation of the i18n argument will be made, clienttranslate must have been used somewhere, for instance:

<pre>
$this->card_types = array(
...
8 => array(
'name' => clienttranslate("Amulet of Fire"),
...
</pre>

Pay attention when using the '''i18n''' argument when translating arguments for the client: do NOT use same argument for both translations AND key codes for client-side actions (like using 'card_name' to move it on the player board as described in the example). It's pretty obvious in the example, but it can be very tricky when translation is made at the end of the development (which is often the case). Use explicit argument names like 'card_name_translated' by example.

'''WARNING:''' you should NEVER use concatenation with ''clienttranslate'', as it would result in a different string to translate at runtime than the one retrieved statically in the translation system, and so translation would not be applied. If you need to compose a string, use substitution and the i18n parameter (but you also have to pay attention not to compose sentences in a way that is dependent upon the English language specific syntax, or it may be impossible to translate correctly in another language: sometimes, you need multiple full sentences rather than relying on substitution).

=== Method _ (underscore) ===

'''self::_( "my string to translate" ):'''

This function returns a string translated in the language of CURRENT user (i.e. player who send the request to the server) (be careful, this is NOT the active player).

This can be used like self::_('bla') or this->('bla'). You cannot use static underscore function _('bla') in php, it is not the same, it will not translate strings from your game.

The returned string will be surrounded by HTML tags, so you cannot use it in places where pure text is required or your string already has another html markup.

Most of the time, you don't need to translate strings on server side, except on the following situations:
* Throwing user exceptions
* Creating the labels for the game interface used in your template
* Rarely, in your material.inc.php, if for example you need to use some string elements in your exceptions
* Rarely, in your "getAllDatas" PHP method, as the data return by this method is used only by current user

Imporant! This function does two things:
* Mark string for translation
* Translates in runtime
As a consequence you absolutely cannot have $var in there! Or string concatenations.
I.e.
$food=self::_("Banana");// good
self::_("User gives $food to a cat"); // bad
For the translator we will have two strings "Banana" and "User gives $food to a cat", but in runtime we will be
"Banana" and "User gives Banana to a cat" and second string would not match anything. And this is as bad
self::_("User gives ".$food." to a cat");// bad

==== Throwing an exception because the player did a forbidden move ====

<pre>
// This will display a translatable red message to the player that just did some wrong action:
throw new BgaUserException( self::_('You must choose 3 cards') );

// ... notice the use of BgaUserException that signals that this exception is "expected". In theory, all exception that are expected should be translated.
</pre>

==== Creating labels ====

In "yourgame.view.php", when creating the labels for the game interface used in your template (.tpl) file.

<pre>
$this->tpl['CARDS_FOR_YEAR_2'] = self::_("Your cards for year II");
</pre>

'''Nota bene:''' it is recommended to set translated text in your interface client side rather than use template variables and server translation, so that translation works natively in replays (that don't have server side translations). For simple strings, the framework will handle moving the translation client side, but for more complex strings it may not work. In particular, you should not use server side translation for templates with substitution variables (or use the specific function "gameview_str_replace( $search, $replace, $string )" if not possible otherwise or for old code compatibility). Also, you should never use a "to_translate" class in your .tpl as it is used internally by the framework.

Example with view.php:
in .tpl:
<pre>
<div id="empire_title_{COLOR}" class="side_title color_{COLOR}">{EMPIRE_LABEL}</div>
</pre>
in view.php:
$this->page->insert_block("player_board", array ("COLOR" => $color,"PLAYER_NAME" => $name,"PLAYER_NO" => $no,
"PLAYER_ID" => $player_id, "CLASSES" => $own?"own":"",
"EMPIRE_LABEL" => self::raw(gameview_str_replace('${player_name}', $name, self::_('${player_name}\'s EMPIRE')))
));
Example with client side:
in .tpl:
<pre>
<div id="empire_title_{COLOR}" class="side_title color_{COLOR}">Stub</div>
</pre>
in .js:
<pre>
for (var player_id in this.gamedatas.players) {
var player_color = this.gamedatas.players[player_id].color;
var player_name = this.gamedatas.players[player_id].name;
$('empire_title_'+player_color).innerHTML=this.format_string_recursive(_("${player_name}'s EMPIRE"), {player_name: player_name});
}
</pre>

==== Translating strings in material file ====

Rarely, in your material.inc.php, if for example you need to use some string elements in your exceptions.

<pre>
// In material.inc.php, $this->energies[n]['nametr'] has been created with the self::_() method. Now we can do this:
throw new BgaUserException( self::_("To execute this action you need more: ").' '.$this->energies[$resource_id]['nametr'] );
</pre>

Note: you could also do this, so you don't need to pollute your material file
throw new BgaUserException( self::_("To execute this action you need more: ").' '.self::_($this->energies[$resource_id]['name']) );

where $this->energies[$resource_id]['name'] were marked in material file using regular clienttranslate function
<pre>
$this->energies = [
22 => [
'name' => clienttranslate('Sun')
...
]
];
</pre>

==== Strings in getAllDatas ====

Rarely, in your "getAllDatas" PHP method, as the data return by this method is used only by current user.

Note: not sure why would you send strings from the server in this case, as same can be achieved on the client usually.

=== Function totranslate ===

'''totranslate( "my string to translate" ):'''

This function works exactly like 'clienttranslate', except it tells BGA that the string is not needed on client side.

You should not use this function, except on the following cases:
* Statistics name in stats.inc.php
* Option names and option values name in gameoptions.inc.php

== Top Secret Undocumented Features ==

If your string contains the clause '$${value}' (such as 'You gain $${value}.') then the translation system seems to move the position of the $ to a localized location (eg $5 in English but 5$ in French). This only seems to occur when using the argument 'value'.

In JavaScript, you can get the current user's language by retrieving the translation for the special string "$locale":

var lang = _('$locale'); // en, fr, etc.

== On server side - advanced (PHP) ==

If you want to use translation system in your custom static modules, you will first need to expose the _() function :
<pre>
class mygame extends Table {
// Exposing protected method translation
public static function totranslate($text) {
return self::_($text);
}
}
</pre>

Then you'll be able to use this directly in other modules by doing
<pre>
throw new BgaUserException(mygame::totranslate("Translated error from my awesome module file"));
</pre>

Notice how the "totranslate" is also used by the static analysis to detect your string. So the following will not work :
<pre>
$msg = "Translated error from my awesome module file";
throw new BgaUserException(mygame::totranslate($msg));
</pre>

== Analyze your project ==

It looks super complex but there is help!
On studio control panel you can find a button "Check project" - it runs bunch of static analysis on your project including scanning for bad translations and missing translations.
It also will extact all you translation keys as translator will see them so you can double check - and run spell checker on them.

== Other Useful Links ==

* BLOG post about translations https://bga-devs.github.io/blog/posts/translations-summary/

[[Category:Studio]]

Translations

2022-06-06T16:46:51Z

Archduke: /* On client side (Javascript) */

{{Studio_Framework_Navigation}}

Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.

__TOC__

== Localization Overview ==

Localization for BGA games happens largely on the CLIENT. Games must be developed in English and English strings are sent to the client.

It's only at the client that your English strings will be displayed with the translation for the user's language, when such a translation exists.

For anyone who has worked on a system where translation happens at the server and localized strings are sent to the client: you must unlearn what you have learned. Just stick with English and send the untranslated English strings. The magic happens at the client.

== How will my strings be translated? ==

When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.

Once your game enters Beta, the BGA player community will descend upon your game like a plague of locusts and translate it into dozens of languages before you can say "Je ne parle pas anglais".

== What do I have to do from a programming standpoint? ==

Not as much as you think. Read on for full details, but the golden rules are:

# Make sure that any string on the server side that needs to be translated on the client side is wrapped in a clienttranslate() function when defined. For example: $my_response = clienttranslate('Hey translators, please translate this string'). clienttranslate doesn't actually do anything at all (it just passes the text through) but the translation engine searches your code for strings wrapped in that function and uses them to build the list of strings that need to be translated.
# On the client side, just display your text, but wrap it in _().
## If you pass a string constant to _() - such as _('This is my string') then the parser will automatically detect and add your string to the list of strings that need to be translated, AND it will display the local translation for it when displaying.
## If you pass a variable to _() - such as _(args.my_message) then MAKE SURE that the variable is set to an English string that is either defined somewhere in your PHP code in a clienttranslate() function or somewhere else in your javascript code in a _() function. As long as it is, the translators will provide translations for it, and the _() function will display the local translation of your English string.
# A string used as the message for notifyAllPlayers or notifyPlayer will automatically have its translation displayed on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used as the "description" or "descriptionmyturn" for a state in your state machine will also be automatically translated on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used in the pre-games option screen will also automatically have any translation displayed at the client - you don't need to do anything EXCEPT make sure that it is wrapped in a totranslate() on the server (nota bene: you should not use clienttranslate() here as this file is processed specifically and those strings will not be included in the game translation file but in the main site translation file - with a prefix to keep translations isolated by module - as they have to be translated on main site pages. If you need exactly the same string in your game for a client side translation, it should be declared somewhere else in your code wrapped inside a clienttranslate() to be included in the game translation file.
# A string used in the statistics screen will operate like a string in the pre-game options screen. It will automatically have any translation displayed at the client as long as you make sure that it is wrapped in a totranslate() on the server.
# If you are using parameters for a call to notifyAllPlayers or notifyPlayers, or for a state's "description" or "descriptionmyturn" and those parameters contain text that needs to be translated, you will need to tell the system to display the translated versions of them by using the 'i18n' argument. See below for full details.

== What strings should be translated? ==

Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages.

This does NOT include error messages that are not supposed to happen (unexpected errors).

== What rules should I follow for the original English strings? ==

For a coherent and homogeneous interface, here are some rules about ending a sentence with a final period '.'

* As a general rule:
** If a sentence is displayed isolated in the interface => no final period
** If a sentence is followed or could be followed by another sentence in the same interface space => final period.

* In detail:
** No final period:
*** button labels
*** section titles
*** menu elements
*** links triggering an isolated action
*** anything that is not a full sentence
*** current actions in the status bar
** Final period:
*** complete sentences (e.g., explanations and descriptions) that can be chained with other sentences
** Either a period or no period is acceptable (but this should be consistent throughout the game) for:
*** isolated tooltips / small sentences
*** game logs (no period is usually preferable)
*** error messages (unless there is more than one sentence in the error message; final period is mandatory in this case)

Otherwise, you should try to follow as closely as possible the general style and format (including capitalization) used in the published English rulebook and game materials.

== Focus on translating notifications ==

Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.

However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.

== How to not make translators crazy ;) ==

* Try to reuse the exact same strings (with the same case, etc.) to minimize the number of strings to translate.
** '''Example''': Consider replacing <pre>self::_("Winner")</pre> and <pre>self::_("Winners")</pre> (two strings to translate) with <pre>self::_("Winner(s)")</pre>
** '''Example 2''': <pre>clienttranslate("play a card")</pre> and <pre>clienttranslate("Play a card")</pre> means there will be two strings to translate.
* Do not mark as translatable a game element that does not have to be translated (e.g., if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:
<pre>self::_("First part of the string, ").$argument.' '.self::_("second part of the string")</pre>
Write instead:
<pre>sprintf( self::_("First part of the string, %s second part of the string"), $argument )</pre>
(or the equivalent "dojo.string.substitute" in Javascript)
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The shorter the string is, the more difficult the task is for them. As a rule of thumb, try to avoid short, insignificant strings that require knowledge of their surrounding context. You can also leave a comment on the context of the string in the translation program (English to English) if you are the developer of the game.
* The BGA translation policy is to be flexible on grammar. We prefer to write "player gets 1 coin(s)" rather than write two versions of the same string for plural and singular - it reduces the number of strings to translate.
* Instead of writing elaborate strings like "With the effect of ZZZ, player XXX gains a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".
* Use present tense instead of past. E.g., "player gets wood" instead of "player got wood".
* Avoid using gender-specific wording as much as possible. If needed be aware that [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place, and cannot work if your use "their" as a singular genderless pronoun, as it removes the information that it's singular. E.g., you should write "playerX returns card to *his* hand" or "playerX returns card to *his/her* hand" and not "playerX returns card to *their* hand" as in the 2 first case the system will substitute the proper pronoun his/her/their depending on playerX declared/undeclared gender, but in the second case it will always stay "their" whatever the player preference setting.
* Where two strings are identical apart from (say) a number, use the same string with a ${parameter}, and call format_string_recursive (on the client) or use args (for notifications and state descriptions) to provide the details. But *never* do that for composing multiple sentences with words: other languages have different grammar and it would most likely create untranslatable strings.

== WARNING: Make sure your strings will be translated! ==

For each game, our translation tool does a full scan of the code, looking for translation markers like "_()" or "clienttranslate()". (See below for the full list of translation markers.)

If your original string is not completely contained inside one of these markers, it won't be translated.

<pre>
// Examples: the following strings will be translated:
var mystring_translated = _("my string"); // JS
$mystring_translated = self::_("my string"); // PHP
$mystring_translated = sprintf( self::_("my string with an %s argument"), $argument ); // PHP

// Examples: the following strings WILL NOT be translated:
$my_string = "my string";
$not_translated = self::_( $my_string ); // The original string is not contained within a translator marker => no translation
$not_translated = self::_( sprintf( "my string with a %s argument", $argument ) ); // Ditto
</pre>

== On client side (Javascript) ==

On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.

Examples:
<pre>
// Get a string in player's language:
var translated = _("original english string");

// Get a string in player's language with parameter:
var translated = dojo.string.substitute( _("You can pick ${p} cards and discard ${d}"), {
p: 2,
d: 4
} );
</pre>

'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.

'''ANOTHER WARNING:''' you cannot use this function _() in the javascript object constructor, but you can achieve the same if you use it the setup method

=== Formatting on client side ===

Sometimes you will want to apply some formatting on the client side, but don't want to put HTML tags within the source string (which may be confusing for translators).

This can be achieved with the <code>bga_format</code> function and Markdown-style syntax.

<pre>
/**
* @function bga_format
* Replaces delimiters with HTML tags in translated text
* @param {string} translated string
* @param {Object} map of replacements to make, should be of the form
* {
* '*': (t) => t,
* '_': 'classname',
* }
* keys are delimiters within the translated string
* values are either strings (classname of surrounding span) or function (flexible replacements)
* @returns {string} Returns the original string, with replacements made.
*/
</pre>

Example:
<pre>
// Get a string in player's language:
bga_format(_('You receive a *special* _tile_'), {
'*': (t) => '<b>' + t + '</b>',
'_': 'tile-name'
});
</pre>

The above will return something along the lines of:
<pre>
You receive a <b>special</b> <span class="tile-name">tile</span>
</pre>

Or, if the user is playing in Spanish, for example:
<pre>
Recibes una <span class="tile-name">loseta</span> <b>especial</b>
</pre>

Notes:
* The text passed to <code>bga_format</code> must still be translated using <code>_()</code>, don't forget it!
* Good characters to demarcate formatting are: <code>['-', '*', '+', '_']</code>
* If the replacements object is a string, the inner text will be placed within a <code><span></code> tag with the string as a class
* If the replacements object is a function, the inner text will be passed as an argument to the function, and the return value will replace the text and the delimiters

== On server side (PHP) ==

On PHP side, you can use 3 different functions to specify that a string must be translated.

=== Function clienttranslate ===

'''clienttranslate( 'string to translate' ):'''

This function is ''transparent'': it will return the original English string without any change. Its only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.

In general, you use clienttranslate:
* In your '''states.inc.php''', for the fields "description" and "descriptionmyturn".

<pre>
"description" => clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),
</pre>

* In '''material.inc.php''', when defining text for game materials that must be displayed on the client side.

<pre>
$this->card_types = array(

1 => array(
'name' => clienttranslate('Amulet of Air'), // Thus, we can use "_( card_name )" on Javascript side.
</pre>

* When sending a notification with ''notifyAllPlayers'' or ''notifyPlayer'', in the game log string and all game log arguments that need a translation.

<pre>
// A game log string with no argument:
self::notifyAllPlayers( 'pickLibraryCards', clienttranslate('Everyone draw cards from their library'), [] );
</pre>

As a consequence there is no point passing variables to this function. E.g.:

<pre>
notif="foo";
self::notifyAllPlayers( 'log', clienttranslate(notif),[]); // BAD

notif=clienttranslate("foo");
self::notifyAllPlayers( 'log', notif,[]); // GOOD

self::notifyAllPlayers( 'log', clienttranslate("player gains ${num} gems"),[num=>2]); // BAD it is dynamic string enterpreted by php
self::notifyAllPlayers( 'log', clienttranslate('player gains ${num} gems'),[num=>2]); // GOOD, difference is single quotes

self::notifyAllPlayers( 'log', clienttranslate("player gains ".${num}." gems"),[num=>2]); // BAD concatenation

</pre>

Translating arguments is a little bit more complex. This uses the '''i18n''' special argument as below:

<pre>
// In the following example, we translate the game log itself, but also the "card_name" argument:

self::notifyAllPlayers( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'points' => $points,
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.
) );
</pre>

To ensure the translation of the i18n argument will be made, clienttranslate must have been used somewhere, for instance:

<pre>
$this->card_types = array(
...
8 => array(
'name' => clienttranslate("Amulet of Fire"),
...
</pre>

Pay attention when using the '''i18n''' argument when translating arguments for the client: do NOT use same argument for both translations AND key codes for client-side actions (like using 'card_name' to move it on the player board as described in the example). It's pretty obvious in the example, but it can be very tricky when translation is made at the end of the development (which is often the case). Use explicit argument names like 'card_name_translated' by example.

'''WARNING:''' you should NEVER use concatenation with ''clienttranslate'', as it would result in a different string to translate at runtime than the one retrieved statically in the translation system, and so translation would not be applied. If you need to compose a string, use substitution and the i18n parameter (but you also have to pay attention not to compose sentences in a way that is dependent upon the English language specific syntax, or it may be impossible to translate correctly in another language: sometimes, you need multiple full sentences rather than relying on substitution).

=== Method _ (underscore) ===

'''self::_( "my string to translate" ):'''

This function returns a string translated in the language of CURRENT user (i.e. player who send the request to the server) (be careful, this is NOT the active player).

This can be used like self::_('bla') or this->('bla'). You cannot use static underscore function _('bla') in php, it is not the same, it will not translate strings from your game.

The returned string will be surrounded by HTML tags, so you cannot use it in places where pure text is required or your string already has another html markup.

Most of the time, you don't need to translate strings on server side, except on the following situations:
* Throwing user exceptions
* Creating the labels for the game interface used in your template
* Rarely, in your material.inc.php, if for example you need to use some string elements in your exceptions
* Rarely, in your "getAllDatas" PHP method, as the data return by this method is used only by current user

Imporant! This function does two things:
* Mark string for translation
* Translates in runtime
As a consequence you absolutely cannot have $var in there! Or string concatenations.
I.e.
$food=self::_("Banana");// good
self::_("User gives $food to a cat"); // bad
For the translator we will have two strings "Banana" and "User gives $food to a cat", but in runtime we will be
"Banana" and "User gives Banana to a cat" and second string would not match anything. And this is as bad
self::_("User gives ".$food." to a cat");// bad

==== Throwing an exception because the player did a forbidden move ====

<pre>
// This will display a translatable red message to the player that just did some wrong action:
throw new BgaUserException( self::_('You must choose 3 cards') );

// ... notice the use of BgaUserException that signals that this exception is "expected". In theory, all exception that are expected should be translated.
</pre>

==== Creating labels ====

In "yourgame.view.php", when creating the labels for the game interface used in your template (.tpl) file.

<pre>
$this->tpl['CARDS_FOR_YEAR_2'] = self::_("Your cards for year II");
</pre>

'''Nota bene:''' it is recommended to set translated text in your interface client side rather than use template variables and server translation, so that translation works natively in replays (that don't have server side translations). For simple strings, the framework will handle moving the translation client side, but for more complex strings it may not work. In particular, you should not use server side translation for templates with substitution variables (or use the specific function "gameview_str_replace( $search, $replace, $string )" if not possible otherwise or for old code compatibility). Also, you should never use a "to_translate" class in your .tpl as it is used internally by the framework.

Example with view.php:
in .tpl:
<pre>
<div id="empire_title_{COLOR}" class="side_title color_{COLOR}">{EMPIRE_LABEL}</div>
</pre>
in view.php:
$this->page->insert_block("player_board", array ("COLOR" => $color,"PLAYER_NAME" => $name,"PLAYER_NO" => $no,
"PLAYER_ID" => $player_id, "CLASSES" => $own?"own":"",
"EMPIRE_LABEL" => self::raw(gameview_str_replace('${player_name}', $name, self::_('${player_name}\'s EMPIRE')))
));
Example with client side:
in .tpl:
<pre>
<div id="empire_title_{COLOR}" class="side_title color_{COLOR}">Stub</div>
</pre>
in .js:
<pre>
for (var player_id in this.gamedatas.players) {
var player_color = this.gamedatas.players[player_id].color;
var player_name = this.gamedatas.players[player_id].name;
$('empire_title_'+player_color).innerHTML=this.format_string_recursive(_("${player_name}'s EMPIRE"), {player_name: player_name});
}
</pre>

==== Translating strings in material file ====

Rarely, in your material.inc.php, if for example you need to use some string elements in your exceptions.

<pre>
// In material.inc.php, $this->energies[n]['nametr'] has been created with the self::_() method. Now we can do this:
throw new BgaUserException( self::_("To execute this action you need more: ").' '.$this->energies[$resource_id]['nametr'] );
</pre>

Note: you could also do this, so you don't need to pollute your material file
throw new BgaUserException( self::_("To execute this action you need more: ").' '.self::_($this->energies[$resource_id]['name']) );

where $this->energies[$resource_id]['name'] were marked in material file using regular clienttranslate function
<pre>
$this->energies = [
22 => [
'name' => clienttranslate('Sun')
...
]
];
</pre>

==== Strings in getAllDatas ====

Rarely, in your "getAllDatas" PHP method, as the data return by this method is used only by current user.

Note: not sure why would you send strings from the server in this case, as same can be achieved on the client usually.

=== Function totranslate ===

'''totranslate( "my string to translate" ):'''

This function works exactly like 'clienttranslate', except it tells BGA that the string is not needed on client side.

You should not use this function, except on the following cases:
* Statistics name in stats.inc.php
* Option names and option values name in gameoptions.inc.php

== Top Secret Undocumented Features ==

If your string contains the clause '$${value}' (such as 'You gain $${value}.') then the translation system seems to move the position of the $ to a localized location (eg $5 in English but 5$ in French). This only seems to occur when using the argument 'value'.

In JavaScript, you can get the current user's language by retrieving the translation for the special string "$locale":

var lang = _('$locale'); // en, fr, etc.

== On server side - advanced (PHP) ==

If you want to use translation system in your custom static modules, you will first need to expose the _() function :
<pre>
class mygame extends Table {
// Exposing protected method translation
public static function totranslate($text) {
return self::_($text);
}
}
</pre>

Then you'll be able to use this directly in other modules by doing
<pre>
throw new BgaUserException(mygame::totranslate("Translated error from my awesome module file"));
</pre>

Notice how the "totranslate" is also used by the static analysis to detect your string. So the following will not work :
<pre>
$msg = "Translated error from my awesome module file";
throw new BgaUserException(mygame::totranslate($msg));
</pre>

== Analyze your project ==

It looks super complex but there is help!
On studio control panel you can find a button "Check project" - it runs bunch of static analysis on your project including scanning for bad translations and missing translations.
It also will extact all you translation keys as translator will see them so you can double check - and run spell checker on them.

== Other Useful Links ==

* BLOG post about translations https://bga-devs.github.io/blog/posts/translations-summary/

[[Category:Studio]]

Translations

2022-06-06T16:45:43Z

Archduke: /* Formatting on client side */

{{Studio_Framework_Navigation}}

Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.

__TOC__

== Localization Overview ==

Localization for BGA games happens largely on the CLIENT. Games must be developed in English and English strings are sent to the client.

It's only at the client that your English strings will be displayed with the translation for the user's language, when such a translation exists.

For anyone who has worked on a system where translation happens at the server and localized strings are sent to the client: you must unlearn what you have learned. Just stick with English and send the untranslated English strings. The magic happens at the client.

== How will my strings be translated? ==

When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.

Once your game enters Beta, the BGA player community will descend upon your game like a plague of locusts and translate it into dozens of languages before you can say "Je ne parle pas anglais".

== What do I have to do from a programming standpoint? ==

Not as much as you think. Read on for full details, but the golden rules are:

# Make sure that any string on the server side that needs to be translated on the client side is wrapped in a clienttranslate() function when defined. For example: $my_response = clienttranslate('Hey translators, please translate this string'). clienttranslate doesn't actually do anything at all (it just passes the text through) but the translation engine searches your code for strings wrapped in that function and uses them to build the list of strings that need to be translated.
# On the client side, just display your text, but wrap it in _().
## If you pass a string constant to _() - such as _('This is my string') then the parser will automatically detect and add your string to the list of strings that need to be translated, AND it will display the local translation for it when displaying.
## If you pass a variable to _() - such as _(args.my_message) then MAKE SURE that the variable is set to an English string that is either defined somewhere in your PHP code in a clienttranslate() function or somewhere else in your javascript code in a _() function. As long as it is, the translators will provide translations for it, and the _() function will display the local translation of your English string.
# A string used as the message for notifyAllPlayers or notifyPlayer will automatically have its translation displayed on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used as the "description" or "descriptionmyturn" for a state in your state machine will also be automatically translated on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used in the pre-games option screen will also automatically have any translation displayed at the client - you don't need to do anything EXCEPT make sure that it is wrapped in a totranslate() on the server (nota bene: you should not use clienttranslate() here as this file is processed specifically and those strings will not be included in the game translation file but in the main site translation file - with a prefix to keep translations isolated by module - as they have to be translated on main site pages. If you need exactly the same string in your game for a client side translation, it should be declared somewhere else in your code wrapped inside a clienttranslate() to be included in the game translation file.
# A string used in the statistics screen will operate like a string in the pre-game options screen. It will automatically have any translation displayed at the client as long as you make sure that it is wrapped in a totranslate() on the server.
# If you are using parameters for a call to notifyAllPlayers or notifyPlayers, or for a state's "description" or "descriptionmyturn" and those parameters contain text that needs to be translated, you will need to tell the system to display the translated versions of them by using the 'i18n' argument. See below for full details.

== What strings should be translated? ==

Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages.

This does NOT include error messages that are not supposed to happen (unexpected errors).

== What rules should I follow for the original English strings? ==

For a coherent and homogeneous interface, here are some rules about ending a sentence with a final period '.'

* As a general rule:
** If a sentence is displayed isolated in the interface => no final period
** If a sentence is followed or could be followed by another sentence in the same interface space => final period.

* In detail:
** No final period:
*** button labels
*** section titles
*** menu elements
*** links triggering an isolated action
*** anything that is not a full sentence
*** current actions in the status bar
** Final period:
*** complete sentences (e.g., explanations and descriptions) that can be chained with other sentences
** Either a period or no period is acceptable (but this should be consistent throughout the game) for:
*** isolated tooltips / small sentences
*** game logs (no period is usually preferable)
*** error messages (unless there is more than one sentence in the error message; final period is mandatory in this case)

Otherwise, you should try to follow as closely as possible the general style and format (including capitalization) used in the published English rulebook and game materials.

== Focus on translating notifications ==

Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.

However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.

== How to not make translators crazy ;) ==

* Try to reuse the exact same strings (with the same case, etc.) to minimize the number of strings to translate.
** '''Example''': Consider replacing <pre>self::_("Winner")</pre> and <pre>self::_("Winners")</pre> (two strings to translate) with <pre>self::_("Winner(s)")</pre>
** '''Example 2''': <pre>clienttranslate("play a card")</pre> and <pre>clienttranslate("Play a card")</pre> means there will be two strings to translate.
* Do not mark as translatable a game element that does not have to be translated (e.g., if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:
<pre>self::_("First part of the string, ").$argument.' '.self::_("second part of the string")</pre>
Write instead:
<pre>sprintf( self::_("First part of the string, %s second part of the string"), $argument )</pre>
(or the equivalent "dojo.string.substitute" in Javascript)
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The shorter the string is, the more difficult the task is for them. As a rule of thumb, try to avoid short, insignificant strings that require knowledge of their surrounding context. You can also leave a comment on the context of the string in the translation program (English to English) if you are the developer of the game.
* The BGA translation policy is to be flexible on grammar. We prefer to write "player gets 1 coin(s)" rather than write two versions of the same string for plural and singular - it reduces the number of strings to translate.
* Instead of writing elaborate strings like "With the effect of ZZZ, player XXX gains a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".
* Use present tense instead of past. E.g., "player gets wood" instead of "player got wood".
* Avoid using gender-specific wording as much as possible. If needed be aware that [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place, and cannot work if your use "their" as a singular genderless pronoun, as it removes the information that it's singular. E.g., you should write "playerX returns card to *his* hand" or "playerX returns card to *his/her* hand" and not "playerX returns card to *their* hand" as in the 2 first case the system will substitute the proper pronoun his/her/their depending on playerX declared/undeclared gender, but in the second case it will always stay "their" whatever the player preference setting.
* Where two strings are identical apart from (say) a number, use the same string with a ${parameter}, and call format_string_recursive (on the client) or use args (for notifications and state descriptions) to provide the details. But *never* do that for composing multiple sentences with words: other languages have different grammar and it would most likely create untranslatable strings.

== WARNING: Make sure your strings will be translated! ==

For each game, our translation tool does a full scan of the code, looking for translation markers like "_()" or "clienttranslate()". (See below for the full list of translation markers.)

If your original string is not completely contained inside one of these markers, it won't be translated.

<pre>
// Examples: the following strings will be translated:
var mystring_translated = _("my string"); // JS
$mystring_translated = self::_("my string"); // PHP
$mystring_translated = sprintf( self::_("my string with an %s argument"), $argument ); // PHP

// Examples: the following strings WILL NOT be translated:
$my_string = "my string";
$not_translated = self::_( $my_string ); // The original string is not contained within a translator marker => no translation
$not_translated = self::_( sprintf( "my string with a %s argument", $argument ) ); // Ditto
</pre>

== On client side (Javascript) ==

On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.

Examples:
<pre>
// Get a string in player's language:
var translated = _("original english string");

// Get a string in player's language with parameter:
var translated = dojo.string.substitute( _("You can pick ${p} cards and discard ${d}"), {
p: 2,
d: 4
} );
</pre>

'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.

'''ANOTHER WARNING:''' you cannot use this function _() in the javascript object constructor, but you can achieve the same if you use it the setup method

=== Formatting on client side ===

Sometimes you will want to apply some formatting on the client side, but don't want to put HTML tags within the source string (which may be confusing for translators).

This can be achieved with the <code>bga_format</code> function and Markdown-style syntax.

<pre>
/**
* @function bga_format
* Replaces delimiters with HTML tags in translated text
* @param {string} translated string
* @param {Object} map of replacements to make, should be of the form
* {
* '*': (t) => t,
* '_': 'classname',
* }
* keys are delimiters within the translated string
* values are either strings (classname of surrounding span) or function (flexible replacements)
* @returns {string} Returns the original string, with replacements made.
*/
</pre>

Example:
<pre>
// Get a string in player's language:
bga_format(_('You receive a *special* _tile_'), {
'*': (t) => '<b>' + t + '</b>',
'_': 'tile-name'
});
</pre>

The above will return something along the lines of:
<pre>
You receive a <b>special</b> <span class="tile-name">tile</span>
</pre>

Or, if the user is playing in Spanish, for example:
<pre>
Recibes una <span class="tile-name">loseta</span> <b>especial</b>
</pre>

Notes:
* The text passed to <code>bga_format</code> must still be translated using <code>_()</code>, don't forget it!
* The characters available to demarcate formatting are: <code>['-', '*', '+', '?', '.', ',', '\\', '^', '$', '|', '#', ' ']</code>
* If the replacements object is a string, the inner text will be placed within a <code><span></code> tag with the string as a class
* If the replacements object is a function, the inner text will be passed as an argument to the function, and the return value will replace the text and the delimiters

== On server side (PHP) ==

On PHP side, you can use 3 different functions to specify that a string must be translated.

=== Function clienttranslate ===

'''clienttranslate( 'string to translate' ):'''

This function is ''transparent'': it will return the original English string without any change. Its only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.

In general, you use clienttranslate:
* In your '''states.inc.php''', for the fields "description" and "descriptionmyturn".

<pre>
"description" => clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),
</pre>

* In '''material.inc.php''', when defining text for game materials that must be displayed on the client side.

<pre>
$this->card_types = array(

1 => array(
'name' => clienttranslate('Amulet of Air'), // Thus, we can use "_( card_name )" on Javascript side.
</pre>

* When sending a notification with ''notifyAllPlayers'' or ''notifyPlayer'', in the game log string and all game log arguments that need a translation.

<pre>
// A game log string with no argument:
self::notifyAllPlayers( 'pickLibraryCards', clienttranslate('Everyone draw cards from their library'), [] );
</pre>

As a consequence there is no point passing variables to this function. E.g.:

<pre>
notif="foo";
self::notifyAllPlayers( 'log', clienttranslate(notif),[]); // BAD

notif=clienttranslate("foo");
self::notifyAllPlayers( 'log', notif,[]); // GOOD

self::notifyAllPlayers( 'log', clienttranslate("player gains ${num} gems"),[num=>2]); // BAD it is dynamic string enterpreted by php
self::notifyAllPlayers( 'log', clienttranslate('player gains ${num} gems'),[num=>2]); // GOOD, difference is single quotes

self::notifyAllPlayers( 'log', clienttranslate("player gains ".${num}." gems"),[num=>2]); // BAD concatenation

</pre>

Translating arguments is a little bit more complex. This uses the '''i18n''' special argument as below:

<pre>
// In the following example, we translate the game log itself, but also the "card_name" argument:

self::notifyAllPlayers( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'points' => $points,
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.
) );
</pre>

To ensure the translation of the i18n argument will be made, clienttranslate must have been used somewhere, for instance:

<pre>
$this->card_types = array(
...
8 => array(
'name' => clienttranslate("Amulet of Fire"),
...
</pre>

Pay attention when using the '''i18n''' argument when translating arguments for the client: do NOT use same argument for both translations AND key codes for client-side actions (like using 'card_name' to move it on the player board as described in the example). It's pretty obvious in the example, but it can be very tricky when translation is made at the end of the development (which is often the case). Use explicit argument names like 'card_name_translated' by example.

'''WARNING:''' you should NEVER use concatenation with ''clienttranslate'', as it would result in a different string to translate at runtime than the one retrieved statically in the translation system, and so translation would not be applied. If you need to compose a string, use substitution and the i18n parameter (but you also have to pay attention not to compose sentences in a way that is dependent upon the English language specific syntax, or it may be impossible to translate correctly in another language: sometimes, you need multiple full sentences rather than relying on substitution).

=== Method _ (underscore) ===

'''self::_( "my string to translate" ):'''

This function returns a string translated in the language of CURRENT user (i.e. player who send the request to the server) (be careful, this is NOT the active player).

This can be used like self::_('bla') or this->('bla'). You cannot use static underscore function _('bla') in php, it is not the same, it will not translate strings from your game.

The returned string will be surrounded by HTML tags, so you cannot use it in places where pure text is required or your string already has another html markup.

Most of the time, you don't need to translate strings on server side, except on the following situations:
* Throwing user exceptions
* Creating the labels for the game interface used in your template
* Rarely, in your material.inc.php, if for example you need to use some string elements in your exceptions
* Rarely, in your "getAllDatas" PHP method, as the data return by this method is used only by current user

Imporant! This function does two things:
* Mark string for translation
* Translates in runtime
As a consequence you absolutely cannot have $var in there! Or string concatenations.
I.e.
$food=self::_("Banana");// good
self::_("User gives $food to a cat"); // bad
For the translator we will have two strings "Banana" and "User gives $food to a cat", but in runtime we will be
"Banana" and "User gives Banana to a cat" and second string would not match anything. And this is as bad
self::_("User gives ".$food." to a cat");// bad

==== Throwing an exception because the player did a forbidden move ====

<pre>
// This will display a translatable red message to the player that just did some wrong action:
throw new BgaUserException( self::_('You must choose 3 cards') );

// ... notice the use of BgaUserException that signals that this exception is "expected". In theory, all exception that are expected should be translated.
</pre>

==== Creating labels ====

In "yourgame.view.php", when creating the labels for the game interface used in your template (.tpl) file.

<pre>
$this->tpl['CARDS_FOR_YEAR_2'] = self::_("Your cards for year II");
</pre>

'''Nota bene:''' it is recommended to set translated text in your interface client side rather than use template variables and server translation, so that translation works natively in replays (that don't have server side translations). For simple strings, the framework will handle moving the translation client side, but for more complex strings it may not work. In particular, you should not use server side translation for templates with substitution variables (or use the specific function "gameview_str_replace( $search, $replace, $string )" if not possible otherwise or for old code compatibility). Also, you should never use a "to_translate" class in your .tpl as it is used internally by the framework.

Example with view.php:
in .tpl:
<pre>
<div id="empire_title_{COLOR}" class="side_title color_{COLOR}">{EMPIRE_LABEL}</div>
</pre>
in view.php:
$this->page->insert_block("player_board", array ("COLOR" => $color,"PLAYER_NAME" => $name,"PLAYER_NO" => $no,
"PLAYER_ID" => $player_id, "CLASSES" => $own?"own":"",
"EMPIRE_LABEL" => self::raw(gameview_str_replace('${player_name}', $name, self::_('${player_name}\'s EMPIRE')))
));
Example with client side:
in .tpl:
<pre>
<div id="empire_title_{COLOR}" class="side_title color_{COLOR}">Stub</div>
</pre>
in .js:
<pre>
for (var player_id in this.gamedatas.players) {
var player_color = this.gamedatas.players[player_id].color;
var player_name = this.gamedatas.players[player_id].name;
$('empire_title_'+player_color).innerHTML=this.format_string_recursive(_("${player_name}'s EMPIRE"), {player_name: player_name});
}
</pre>

==== Translating strings in material file ====

Rarely, in your material.inc.php, if for example you need to use some string elements in your exceptions.

<pre>
// In material.inc.php, $this->energies[n]['nametr'] has been created with the self::_() method. Now we can do this:
throw new BgaUserException( self::_("To execute this action you need more: ").' '.$this->energies[$resource_id]['nametr'] );
</pre>

Note: you could also do this, so you don't need to pollute your material file
throw new BgaUserException( self::_("To execute this action you need more: ").' '.self::_($this->energies[$resource_id]['name']) );

where $this->energies[$resource_id]['name'] were marked in material file using regular clienttranslate function
<pre>
$this->energies = [
22 => [
'name' => clienttranslate('Sun')
...
]
];
</pre>

==== Strings in getAllDatas ====

Rarely, in your "getAllDatas" PHP method, as the data return by this method is used only by current user.

Note: not sure why would you send strings from the server in this case, as same can be achieved on the client usually.

=== Function totranslate ===

'''totranslate( "my string to translate" ):'''

This function works exactly like 'clienttranslate', except it tells BGA that the string is not needed on client side.

You should not use this function, except on the following cases:
* Statistics name in stats.inc.php
* Option names and option values name in gameoptions.inc.php

== Top Secret Undocumented Features ==

If your string contains the clause '$${value}' (such as 'You gain $${value}.') then the translation system seems to move the position of the $ to a localized location (eg $5 in English but 5$ in French). This only seems to occur when using the argument 'value'.

In JavaScript, you can get the current user's language by retrieving the translation for the special string "$locale":

var lang = _('$locale'); // en, fr, etc.

== On server side - advanced (PHP) ==

If you want to use translation system in your custom static modules, you will first need to expose the _() function :
<pre>
class mygame extends Table {
// Exposing protected method translation
public static function totranslate($text) {
return self::_($text);
}
}
</pre>

Then you'll be able to use this directly in other modules by doing
<pre>
throw new BgaUserException(mygame::totranslate("Translated error from my awesome module file"));
</pre>

Notice how the "totranslate" is also used by the static analysis to detect your string. So the following will not work :
<pre>
$msg = "Translated error from my awesome module file";
throw new BgaUserException(mygame::totranslate($msg));
</pre>

== Analyze your project ==

It looks super complex but there is help!
On studio control panel you can find a button "Check project" - it runs bunch of static analysis on your project including scanning for bad translations and missing translations.
It also will extact all you translation keys as translator will see them so you can double check - and run spell checker on them.

== Other Useful Links ==

* BLOG post about translations https://bga-devs.github.io/blog/posts/translations-summary/

[[Category:Studio]]

Translations

2022-06-06T16:44:38Z

Archduke: /* Formatting on client side */

{{Studio_Framework_Navigation}}

Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.

__TOC__

== Localization Overview ==

Localization for BGA games happens largely on the CLIENT. Games must be developed in English and English strings are sent to the client.

It's only at the client that your English strings will be displayed with the translation for the user's language, when such a translation exists.

For anyone who has worked on a system where translation happens at the server and localized strings are sent to the client: you must unlearn what you have learned. Just stick with English and send the untranslated English strings. The magic happens at the client.

== How will my strings be translated? ==

When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.

Once your game enters Beta, the BGA player community will descend upon your game like a plague of locusts and translate it into dozens of languages before you can say "Je ne parle pas anglais".

== What do I have to do from a programming standpoint? ==

Not as much as you think. Read on for full details, but the golden rules are:

# Make sure that any string on the server side that needs to be translated on the client side is wrapped in a clienttranslate() function when defined. For example: $my_response = clienttranslate('Hey translators, please translate this string'). clienttranslate doesn't actually do anything at all (it just passes the text through) but the translation engine searches your code for strings wrapped in that function and uses them to build the list of strings that need to be translated.
# On the client side, just display your text, but wrap it in _().
## If you pass a string constant to _() - such as _('This is my string') then the parser will automatically detect and add your string to the list of strings that need to be translated, AND it will display the local translation for it when displaying.
## If you pass a variable to _() - such as _(args.my_message) then MAKE SURE that the variable is set to an English string that is either defined somewhere in your PHP code in a clienttranslate() function or somewhere else in your javascript code in a _() function. As long as it is, the translators will provide translations for it, and the _() function will display the local translation of your English string.
# A string used as the message for notifyAllPlayers or notifyPlayer will automatically have its translation displayed on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used as the "description" or "descriptionmyturn" for a state in your state machine will also be automatically translated on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used in the pre-games option screen will also automatically have any translation displayed at the client - you don't need to do anything EXCEPT make sure that it is wrapped in a totranslate() on the server (nota bene: you should not use clienttranslate() here as this file is processed specifically and those strings will not be included in the game translation file but in the main site translation file - with a prefix to keep translations isolated by module - as they have to be translated on main site pages. If you need exactly the same string in your game for a client side translation, it should be declared somewhere else in your code wrapped inside a clienttranslate() to be included in the game translation file.
# A string used in the statistics screen will operate like a string in the pre-game options screen. It will automatically have any translation displayed at the client as long as you make sure that it is wrapped in a totranslate() on the server.
# If you are using parameters for a call to notifyAllPlayers or notifyPlayers, or for a state's "description" or "descriptionmyturn" and those parameters contain text that needs to be translated, you will need to tell the system to display the translated versions of them by using the 'i18n' argument. See below for full details.

== What strings should be translated? ==

Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages.

This does NOT include error messages that are not supposed to happen (unexpected errors).

== What rules should I follow for the original English strings? ==

For a coherent and homogeneous interface, here are some rules about ending a sentence with a final period '.'

* As a general rule:
** If a sentence is displayed isolated in the interface => no final period
** If a sentence is followed or could be followed by another sentence in the same interface space => final period.

* In detail:
** No final period:
*** button labels
*** section titles
*** menu elements
*** links triggering an isolated action
*** anything that is not a full sentence
*** current actions in the status bar
** Final period:
*** complete sentences (e.g., explanations and descriptions) that can be chained with other sentences
** Either a period or no period is acceptable (but this should be consistent throughout the game) for:
*** isolated tooltips / small sentences
*** game logs (no period is usually preferable)
*** error messages (unless there is more than one sentence in the error message; final period is mandatory in this case)

Otherwise, you should try to follow as closely as possible the general style and format (including capitalization) used in the published English rulebook and game materials.

== Focus on translating notifications ==

Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.

However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.

== How to not make translators crazy ;) ==

* Try to reuse the exact same strings (with the same case, etc.) to minimize the number of strings to translate.
** '''Example''': Consider replacing <pre>self::_("Winner")</pre> and <pre>self::_("Winners")</pre> (two strings to translate) with <pre>self::_("Winner(s)")</pre>
** '''Example 2''': <pre>clienttranslate("play a card")</pre> and <pre>clienttranslate("Play a card")</pre> means there will be two strings to translate.
* Do not mark as translatable a game element that does not have to be translated (e.g., if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:
<pre>self::_("First part of the string, ").$argument.' '.self::_("second part of the string")</pre>
Write instead:
<pre>sprintf( self::_("First part of the string, %s second part of the string"), $argument )</pre>
(or the equivalent "dojo.string.substitute" in Javascript)
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The shorter the string is, the more difficult the task is for them. As a rule of thumb, try to avoid short, insignificant strings that require knowledge of their surrounding context. You can also leave a comment on the context of the string in the translation program (English to English) if you are the developer of the game.
* The BGA translation policy is to be flexible on grammar. We prefer to write "player gets 1 coin(s)" rather than write two versions of the same string for plural and singular - it reduces the number of strings to translate.
* Instead of writing elaborate strings like "With the effect of ZZZ, player XXX gains a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".
* Use present tense instead of past. E.g., "player gets wood" instead of "player got wood".
* Avoid using gender-specific wording as much as possible. If needed be aware that [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place, and cannot work if your use "their" as a singular genderless pronoun, as it removes the information that it's singular. E.g., you should write "playerX returns card to *his* hand" or "playerX returns card to *his/her* hand" and not "playerX returns card to *their* hand" as in the 2 first case the system will substitute the proper pronoun his/her/their depending on playerX declared/undeclared gender, but in the second case it will always stay "their" whatever the player preference setting.
* Where two strings are identical apart from (say) a number, use the same string with a ${parameter}, and call format_string_recursive (on the client) or use args (for notifications and state descriptions) to provide the details. But *never* do that for composing multiple sentences with words: other languages have different grammar and it would most likely create untranslatable strings.

== WARNING: Make sure your strings will be translated! ==

For each game, our translation tool does a full scan of the code, looking for translation markers like "_()" or "clienttranslate()". (See below for the full list of translation markers.)

If your original string is not completely contained inside one of these markers, it won't be translated.

<pre>
// Examples: the following strings will be translated:
var mystring_translated = _("my string"); // JS
$mystring_translated = self::_("my string"); // PHP
$mystring_translated = sprintf( self::_("my string with an %s argument"), $argument ); // PHP

// Examples: the following strings WILL NOT be translated:
$my_string = "my string";
$not_translated = self::_( $my_string ); // The original string is not contained within a translator marker => no translation
$not_translated = self::_( sprintf( "my string with a %s argument", $argument ) ); // Ditto
</pre>

== On client side (Javascript) ==

On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.

Examples:
<pre>
// Get a string in player's language:
var translated = _("original english string");

// Get a string in player's language with parameter:
var translated = dojo.string.substitute( _("You can pick ${p} cards and discard ${d}"), {
p: 2,
d: 4
} );
</pre>

'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.

'''ANOTHER WARNING:''' you cannot use this function _() in the javascript object constructor, but you can achieve the same if you use it the setup method

=== Formatting on client side ===

Sometimes you will want to apply some formatting on the client side, but don't want to put HTML tags within the source string (which may be confusing for translators).

This can be achieved with the <code>bga_format</code> function and Markdown-style syntax.

<pre>
/**
* @function bga_format
* Replaces delimiters with HTML tags in translated text
* @param {string} translated string
* @param {Object} map of replacements to make, should be of the form
* {
* '*': (t) => t,
* '_': 'classname',
* }
* keys are delimiters within the translated string
* values are either strings (classname of surrounding span) or function (flexible replacements)
* @returns {string} Returns the original string, with replacements made.
*/
</pre>

Example:
<pre>
// Get a string in player's language:
bga_format(_('You receive a *special* _tile_'), {
'*': (t) => '<b>' + t + '</b>',
'_': 'tile-name'
});
</pre>

The above will return something along the lines of:
<pre>
You receive a <b>special</b> <span class="tile-name">tile</span>
</pre>

Or, if the user is playing in Spanish, for example:
<pre>
Recibes una <span class="tile-name">loseta</span> <b>especial</b>
</pre>

Notes:
* The text passed to <code>bga_format</code> must still be translated using <code>_()</code>, don't forget it!
* The characters available to demarcate formatting are: <code>['-', '*', '+', '?', '.', ',', '\\', '^', '$', '|', '#', ' ']</code>
* If the replacements object is a string, the inner text will be placed within a `\<span\>` tag with the string as a class
* If the replacements object is a function, the inner text will be passed as an argument to the function, and the return value will replace the text and the delimiters

== On server side (PHP) ==

On PHP side, you can use 3 different functions to specify that a string must be translated.

=== Function clienttranslate ===

'''clienttranslate( 'string to translate' ):'''

This function is ''transparent'': it will return the original English string without any change. Its only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.

In general, you use clienttranslate:
* In your '''states.inc.php''', for the fields "description" and "descriptionmyturn".

<pre>
"description" => clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),
</pre>

* In '''material.inc.php''', when defining text for game materials that must be displayed on the client side.

<pre>
$this->card_types = array(

1 => array(
'name' => clienttranslate('Amulet of Air'), // Thus, we can use "_( card_name )" on Javascript side.
</pre>

* When sending a notification with ''notifyAllPlayers'' or ''notifyPlayer'', in the game log string and all game log arguments that need a translation.

<pre>
// A game log string with no argument:
self::notifyAllPlayers( 'pickLibraryCards', clienttranslate('Everyone draw cards from their library'), [] );
</pre>

As a consequence there is no point passing variables to this function. E.g.:

<pre>
notif="foo";
self::notifyAllPlayers( 'log', clienttranslate(notif),[]); // BAD

notif=clienttranslate("foo");
self::notifyAllPlayers( 'log', notif,[]); // GOOD

self::notifyAllPlayers( 'log', clienttranslate("player gains ${num} gems"),[num=>2]); // BAD it is dynamic string enterpreted by php
self::notifyAllPlayers( 'log', clienttranslate('player gains ${num} gems'),[num=>2]); // GOOD, difference is single quotes

self::notifyAllPlayers( 'log', clienttranslate("player gains ".${num}." gems"),[num=>2]); // BAD concatenation

</pre>

Translating arguments is a little bit more complex. This uses the '''i18n''' special argument as below:

<pre>
// In the following example, we translate the game log itself, but also the "card_name" argument:

self::notifyAllPlayers( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'points' => $points,
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.
) );
</pre>

To ensure the translation of the i18n argument will be made, clienttranslate must have been used somewhere, for instance:

<pre>
$this->card_types = array(
...
8 => array(
'name' => clienttranslate("Amulet of Fire"),
...
</pre>

Pay attention when using the '''i18n''' argument when translating arguments for the client: do NOT use same argument for both translations AND key codes for client-side actions (like using 'card_name' to move it on the player board as described in the example). It's pretty obvious in the example, but it can be very tricky when translation is made at the end of the development (which is often the case). Use explicit argument names like 'card_name_translated' by example.

'''WARNING:''' you should NEVER use concatenation with ''clienttranslate'', as it would result in a different string to translate at runtime than the one retrieved statically in the translation system, and so translation would not be applied. If you need to compose a string, use substitution and the i18n parameter (but you also have to pay attention not to compose sentences in a way that is dependent upon the English language specific syntax, or it may be impossible to translate correctly in another language: sometimes, you need multiple full sentences rather than relying on substitution).

=== Method _ (underscore) ===

'''self::_( "my string to translate" ):'''

This function returns a string translated in the language of CURRENT user (i.e. player who send the request to the server) (be careful, this is NOT the active player).

This can be used like self::_('bla') or this->('bla'). You cannot use static underscore function _('bla') in php, it is not the same, it will not translate strings from your game.

The returned string will be surrounded by HTML tags, so you cannot use it in places where pure text is required or your string already has another html markup.

Most of the time, you don't need to translate strings on server side, except on the following situations:
* Throwing user exceptions
* Creating the labels for the game interface used in your template
* Rarely, in your material.inc.php, if for example you need to use some string elements in your exceptions
* Rarely, in your "getAllDatas" PHP method, as the data return by this method is used only by current user

Imporant! This function does two things:
* Mark string for translation
* Translates in runtime
As a consequence you absolutely cannot have $var in there! Or string concatenations.
I.e.
$food=self::_("Banana");// good
self::_("User gives $food to a cat"); // bad
For the translator we will have two strings "Banana" and "User gives $food to a cat", but in runtime we will be
"Banana" and "User gives Banana to a cat" and second string would not match anything. And this is as bad
self::_("User gives ".$food." to a cat");// bad

==== Throwing an exception because the player did a forbidden move ====

<pre>
// This will display a translatable red message to the player that just did some wrong action:
throw new BgaUserException( self::_('You must choose 3 cards') );

// ... notice the use of BgaUserException that signals that this exception is "expected". In theory, all exception that are expected should be translated.
</pre>

==== Creating labels ====

In "yourgame.view.php", when creating the labels for the game interface used in your template (.tpl) file.

<pre>
$this->tpl['CARDS_FOR_YEAR_2'] = self::_("Your cards for year II");
</pre>

'''Nota bene:''' it is recommended to set translated text in your interface client side rather than use template variables and server translation, so that translation works natively in replays (that don't have server side translations). For simple strings, the framework will handle moving the translation client side, but for more complex strings it may not work. In particular, you should not use server side translation for templates with substitution variables (or use the specific function "gameview_str_replace( $search, $replace, $string )" if not possible otherwise or for old code compatibility). Also, you should never use a "to_translate" class in your .tpl as it is used internally by the framework.

Example with view.php:
in .tpl:
<pre>
<div id="empire_title_{COLOR}" class="side_title color_{COLOR}">{EMPIRE_LABEL}</div>
</pre>
in view.php:
$this->page->insert_block("player_board", array ("COLOR" => $color,"PLAYER_NAME" => $name,"PLAYER_NO" => $no,
"PLAYER_ID" => $player_id, "CLASSES" => $own?"own":"",
"EMPIRE_LABEL" => self::raw(gameview_str_replace('${player_name}', $name, self::_('${player_name}\'s EMPIRE')))
));
Example with client side:
in .tpl:
<pre>
<div id="empire_title_{COLOR}" class="side_title color_{COLOR}">Stub</div>
</pre>
in .js:
<pre>
for (var player_id in this.gamedatas.players) {
var player_color = this.gamedatas.players[player_id].color;
var player_name = this.gamedatas.players[player_id].name;
$('empire_title_'+player_color).innerHTML=this.format_string_recursive(_("${player_name}'s EMPIRE"), {player_name: player_name});
}
</pre>

==== Translating strings in material file ====

Rarely, in your material.inc.php, if for example you need to use some string elements in your exceptions.

<pre>
// In material.inc.php, $this->energies[n]['nametr'] has been created with the self::_() method. Now we can do this:
throw new BgaUserException( self::_("To execute this action you need more: ").' '.$this->energies[$resource_id]['nametr'] );
</pre>

Note: you could also do this, so you don't need to pollute your material file
throw new BgaUserException( self::_("To execute this action you need more: ").' '.self::_($this->energies[$resource_id]['name']) );

where $this->energies[$resource_id]['name'] were marked in material file using regular clienttranslate function
<pre>
$this->energies = [
22 => [
'name' => clienttranslate('Sun')
...
]
];
</pre>

==== Strings in getAllDatas ====

Rarely, in your "getAllDatas" PHP method, as the data return by this method is used only by current user.

Note: not sure why would you send strings from the server in this case, as same can be achieved on the client usually.

=== Function totranslate ===

'''totranslate( "my string to translate" ):'''

This function works exactly like 'clienttranslate', except it tells BGA that the string is not needed on client side.

You should not use this function, except on the following cases:
* Statistics name in stats.inc.php
* Option names and option values name in gameoptions.inc.php

== Top Secret Undocumented Features ==

If your string contains the clause '$${value}' (such as 'You gain $${value}.') then the translation system seems to move the position of the $ to a localized location (eg $5 in English but 5$ in French). This only seems to occur when using the argument 'value'.

In JavaScript, you can get the current user's language by retrieving the translation for the special string "$locale":

var lang = _('$locale'); // en, fr, etc.

== On server side - advanced (PHP) ==

If you want to use translation system in your custom static modules, you will first need to expose the _() function :
<pre>
class mygame extends Table {
// Exposing protected method translation
public static function totranslate($text) {
return self::_($text);
}
}
</pre>

Then you'll be able to use this directly in other modules by doing
<pre>
throw new BgaUserException(mygame::totranslate("Translated error from my awesome module file"));
</pre>

Notice how the "totranslate" is also used by the static analysis to detect your string. So the following will not work :
<pre>
$msg = "Translated error from my awesome module file";
throw new BgaUserException(mygame::totranslate($msg));
</pre>

== Analyze your project ==

It looks super complex but there is help!
On studio control panel you can find a button "Check project" - it runs bunch of static analysis on your project including scanning for bad translations and missing translations.
It also will extact all you translation keys as translator will see them so you can double check - and run spell checker on them.

== Other Useful Links ==

* BLOG post about translations https://bga-devs.github.io/blog/posts/translations-summary/

[[Category:Studio]]

File:Title guidelines.png

2022-06-02T10:17:39Z

Archduke:

Template:Studio Framework Navigation

2022-05-04T10:45:29Z

Archduke:

<div class="studio-framework-navigation" style="float: right; width: 300px; border: solid #000 1px; padding: 1em; margin-left: 1em; background: #fff;">

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game File Reference'''</center></div>

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''[[Studio file reference|Overview]]'''</center></div>

* [[Game database model: dbmodel.sql|<b>dbmodel.sql</b>]] - database model
* [[Game meta-information: gameinfos.inc.php|<b>gameinfos.inc.php</b>]] - meta-information
* [[Game options and preferences: gameoptions.inc.php|<b>gameoptions.inc.php</b>]] - game options & user preferences
* [[Game art: img directory|<b>img/</b>]] - game art
* [[Game_metadata_manager|<b>Game Metadata Manager</b>]] - tags and metadata media
* [[Game material description: material.inc.php|<b>material.inc.php</b>]] - static data
* <b>misc/</b> - studio-only storage
* <b>modules/</b> - additional game code
* [[Your game state machine: states.inc.php|<b>states.inc.php</b>]] - state machine
* [[Game statistics: stats.inc.php|<b>stats.inc.php</b>]] - statistics
* [[Players actions: yourgamename.action.php|X.<b>action.php</b>]] - player actions
* [[Game interface stylesheet: yourgamename.css|X<b>.css</b>]] - interface stylesheet
* [[Main game logic: yourgamename.game.php|X.<b>game.php</b>]] - main logic
* [[Game interface logic: yourgamename.js|X.<b>js</b>]] - interface logic
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X.<b>view.php</b>]] - dynamic game layout
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X_X.<b>tpl</b>]] - static game layout
<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Useful Components'''</center></div>

'''Official'''

* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
* [[Draggable]]: a JS component to manage drag'n'drop actions.
* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.
* [[Zone]]: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).

Undocumented component (if somebody knows please help with docs)
* [[Wrapper]]: a JS component to wrap a <div> element around its child, even if these elements are absolute positioned.

'''Unofficial'''

* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks
* [[Some usual board game elements image ressources]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game Development Process'''</center></div>

* [[First steps with BGA Studio]]
* [[Create a game in BGA Studio: Complete Walkthrough]]
* [[Tutorial reversi]]
* [[Tutorial gomoku]]
* [[Tutorial hearts]]
* [[BGA Studio Guidelines]]
* [[BGA game Lifecycle]]
* [[Pre-release checklist]]
* [[Post-release phase]]
* [[Help|Player Resources]] - add player help/rules to your game page

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Guides for Common Topics'''</center></div>

* [[Translations]] - make your game translatable
* [[Game replay|Game Replay]]
* [[Your game mobile version|Mobile Users]]
* [[3D]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Miscellaneous Resources'''</center></div>

* [[Studio FAQ]]
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment
* [[Studio logs]] - Instructions for log access
* [[Practical debugging]] - Tips focused on debugging
* [[Troubleshooting]] - Most common "I am really stuck" situations
* [https://studio.boardgamearena.com/bugs Studio Bugs] - Reports against Studio itself (not BGA!)
</div>

Template:Studio Framework Navigation

2022-05-04T10:45:12Z

Archduke:

<div class="studio-framework-navigation" style="float: right; width: 300px; border: solid #000 1px; padding: 1em; margin-left: 1em; background: #fff;">

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game File Reference'''</center></div>

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''[[Studio file reference|Overview]]'''</center></div>

* [[Game database model: dbmodel.sql|<b>dbmodel.sql</b>]] - database model
* [[Game meta-information: gameinfos.inc.php|<b>gameinfos.inc.php</b>]] - meta-information
* [[Game options and preferences: gameoptions.inc.php|<b>gameoptions.inc.php</b>]] - game options & user preferences
* [[Game art: img directory|<b>img/</b>]] - game art
* [[Game_metadata_manager|Game Metadata Manager]] - tags and metadata media
* [[Game material description: material.inc.php|<b>material.inc.php</b>]] - static data
* <b>misc/</b> - studio-only storage
* <b>modules/</b> - additional game code
* [[Your game state machine: states.inc.php|<b>states.inc.php</b>]] - state machine
* [[Game statistics: stats.inc.php|<b>stats.inc.php</b>]] - statistics
* [[Players actions: yourgamename.action.php|X.<b>action.php</b>]] - player actions
* [[Game interface stylesheet: yourgamename.css|X<b>.css</b>]] - interface stylesheet
* [[Main game logic: yourgamename.game.php|X.<b>game.php</b>]] - main logic
* [[Game interface logic: yourgamename.js|X.<b>js</b>]] - interface logic
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X.<b>view.php</b>]] - dynamic game layout
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X_X.<b>tpl</b>]] - static game layout
<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Useful Components'''</center></div>

'''Official'''

* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
* [[Draggable]]: a JS component to manage drag'n'drop actions.
* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.
* [[Zone]]: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).

Undocumented component (if somebody knows please help with docs)
* [[Wrapper]]: a JS component to wrap a <div> element around its child, even if these elements are absolute positioned.

'''Unofficial'''

* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks
* [[Some usual board game elements image ressources]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game Development Process'''</center></div>

* [[First steps with BGA Studio]]
* [[Create a game in BGA Studio: Complete Walkthrough]]
* [[Tutorial reversi]]
* [[Tutorial gomoku]]
* [[Tutorial hearts]]
* [[BGA Studio Guidelines]]
* [[BGA game Lifecycle]]
* [[Pre-release checklist]]
* [[Post-release phase]]
* [[Help|Player Resources]] - add player help/rules to your game page

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Guides for Common Topics'''</center></div>

* [[Translations]] - make your game translatable
* [[Game replay|Game Replay]]
* [[Your game mobile version|Mobile Users]]
* [[3D]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Miscellaneous Resources'''</center></div>

* [[Studio FAQ]]
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment
* [[Studio logs]] - Instructions for log access
* [[Practical debugging]] - Tips focused on debugging
* [[Troubleshooting]] - Most common "I am really stuck" situations
* [https://studio.boardgamearena.com/bugs Studio Bugs] - Reports against Studio itself (not BGA!)
</div>

File:Game Metadata Manager Icon.png

2022-05-03T15:24:34Z

Archduke:

File:Carcassonne Banner.jpg

2022-05-03T13:53:34Z

Archduke:

File:Carcassonne Icon.png

2022-05-03T13:52:56Z

Archduke:

File:Carcassonne Box.png

2022-05-03T13:51:53Z

Archduke:

File:Carcassonne Title.png

2022-05-03T13:49:04Z

Archduke:

Template:Studio Framework Navigation

2022-05-03T10:17:02Z

Archduke:

<div class="studio-framework-navigation" style="float: right; width: 300px; border: solid #000 1px; padding: 1em; margin-left: 1em; background: #fff;">

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game File Reference'''</center></div>

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''[[Studio file reference|Overview]]'''</center></div>

* [[Game database model: dbmodel.sql|<b>dbmodel.sql</b>]] - database model
* [[Game meta-information: gameinfos.inc.php|<b>gameinfos.inc.php</b>]] - meta-information
* [[Game options and preferences: gameoptions.inc.php|<b>gameoptions.inc.php</b>]] - game options & user preferences
* [[Game art: img directory|<b>img/</b>]] - game art
* [[Game material description: material.inc.php|<b>material.inc.php</b>]] - static data
* <b>misc/</b> - studio-only storage
* <b>modules/</b> - additional game code
* [[Your game state machine: states.inc.php|<b>states.inc.php</b>]] - state machine
* [[Game statistics: stats.inc.php|<b>stats.inc.php</b>]] - statistics
* [[Players actions: yourgamename.action.php|X.<b>action.php</b>]] - player actions
* [[Game interface stylesheet: yourgamename.css|X<b>.css</b>]] - interface stylesheet
* [[Main game logic: yourgamename.game.php|X.<b>game.php</b>]] - main logic
* [[Game interface logic: yourgamename.js|X.<b>js</b>]] - interface logic
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X.<b>view.php</b>]] - dynamic game layout
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X_X.<b>tpl</b>]] - static game layout
<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Useful Components'''</center></div>

'''Official'''

* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
* [[Draggable]]: a JS component to manage drag'n'drop actions.
* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.
* [[Zone]]: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).

Undocumented component (if somebody knows please help with docs)
* [[Wrapper]]: a JS component to wrap a <div> element around its child, even if these elements are absolute positioned.

'''Unofficial'''

* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks
* [[Some usual board game elements image ressources]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game Development Process'''</center></div>

* [[First steps with BGA Studio]]
* [[Create a game in BGA Studio: Complete Walkthrough]]
* [[Tutorial reversi]]
* [[Tutorial gomoku]]
* [[Tutorial hearts]]
* [[BGA Studio Guidelines]]
* [[BGA game Lifecycle]]
* [[Pre-release checklist]]
* [[Post-release phase]]
* [[Help|Player Resources]] - add player help/rules to your game page

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Guides for Common Topics'''</center></div>

* [[Translations]] - make your game translatable
* [[Game replay|Game Replay]]
* [[Your game mobile version|Mobile Users]]
* [[3D]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Miscellaneous Resources'''</center></div>

* [[Studio FAQ]]
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment
* [[Studio logs]] - Instructions for log access
* [[Practical debugging]] - Tips focused on debugging
* [[Troubleshooting]] - Most common "I am really stuck" situations
* [https://studio.boardgamearena.com/bugs Studio Bugs] - Reports against Studio itself (not BGA!)
</div>

Template:Studio Framework Navigation

2022-05-03T10:16:40Z

Archduke:

<div class="studio-framework-navigation" style="float: right; width: 300px; border: solid #000 1px; padding: 1em; margin-left: 1em; background: #fff;">

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game File Reference'''</center></div>

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''[[Studio file reference|Overview]]'''</center></div>

* [[Game database model: dbmodel.sql|<b>dbmodel.sql</b>]] - database model
* [[Game meta-information: gameinfos.inc.php|<b>gameinfos.inc.php</b>]] - meta-information
* [[Game options and preferences: gameoptions.inc.php|<b>gameoptions.inc.php</b>]] - game options & user preferences
* [[Game art: img directory|<b>img/</b>]] - game art
* [[Game material description: material.inc.php|<b>material.inc.php</b>]] - static data
* <b>misc/</b> - studio-only storage
* <b>modules/</b> - additional game code
* [[Your game state machine: states.inc.php|<b>states.inc.php</b>]] - state machine
* [[Game statistics: stats.inc.php|<b>stats.inc.php</b>]] - statistics
* [[Players actions: yourgamename.action.php|X.<b>action.php</b>]] - player actions
* [[Game interface stylesheet: yourgamename.css|X<b>.css</b>]] - interface stylesheet
* [[Main game logic: yourgamename.game.php|X.<b>game.php</b>]] - main logic
* [[Game interface logic: yourgamename.js|X.<b>js</b>]] - interface logic
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X.<b>view.php</b>]] - dynamic game layout
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X_X.<b>tpl</b>]] - static game layout
<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Useful Components'''</center></div>

'''Official'''

* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
* [[Draggable]]: a JS component to manage drag'n'drop actions.
* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.
* [[Zone]]: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).

Undocumented component (if somebody knows please help with docs)
* [[Wrapper]]: a JS component to wrap a <div> element around its child, even if these elements are absolute positioned.

'''Unofficial'''

* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks
* [[Some usual board game elements image ressources]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game Development Process'''</center></div>

* [[First steps with BGA Studio]]
* [[Create a game in BGA Studio: Complete Walkthrough]]
* [[Tutorial reversi]]
* [[Tutorial gomoku]]
* [[Tutorial hearts]]
* [[BGA Studio Guidelines]]
* [[BGA game Lifecycle]]
* [[Pre-release checklist]]
* [[Post-release phase]]
* [[Help|Player Resources]] - add player help/rules to your game page

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Guides for Common Topics'''</center></div>

* [[Translations]] - make your game translatable
* [[Game replay|Game Replay]]
* [[Your game mobile version|Mobile Users]]
* [[3D]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Miscellaneous Resources'''</center></div>

* [[Studio FAQ]]
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment
* [[Studio logs]] - Instructions for log access
* [[Practical debugging]] - Tips focused on debugging
* [[Troubleshooting]] - Most common "I am really stuck" situations
* [https://studio.boardgamearena.com/bugs Studio Bugs] - Reports against Studio itself (not BGA!)
</div>

__TOC__

Template:Studio Framework Navigation

2022-05-03T10:16:20Z

Archduke:

__TOC__
<div class="studio-framework-navigation" style="float: right; width: 300px; border: solid #000 1px; padding: 1em; margin-left: 1em; background: #fff;">

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game File Reference'''</center></div>

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''[[Studio file reference|Overview]]'''</center></div>

* [[Game database model: dbmodel.sql|<b>dbmodel.sql</b>]] - database model
* [[Game meta-information: gameinfos.inc.php|<b>gameinfos.inc.php</b>]] - meta-information
* [[Game options and preferences: gameoptions.inc.php|<b>gameoptions.inc.php</b>]] - game options & user preferences
* [[Game art: img directory|<b>img/</b>]] - game art
* [[Game material description: material.inc.php|<b>material.inc.php</b>]] - static data
* <b>misc/</b> - studio-only storage
* <b>modules/</b> - additional game code
* [[Your game state machine: states.inc.php|<b>states.inc.php</b>]] - state machine
* [[Game statistics: stats.inc.php|<b>stats.inc.php</b>]] - statistics
* [[Players actions: yourgamename.action.php|X.<b>action.php</b>]] - player actions
* [[Game interface stylesheet: yourgamename.css|X<b>.css</b>]] - interface stylesheet
* [[Main game logic: yourgamename.game.php|X.<b>game.php</b>]] - main logic
* [[Game interface logic: yourgamename.js|X.<b>js</b>]] - interface logic
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X.<b>view.php</b>]] - dynamic game layout
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X_X.<b>tpl</b>]] - static game layout
<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Useful Components'''</center></div>

'''Official'''

* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
* [[Draggable]]: a JS component to manage drag'n'drop actions.
* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.
* [[Zone]]: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).

Undocumented component (if somebody knows please help with docs)
* [[Wrapper]]: a JS component to wrap a <div> element around its child, even if these elements are absolute positioned.

'''Unofficial'''

* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks
* [[Some usual board game elements image ressources]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game Development Process'''</center></div>

* [[First steps with BGA Studio]]
* [[Create a game in BGA Studio: Complete Walkthrough]]
* [[Tutorial reversi]]
* [[Tutorial gomoku]]
* [[Tutorial hearts]]
* [[BGA Studio Guidelines]]
* [[BGA game Lifecycle]]
* [[Pre-release checklist]]
* [[Post-release phase]]
* [[Help|Player Resources]] - add player help/rules to your game page

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Guides for Common Topics'''</center></div>

* [[Translations]] - make your game translatable
* [[Game replay|Game Replay]]
* [[Your game mobile version|Mobile Users]]
* [[3D]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Miscellaneous Resources'''</center></div>

* [[Studio FAQ]]
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment
* [[Studio logs]] - Instructions for log access
* [[Practical debugging]] - Tips focused on debugging
* [[Troubleshooting]] - Most common "I am really stuck" situations
* [https://studio.boardgamearena.com/bugs Studio Bugs] - Reports against Studio itself (not BGA!)
</div>

Studio

2022-05-03T10:15:21Z

Archduke: Add TOC

{{Studio_Framework_Navigation}}

[[File:Bga_studio_small.jpg]]

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

__TOC__

== What is Board Game Arena Studio? ==

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

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

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

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

== Discover BGA Studio in 5 presentations ==

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

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

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

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

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

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

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

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

Then start editing files and see what happens! ;)

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

If you have any questions, please check out the '''[[Studio FAQ]]''' first, then if you didn't find the answer you were looking for, please post your question on the [http://forum.boardgamearena.com/viewforum.php?f=12 '''development forum'''].

== BGA Studio documentation ==

=== BGA Studio Framework reference ===

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

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

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

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

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

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

==== Other components ====

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

=== BGA Studio game components reference ===

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

JS:

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

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

Reference for classes in game class hierarchy

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

=== BGA Studio user guide ===

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

Lifecycle

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

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

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

== Other resources ==

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

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

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

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

[[Contact BGA Studio]]

== Software Versions ==

Versions currently used by BGA framework:

* Dojo Toolkit 1.15
* PHP: 7.4
* SQL: MySQL 5.7
* JS/CSS/HTML: limited by what minimization tools support [[Game_interface_logic:_yourgamename.js#Javascript_minimization_.28after_July_2020.29]]
* Font Awesome: 4.7 https://fontawesome.com/v4.7/icons/

Template:Studio Framework Navigation

2022-05-03T10:14:54Z

Archduke:

__NOTOC__
<div class="studio-framework-navigation" style="float: right; width: 300px; border: solid #000 1px; padding: 1em; margin-left: 1em; background: #fff;">

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game File Reference'''</center></div>

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''[[Studio file reference|Overview]]'''</center></div>

* [[Game database model: dbmodel.sql|<b>dbmodel.sql</b>]] - database model
* [[Game meta-information: gameinfos.inc.php|<b>gameinfos.inc.php</b>]] - meta-information
* [[Game options and preferences: gameoptions.inc.php|<b>gameoptions.inc.php</b>]] - game options & user preferences
* [[Game art: img directory|<b>img/</b>]] - game art
* [[Game material description: material.inc.php|<b>material.inc.php</b>]] - static data
* <b>misc/</b> - studio-only storage
* <b>modules/</b> - additional game code
* [[Your game state machine: states.inc.php|<b>states.inc.php</b>]] - state machine
* [[Game statistics: stats.inc.php|<b>stats.inc.php</b>]] - statistics
* [[Players actions: yourgamename.action.php|X.<b>action.php</b>]] - player actions
* [[Game interface stylesheet: yourgamename.css|X<b>.css</b>]] - interface stylesheet
* [[Main game logic: yourgamename.game.php|X.<b>game.php</b>]] - main logic
* [[Game interface logic: yourgamename.js|X.<b>js</b>]] - interface logic
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X.<b>view.php</b>]] - dynamic game layout
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X_X.<b>tpl</b>]] - static game layout
<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Useful Components'''</center></div>

'''Official'''

* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
* [[Draggable]]: a JS component to manage drag'n'drop actions.
* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.
* [[Zone]]: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).

Undocumented component (if somebody knows please help with docs)
* [[Wrapper]]: a JS component to wrap a <div> element around its child, even if these elements are absolute positioned.

'''Unofficial'''

* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks
* [[Some usual board game elements image ressources]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game Development Process'''</center></div>

* [[First steps with BGA Studio]]
* [[Create a game in BGA Studio: Complete Walkthrough]]
* [[Tutorial reversi]]
* [[Tutorial gomoku]]
* [[Tutorial hearts]]
* [[BGA Studio Guidelines]]
* [[BGA game Lifecycle]]
* [[Pre-release checklist]]
* [[Post-release phase]]
* [[Help|Player Resources]] - add player help/rules to your game page

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Guides for Common Topics'''</center></div>

* [[Translations]] - make your game translatable
* [[Game replay|Game Replay]]
* [[Your game mobile version|Mobile Users]]
* [[3D]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Miscellaneous Resources'''</center></div>

* [[Studio FAQ]]
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment
* [[Studio logs]] - Instructions for log access
* [[Practical debugging]] - Tips focused on debugging
* [[Troubleshooting]] - Most common "I am really stuck" situations
* [https://studio.boardgamearena.com/bugs Studio Bugs] - Reports against Studio itself (not BGA!)
</div>

Translations

2022-05-03T10:04:30Z

Archduke: /* Formatting on client side */

{{Studio_Framework_Navigation}}

Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.

__TOC__

== Localization Overview ==

Localization for BGA games happens largely on the CLIENT. Games must be developed in English and English strings are sent to the client.

It's only at the client that your English strings will be displayed with the translation for the user's language, when such a translation exists.

For anyone who has worked on a system where translation happens at the server and localized strings are sent to the client: you must unlearn what you have learned. Just stick with English and send the untranslated English strings. The magic happens at the client.

== How will my strings be translated? ==

When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.

Once your game enters Beta, the BGA player community will descend upon your game like a plague of locusts and translate it into dozens of languages before you can say "Je ne parle pas anglais".

== What do I have to do from a programming standpoint? ==

Not as much as you think. Read on for full details, but the golden rules are:

# Make sure that any string on the server side that needs to be translated on the client side is wrapped in a clienttranslate() function when defined. For example: $my_response = clienttranslate('Hey translators, please translate this string'). clienttranslate doesn't actually do anything at all (it just passes the text through) but the translation engine searches your code for strings wrapped in that function and uses them to build the list of strings that need to be translated.
# On the client side, just display your text, but wrap it in _().
## If you pass a string constant to _() - such as _('This is my string') then the parser will automatically detect and add your string to the list of strings that need to be translated, AND it will display the local translation for it when displaying.
## If you pass a variable to _() - such as _(args.my_message) then MAKE SURE that the variable is set to an English string that is either defined somewhere in your PHP code in a clienttranslate() function or somewhere else in your javascript code in a _() function. As long as it is, the translators will provide translations for it, and the _() function will display the local translation of your English string.
# A string used as the message for notifyAllPlayers or notifyPlayer will automatically have its translation displayed on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used as the "description" or "descriptionmyturn" for a state in your state machine will also be automatically translated on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used in the pre-games option screen will also automatically have any translation displayed at the client - you don't need to do anything EXCEPT make sure that it is wrapped in a totranslate() on the server (nota bene: you should not use clienttranslate() here as this file is processed specifically and those strings will not be included in the game translation file but in the main site translation file - with a prefix to keep translations isolated by module - as they have to be translated on main site pages. If you need exactly the same string in your game for a client side translation, it should be declared somewhere else in your code wrapped inside a clienttranslate() to be included in the game translation file.
# A string used in the statistics screen will operate like a string in the pre-game options screen. It will automatically have any translation displayed at the client as long as you make sure that it is wrapped in a totranslate() on the server.
# If you are using parameters for a call to notifyAllPlayers or notifyPlayers, or for a state's "description" or "descriptionmyturn" and those parameters contain text that needs to be translated, you will need to tell the system to display the translated versions of them by using the 'i18n' argument. See below for full details.

== What strings should be translated? ==

Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages.

This does NOT include error messages that are not supposed to happen (unexpected errors).

== What rules should I follow for the original English strings? ==

For a coherent and homogeneous interface, here are some rules about ending a sentence with a final period '.'

* As a general rule:
** If a sentence is displayed isolated in the interface => no final period
** If a sentence is followed or could be followed by another sentence in the same interface space => final period.

* In detail:
** No final period:
*** button labels
*** section titles
*** menu elements
*** links triggering an isolated action
*** anything that is not a full sentence
*** current actions in the status bar
** Final period:
*** complete sentences (e.g., explanations and descriptions) that can be chained with other sentences
** Either a period or no period is acceptable (but this should be consistent throughout the game) for:
*** isolated tooltips / small sentences
*** game logs (no period is usually preferable)
*** error messages (unless there is more than one sentence in the error message; final period is mandatory in this case)

Otherwise, you should try to follow as closely as possible the general style and format (including capitalization) used in the published English rulebook and game materials.

== Focus on translating notifications ==

Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.

However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.

== How to not make translators crazy ;) ==

* Try to reuse the exact same strings (with the same case, etc.) to minimize the number of strings to translate.
** '''Example''': Consider replacing <pre>self::_("Winner")</pre> and <pre>self::_("Winners")</pre> (two strings to translate) with <pre>self::_("Winner(s)")</pre>
** '''Example 2''': <pre>clienttranslate("play a card")</pre> and <pre>clienttranslate("Play a card")</pre> means there will be two strings to translate.
* Do not mark as translatable a game element that does not have to be translated (e.g., if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:
<pre>self::_("First part of the string, ").$argument.' '.self::_("second part of the string")</pre>
Write instead:
<pre>sprintf( self::_("First part of the string, %s second part of the string"), $argument )</pre>
(or the equivalent "dojo.string.substitute" in Javascript)
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The shorter the string is, the more difficult the task is for them. As a rule of thumb, try to avoid short, insignificant strings that require knowledge of their surrounding context. You can also leave a comment on the context of the string in the translation program (English to English) if you are the developer of the game.
* The BGA translation policy is to be flexible on grammar. We prefer to write "player gets 1 coin(s)" rather than write two versions of the same string for plural and singular - it reduces the number of strings to translate.
* Instead of writing elaborate strings like "With the effect of ZZZ, player XXX gains a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".
* Use present tense instead of past. E.g., "player gets wood" instead of "player got wood".
* Avoid using gender-specific wording as much as possible. If needed be aware that [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place, and cannot work if your use "their" as a singular genderless pronoun, as it removes the information that it's singular. E.g., you should write "playerX returns card to *his* hand" or "playerX returns card to *his/her* hand" and not "playerX returns card to *their* hand" as in the 2 first case the system will substitute the proper pronoun his/her/their depending on playerX declared/undeclared gender, but in the second case it will always stay "their" whatever the player preference setting.
* Where two strings are identical apart from (say) a number, use the same string with a ${parameter}, and call format_string_recursive (on the client) or use args (for notifications and state descriptions) to provide the details. But *never* do that for composing multiple sentences with words: other languages have different grammar and it would most likely create untranslatable strings.

== WARNING: Make sure your strings will be translated! ==

For each game, our translation tool does a full scan of the code, looking for translation markers like "_()" or "clienttranslate()". (See below for the full list of translation markers.)

If your original string is not completely contained inside one of these markers, it won't be translated.

<pre>
// Examples: the following strings will be translated:
var mystring_translated = _("my string"); // JS
$mystring_translated = self::_("my string"); // PHP
$mystring_translated = sprintf( self::_("my string with an %s argument"), $argument ); // PHP

// Examples: the following strings WILL NOT be translated:
$my_string = "my string";
$not_translated = self::_( $my_string ); // The original string is not contained within a translator marker => no translation
$not_translated = self::_( sprintf( "my string with a %s argument", $argument ) ); // Ditto
</pre>

== On client side (Javascript) ==

On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.

Examples:
<pre>
// Get a string in player's language:
var translated = _("original english string");

// Get a string in player's language with parameter:
var translated = dojo.string.substitute( _("You can pick ${p} cards and discard ${d}"), {
p: 2,
d: 4
} );
</pre>

'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.

'''ANOTHER WARNING:''' you cannot use this function _() in the javascript object constructor, but you can achieve the same if you use it the setup method

=== Formatting on client side ===

Sometimes you will want to apply some formatting on the client side, but don't want to put HTML tags within the source string (which may be confusing for translators).

This can be achieved with the <code>bga_format</code> function and Markdown-style syntax.

<pre>
/**
* @function bga_format
* Replaces delimiters with HTML tags in translated text
* @param {string} translated string
* @param {Object} map of replacements to make, should be of the form
* {
* '*': (t) => t,
* '_': 'classname',
* }
* keys are delimiters within the translated string
* values are either strings (classname of surrounding span) or function (flexible replacements)
* @returns {string} Returns the original string, with replacements made.
*/
</pre>

Example:
<pre>
// Get a string in player's language:
bga_format(_('You receive a *special* _tile_'), {
'*': (t) => '<b>' + t + '</b>',
'_': 'tile-name'
});
</pre>

The above will return something along the lines of:
<pre>
You receive a <b>special</b> <span class="tile-name">tile</span>
</pre>

Or, if the user is playing in Spanish, for example:
<pre>
Recibes una <span class="tile-name">loseta</span> <b>especial</b>
</pre>

Notes:
* The text passed to <code>bga_format</code> must still be translated using <code>_()</code>, don't forget it!
* The characters available to demarcate formatting are: <code>['-', '[', ']', '{', '}', '(', ')', '*', '+', '?', '.', ',', '\\', '^', '$', '|', '#', ' ']</code>
* If the replacements object is a string, the inner text will be placed within a `<span>` tag with the string as a class
* If the replacements object is a function, the inner text will be passed as an argument to the function, and the return value will replace the text and the delimiters

== On server side (PHP) ==

On PHP side, you can use 3 different functions to specify that a string must be translated.

=== Function clienttranslate ===

'''clienttranslate( 'string to translate' ):'''

This function is ''transparent'': it will return the original English string without any change. Its only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.

In general, you use clienttranslate:
* In your '''states.inc.php''', for the fields "description" and "descriptionmyturn".

<pre>
"description" => clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),
</pre>

* In '''material.inc.php''', when defining text for game materials that must be displayed on the client side.

<pre>
$this->card_types = array(

1 => array(
'name' => clienttranslate('Amulet of Air'), // Thus, we can use "_( card_name )" on Javascript side.
</pre>

* When sending a notification with ''notifyAllPlayers'' or ''notifyPlayer'', in the game log string and all game log arguments that need a translation.

<pre>
// A game log string with no argument:
self::notifyAllPlayers( 'pickLibraryCards', clienttranslate('Everyone draw cards from their library'), [] );
</pre>

As a consequence there is no point passing variables to this function. E.g.:

<pre>
notif="foo";
self::notifyAllPlayers( 'log', clienttranslate(notif),[]); // BAD

notif=clienttranslate("foo");
self::notifyAllPlayers( 'log', notif,[]); // GOOD

self::notifyAllPlayers( 'log', clienttranslate("player gains ${num} gems"),[num=>2]); // BAD it is dynamic string enterpreted by php
self::notifyAllPlayers( 'log', clienttranslate('player gains ${num} gems'),[num=>2]); // GOOD, difference is single quotes

self::notifyAllPlayers( 'log', clienttranslate("player gains ".${num}." gems"),[num=>2]); // BAD concatenation

</pre>

Translating arguments is a little bit more complex. This uses the '''i18n''' special argument as below:

<pre>
// In the following example, we translate the game log itself, but also the "card_name" argument:

self::notifyAllPlayers( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'points' => $points,
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.
) );
</pre>

To ensure the translation of the i18n argument will be made, clienttranslate must have been used somewhere, for instance:

<pre>
$this->card_types = array(
...
8 => array(
'name' => clienttranslate("Amulet of Fire"),
...
</pre>

Pay attention when using the '''i18n''' argument when translating arguments for the client: do NOT use same argument for both translations AND key codes for client-side actions (like using 'card_name' to move it on the player board as described in the example). It's pretty obvious in the example, but it can be very tricky when translation is made at the end of the development (which is often the case). Use explicit argument names like 'card_name_translated' by example.

'''WARNING:''' you should NEVER use concatenation with ''clienttranslate'', as it would result in a different string to translate at runtime than the one retrieved statically in the translation system, and so translation would not be applied. If you need to compose a string, use substitution and the i18n parameter (but you also have to pay attention not to compose sentences in a way that is dependent upon the English language specific syntax, or it may be impossible to translate correctly in another language: sometimes, you need multiple full sentences rather than relying on substitution).

=== Method _ (underscore) ===

'''self::_( "my string to translate" ):'''

This function returns a string translated in the language of CURRENT user (i.e. player who send the request to the server) (be careful, this is NOT the active player).

This can be used like self::_('bla') or this->('bla'). You cannot use static underscore function _('bla') in php, it is not the same, it will not translate strings from your game.

The returned string will be surrounded by HTML tags, so you cannot use it in places where pure text is required or your string already has another html markup.

Most of the time, you don't need to translate strings on server side, except on the following situations:
* Throwing user exceptions
* Creating the labels for the game interface used in your template
* Rarely, in your material.inc.php, if for example you need to use some string elements in your exceptions
* Rarely, in your "getAllDatas" PHP method, as the data return by this method is used only by current user

Imporant! This function does two things:
* Mark string for translation
* Translates in runtime
As a consequence you absolutely cannot have $var in there! Or string concatenations.
I.e.
$food=self::_("Banana");// good
self::_("User gives $food to a cat"); // bad
For the translator we will have two strings "Banana" and "User gives $food to a cat", but in runtime we will be
"Banana" and "User gives Banana to a cat" and second string would not match anything. And this is as bad
self::_("User gives ".$food." to a cat");// bad

==== Throwing an exception because the player did a forbidden move ====

<pre>
// This will display a translatable red message to the player that just did some wrong action:
throw new BgaUserException( self::_('You must choose 3 cards') );

// ... notice the use of BgaUserException that signals that this exception is "expected". In theory, all exception that are expected should be translated.
</pre>

==== Creating labels ====

In "yourgame.view.php", when creating the labels for the game interface used in your template (.tpl) file.

<pre>
$this->tpl['CARDS_FOR_YEAR_2'] = self::_("Your cards for year II");
</pre>

'''Nota bene:''' it is recommended to set translated text in your interface client side rather than use template variables and server translation, so that translation works natively in replays (that don't have server side translations). For simple strings, the framework will handle moving the translation client side, but for more complex strings it may not work. In particular, you should not use server side translation for templates with substitution variables (or use the specific function "gameview_str_replace( $search, $replace, $string )" if not possible otherwise or for old code compatibility). Also, you should never use a "to_translate" class in your .tpl as it is used internally by the framework.

Example with view.php:
in .tpl:
<pre>
<div id="empire_title_{COLOR}" class="side_title color_{COLOR}">{EMPIRE_LABEL}</div>
</pre>
in view.php:
$this->page->insert_block("player_board", array ("COLOR" => $color,"PLAYER_NAME" => $name,"PLAYER_NO" => $no,
"PLAYER_ID" => $player_id, "CLASSES" => $own?"own":"",
"EMPIRE_LABEL" => self::raw(gameview_str_replace('${player_name}', $name, self::_('${player_name}\'s EMPIRE')))
));
Example with client side:
in .tpl:
<pre>
<div id="empire_title_{COLOR}" class="side_title color_{COLOR}">Stub</div>
</pre>
in .js:
<pre>
for (var player_id in this.gamedatas.players) {
var player_color = this.gamedatas.players[player_id].color;
var player_name = this.gamedatas.players[player_id].name;
$('empire_title_'+player_color).innerHTML=this.format_string_recursive(_("${player_name}'s EMPIRE"), {player_name: player_name});
}
</pre>

==== Translating strings in material file ====

Rarely, in your material.inc.php, if for example you need to use some string elements in your exceptions.

<pre>
// In material.inc.php, $this->energies[n]['nametr'] has been created with the self::_() method. Now we can do this:
throw new BgaUserException( self::_("To execute this action you need more: ").' '.$this->energies[$resource_id]['nametr'] );
</pre>

Note: you could also do this, so you don't need to pollute your material file
throw new BgaUserException( self::_("To execute this action you need more: ").' '.self::_($this->energies[$resource_id]['name']) );

where $this->energies[$resource_id]['name'] were marked in material file using regular clienttranslate function
<pre>
$this->energies = [
22 => [
'name' => clienttranslate('Sun')
...
]
];
</pre>

==== Strings in getAllDatas ====

Rarely, in your "getAllDatas" PHP method, as the data return by this method is used only by current user.

Note: not sure why would you send strings from the server in this case, as same can be achieved on the client usually.

=== Function totranslate ===

'''totranslate( "my string to translate" ):'''

This function works exactly like 'clienttranslate', except it tells BGA that the string is not needed on client side.

You should not use this function, except on the following cases:
* Statistics name in stats.inc.php
* Option names and option values name in gameoptions.inc.php

== Top Secret Undocumented Features ==

If your string contains the clause '$${value}' (such as 'You gain $${value}.') then the translation system seems to move the position of the $ to a localized location (eg $5 in English but 5$ in French). This only seems to occur when using the argument 'value'.

In JavaScript, you can get the current user's language by retrieving the translation for the special string "$locale":

var lang = _('$locale'); // en, fr, etc.

== On server side - advanced (PHP) ==

If you want to use translation system in your custom static modules, you will first need to expose the _() function :
<pre>
class mygame extends Table {
// Exposing protected method translation
public static function totranslate($text) {
return self::_($text);
}
}
</pre>

Then you'll be able to use this directly in other modules by doing
<pre>
throw new BgaUserException(mygame::totranslate("Translated error from my awesome module file"));
</pre>

Notice how the "totranslate" is also used by the static analysis to detect your string. So the following will not work :
<pre>
$msg = "Translated error from my awesome module file";
throw new BgaUserException(mygame::totranslate($msg));
</pre>

== Analyze your project ==

It looks super complex but there is help!
On studio control panel you can find a button "Check project" - it runs bunch of static analysis on your project including scanning for bad translations and missing translations.
It also will extact all you translation keys as translator will see them so you can double check - and run spell checker on them.

== Other Useful Links ==

* BLOG post about translations https://bga-devs.github.io/blog/posts/translations-summary/

Translations

2022-05-03T10:03:06Z

Archduke:

{{Studio_Framework_Navigation}}

Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.

__TOC__

== Localization Overview ==

Localization for BGA games happens largely on the CLIENT. Games must be developed in English and English strings are sent to the client.

It's only at the client that your English strings will be displayed with the translation for the user's language, when such a translation exists.

For anyone who has worked on a system where translation happens at the server and localized strings are sent to the client: you must unlearn what you have learned. Just stick with English and send the untranslated English strings. The magic happens at the client.

== How will my strings be translated? ==

When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.

Once your game enters Beta, the BGA player community will descend upon your game like a plague of locusts and translate it into dozens of languages before you can say "Je ne parle pas anglais".

== What do I have to do from a programming standpoint? ==

Not as much as you think. Read on for full details, but the golden rules are:

# Make sure that any string on the server side that needs to be translated on the client side is wrapped in a clienttranslate() function when defined. For example: $my_response = clienttranslate('Hey translators, please translate this string'). clienttranslate doesn't actually do anything at all (it just passes the text through) but the translation engine searches your code for strings wrapped in that function and uses them to build the list of strings that need to be translated.
# On the client side, just display your text, but wrap it in _().
## If you pass a string constant to _() - such as _('This is my string') then the parser will automatically detect and add your string to the list of strings that need to be translated, AND it will display the local translation for it when displaying.
## If you pass a variable to _() - such as _(args.my_message) then MAKE SURE that the variable is set to an English string that is either defined somewhere in your PHP code in a clienttranslate() function or somewhere else in your javascript code in a _() function. As long as it is, the translators will provide translations for it, and the _() function will display the local translation of your English string.
# A string used as the message for notifyAllPlayers or notifyPlayer will automatically have its translation displayed on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used as the "description" or "descriptionmyturn" for a state in your state machine will also be automatically translated on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used in the pre-games option screen will also automatically have any translation displayed at the client - you don't need to do anything EXCEPT make sure that it is wrapped in a totranslate() on the server (nota bene: you should not use clienttranslate() here as this file is processed specifically and those strings will not be included in the game translation file but in the main site translation file - with a prefix to keep translations isolated by module - as they have to be translated on main site pages. If you need exactly the same string in your game for a client side translation, it should be declared somewhere else in your code wrapped inside a clienttranslate() to be included in the game translation file.
# A string used in the statistics screen will operate like a string in the pre-game options screen. It will automatically have any translation displayed at the client as long as you make sure that it is wrapped in a totranslate() on the server.
# If you are using parameters for a call to notifyAllPlayers or notifyPlayers, or for a state's "description" or "descriptionmyturn" and those parameters contain text that needs to be translated, you will need to tell the system to display the translated versions of them by using the 'i18n' argument. See below for full details.

== What strings should be translated? ==

Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages.

This does NOT include error messages that are not supposed to happen (unexpected errors).

== What rules should I follow for the original English strings? ==

For a coherent and homogeneous interface, here are some rules about ending a sentence with a final period '.'

* As a general rule:
** If a sentence is displayed isolated in the interface => no final period
** If a sentence is followed or could be followed by another sentence in the same interface space => final period.

* In detail:
** No final period:
*** button labels
*** section titles
*** menu elements
*** links triggering an isolated action
*** anything that is not a full sentence
*** current actions in the status bar
** Final period:
*** complete sentences (e.g., explanations and descriptions) that can be chained with other sentences
** Either a period or no period is acceptable (but this should be consistent throughout the game) for:
*** isolated tooltips / small sentences
*** game logs (no period is usually preferable)
*** error messages (unless there is more than one sentence in the error message; final period is mandatory in this case)

Otherwise, you should try to follow as closely as possible the general style and format (including capitalization) used in the published English rulebook and game materials.

== Focus on translating notifications ==

Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.

However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.

== How to not make translators crazy ;) ==

* Try to reuse the exact same strings (with the same case, etc.) to minimize the number of strings to translate.
** '''Example''': Consider replacing <pre>self::_("Winner")</pre> and <pre>self::_("Winners")</pre> (two strings to translate) with <pre>self::_("Winner(s)")</pre>
** '''Example 2''': <pre>clienttranslate("play a card")</pre> and <pre>clienttranslate("Play a card")</pre> means there will be two strings to translate.
* Do not mark as translatable a game element that does not have to be translated (e.g., if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:
<pre>self::_("First part of the string, ").$argument.' '.self::_("second part of the string")</pre>
Write instead:
<pre>sprintf( self::_("First part of the string, %s second part of the string"), $argument )</pre>
(or the equivalent "dojo.string.substitute" in Javascript)
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The shorter the string is, the more difficult the task is for them. As a rule of thumb, try to avoid short, insignificant strings that require knowledge of their surrounding context. You can also leave a comment on the context of the string in the translation program (English to English) if you are the developer of the game.
* The BGA translation policy is to be flexible on grammar. We prefer to write "player gets 1 coin(s)" rather than write two versions of the same string for plural and singular - it reduces the number of strings to translate.
* Instead of writing elaborate strings like "With the effect of ZZZ, player XXX gains a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".
* Use present tense instead of past. E.g., "player gets wood" instead of "player got wood".
* Avoid using gender-specific wording as much as possible. If needed be aware that [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place, and cannot work if your use "their" as a singular genderless pronoun, as it removes the information that it's singular. E.g., you should write "playerX returns card to *his* hand" or "playerX returns card to *his/her* hand" and not "playerX returns card to *their* hand" as in the 2 first case the system will substitute the proper pronoun his/her/their depending on playerX declared/undeclared gender, but in the second case it will always stay "their" whatever the player preference setting.
* Where two strings are identical apart from (say) a number, use the same string with a ${parameter}, and call format_string_recursive (on the client) or use args (for notifications and state descriptions) to provide the details. But *never* do that for composing multiple sentences with words: other languages have different grammar and it would most likely create untranslatable strings.

== WARNING: Make sure your strings will be translated! ==

For each game, our translation tool does a full scan of the code, looking for translation markers like "_()" or "clienttranslate()". (See below for the full list of translation markers.)

If your original string is not completely contained inside one of these markers, it won't be translated.

<pre>
// Examples: the following strings will be translated:
var mystring_translated = _("my string"); // JS
$mystring_translated = self::_("my string"); // PHP
$mystring_translated = sprintf( self::_("my string with an %s argument"), $argument ); // PHP

// Examples: the following strings WILL NOT be translated:
$my_string = "my string";
$not_translated = self::_( $my_string ); // The original string is not contained within a translator marker => no translation
$not_translated = self::_( sprintf( "my string with a %s argument", $argument ) ); // Ditto
</pre>

== On client side (Javascript) ==

On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.

Examples:
<pre>
// Get a string in player's language:
var translated = _("original english string");

// Get a string in player's language with parameter:
var translated = dojo.string.substitute( _("You can pick ${p} cards and discard ${d}"), {
p: 2,
d: 4
} );
</pre>

'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.

'''ANOTHER WARNING:''' you cannot use this function _() in the javascript object constructor, but you can achieve the same if you use it the setup method

=== Formatting on client side ===

Sometimes you will want to apply some formatting on the client side, but don't want to put HTML tags within the source string (which may be confusing for translators).

This can be achieved with the `bga_format` function and Markdown-style syntax.

<pre>
/**
* @function bga_format
* Replaces delimiters with HTML tags in translated text
* @param {string} translated string
* @param {Object} map of replacements to make, should be of the form
* {
* '*': (t) => t,
* '_': 'classname',
* }
* keys are delimiters within the translated string
* values are either strings (classname of surrounding span) or function (flexible replacements)
* @returns {string} Returns the original string, with replacements made.
*/
</pre>

Example:
<pre>
// Get a string in player's language:
bga_format(_('You receive a *special* _tile_'), {
'*': (t) => '<b>' + t + '</b>',
'_': 'tile-name'
});
</pre>

The above will return something along the lines of:
<pre>
You receive a <b>special</b> <span class="tile-name">tile</span>
</pre>

Or, if the user is playing in Spanish, for example:
<pre>
Recibes una <span class="tile-name">loseta</span> <b>especial</b>
</pre>

Notes:
- The text passed to `bga_format` must still be translated using `_()`, don't forget it!
- The characters available to demarcate formatting are: <code>['-', '[', ']', '{', '}', '(', ')', '*', '+', '?', '.', ',', '\\', '^', '$', '|', '#', ' ']</code>
- If the replacements object is a string, the inner text will be placed within a `<span>` tag with the string as a class
- If the replacements object is a function, the inner text will be passed as an argument to the function, and the return value will replace the text and the delimiters

== On server side (PHP) ==

On PHP side, you can use 3 different functions to specify that a string must be translated.

=== Function clienttranslate ===

'''clienttranslate( 'string to translate' ):'''

This function is ''transparent'': it will return the original English string without any change. Its only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.

In general, you use clienttranslate:
* In your '''states.inc.php''', for the fields "description" and "descriptionmyturn".

<pre>
"description" => clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),
</pre>

* In '''material.inc.php''', when defining text for game materials that must be displayed on the client side.

<pre>
$this->card_types = array(

1 => array(
'name' => clienttranslate('Amulet of Air'), // Thus, we can use "_( card_name )" on Javascript side.
</pre>

* When sending a notification with ''notifyAllPlayers'' or ''notifyPlayer'', in the game log string and all game log arguments that need a translation.

<pre>
// A game log string with no argument:
self::notifyAllPlayers( 'pickLibraryCards', clienttranslate('Everyone draw cards from their library'), [] );
</pre>

As a consequence there is no point passing variables to this function. E.g.:

<pre>
notif="foo";
self::notifyAllPlayers( 'log', clienttranslate(notif),[]); // BAD

notif=clienttranslate("foo");
self::notifyAllPlayers( 'log', notif,[]); // GOOD

self::notifyAllPlayers( 'log', clienttranslate("player gains ${num} gems"),[num=>2]); // BAD it is dynamic string enterpreted by php
self::notifyAllPlayers( 'log', clienttranslate('player gains ${num} gems'),[num=>2]); // GOOD, difference is single quotes

self::notifyAllPlayers( 'log', clienttranslate("player gains ".${num}." gems"),[num=>2]); // BAD concatenation

</pre>

Translating arguments is a little bit more complex. This uses the '''i18n''' special argument as below:

<pre>
// In the following example, we translate the game log itself, but also the "card_name" argument:

self::notifyAllPlayers( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'points' => $points,
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.
) );
</pre>

To ensure the translation of the i18n argument will be made, clienttranslate must have been used somewhere, for instance:

<pre>
$this->card_types = array(
...
8 => array(
'name' => clienttranslate("Amulet of Fire"),
...
</pre>

Pay attention when using the '''i18n''' argument when translating arguments for the client: do NOT use same argument for both translations AND key codes for client-side actions (like using 'card_name' to move it on the player board as described in the example). It's pretty obvious in the example, but it can be very tricky when translation is made at the end of the development (which is often the case). Use explicit argument names like 'card_name_translated' by example.

'''WARNING:''' you should NEVER use concatenation with ''clienttranslate'', as it would result in a different string to translate at runtime than the one retrieved statically in the translation system, and so translation would not be applied. If you need to compose a string, use substitution and the i18n parameter (but you also have to pay attention not to compose sentences in a way that is dependent upon the English language specific syntax, or it may be impossible to translate correctly in another language: sometimes, you need multiple full sentences rather than relying on substitution).

=== Method _ (underscore) ===

'''self::_( "my string to translate" ):'''

This function returns a string translated in the language of CURRENT user (i.e. player who send the request to the server) (be careful, this is NOT the active player).

This can be used like self::_('bla') or this->('bla'). You cannot use static underscore function _('bla') in php, it is not the same, it will not translate strings from your game.

The returned string will be surrounded by HTML tags, so you cannot use it in places where pure text is required or your string already has another html markup.

Most of the time, you don't need to translate strings on server side, except on the following situations:
* Throwing user exceptions
* Creating the labels for the game interface used in your template
* Rarely, in your material.inc.php, if for example you need to use some string elements in your exceptions
* Rarely, in your "getAllDatas" PHP method, as the data return by this method is used only by current user

Imporant! This function does two things:
* Mark string for translation
* Translates in runtime
As a consequence you absolutely cannot have $var in there! Or string concatenations.
I.e.
$food=self::_("Banana");// good
self::_("User gives $food to a cat"); // bad
For the translator we will have two strings "Banana" and "User gives $food to a cat", but in runtime we will be
"Banana" and "User gives Banana to a cat" and second string would not match anything. And this is as bad
self::_("User gives ".$food." to a cat");// bad

==== Throwing an exception because the player did a forbidden move ====

<pre>
// This will display a translatable red message to the player that just did some wrong action:
throw new BgaUserException( self::_('You must choose 3 cards') );

// ... notice the use of BgaUserException that signals that this exception is "expected". In theory, all exception that are expected should be translated.
</pre>

==== Creating labels ====

In "yourgame.view.php", when creating the labels for the game interface used in your template (.tpl) file.

<pre>
$this->tpl['CARDS_FOR_YEAR_2'] = self::_("Your cards for year II");
</pre>

'''Nota bene:''' it is recommended to set translated text in your interface client side rather than use template variables and server translation, so that translation works natively in replays (that don't have server side translations). For simple strings, the framework will handle moving the translation client side, but for more complex strings it may not work. In particular, you should not use server side translation for templates with substitution variables (or use the specific function "gameview_str_replace( $search, $replace, $string )" if not possible otherwise or for old code compatibility). Also, you should never use a "to_translate" class in your .tpl as it is used internally by the framework.

Example with view.php:
in .tpl:
<pre>
<div id="empire_title_{COLOR}" class="side_title color_{COLOR}">{EMPIRE_LABEL}</div>
</pre>
in view.php:
$this->page->insert_block("player_board", array ("COLOR" => $color,"PLAYER_NAME" => $name,"PLAYER_NO" => $no,
"PLAYER_ID" => $player_id, "CLASSES" => $own?"own":"",
"EMPIRE_LABEL" => self::raw(gameview_str_replace('${player_name}', $name, self::_('${player_name}\'s EMPIRE')))
));
Example with client side:
in .tpl:
<pre>
<div id="empire_title_{COLOR}" class="side_title color_{COLOR}">Stub</div>
</pre>
in .js:
<pre>
for (var player_id in this.gamedatas.players) {
var player_color = this.gamedatas.players[player_id].color;
var player_name = this.gamedatas.players[player_id].name;
$('empire_title_'+player_color).innerHTML=this.format_string_recursive(_("${player_name}'s EMPIRE"), {player_name: player_name});
}
</pre>

==== Translating strings in material file ====

Rarely, in your material.inc.php, if for example you need to use some string elements in your exceptions.

<pre>
// In material.inc.php, $this->energies[n]['nametr'] has been created with the self::_() method. Now we can do this:
throw new BgaUserException( self::_("To execute this action you need more: ").' '.$this->energies[$resource_id]['nametr'] );
</pre>

Note: you could also do this, so you don't need to pollute your material file
throw new BgaUserException( self::_("To execute this action you need more: ").' '.self::_($this->energies[$resource_id]['name']) );

where $this->energies[$resource_id]['name'] were marked in material file using regular clienttranslate function
<pre>
$this->energies = [
22 => [
'name' => clienttranslate('Sun')
...
]
];
</pre>

==== Strings in getAllDatas ====

Rarely, in your "getAllDatas" PHP method, as the data return by this method is used only by current user.

Note: not sure why would you send strings from the server in this case, as same can be achieved on the client usually.

=== Function totranslate ===

'''totranslate( "my string to translate" ):'''

This function works exactly like 'clienttranslate', except it tells BGA that the string is not needed on client side.

You should not use this function, except on the following cases:
* Statistics name in stats.inc.php
* Option names and option values name in gameoptions.inc.php

== Top Secret Undocumented Features ==

If your string contains the clause '$${value}' (such as 'You gain $${value}.') then the translation system seems to move the position of the $ to a localized location (eg $5 in English but 5$ in French). This only seems to occur when using the argument 'value'.

In JavaScript, you can get the current user's language by retrieving the translation for the special string "$locale":

var lang = _('$locale'); // en, fr, etc.

== On server side - advanced (PHP) ==

If you want to use translation system in your custom static modules, you will first need to expose the _() function :
<pre>
class mygame extends Table {
// Exposing protected method translation
public static function totranslate($text) {
return self::_($text);
}
}
</pre>

Then you'll be able to use this directly in other modules by doing
<pre>
throw new BgaUserException(mygame::totranslate("Translated error from my awesome module file"));
</pre>

Notice how the "totranslate" is also used by the static analysis to detect your string. So the following will not work :
<pre>
$msg = "Translated error from my awesome module file";
throw new BgaUserException(mygame::totranslate($msg));
</pre>

== Analyze your project ==

It looks super complex but there is help!
On studio control panel you can find a button "Check project" - it runs bunch of static analysis on your project including scanning for bad translations and missing translations.
It also will extact all you translation keys as translator will see them so you can double check - and run spell checker on them.

== Other Useful Links ==

* BLOG post about translations https://bga-devs.github.io/blog/posts/translations-summary/

Translations

2022-05-03T09:46:14Z

Archduke: Add TOC

{{Studio_Framework_Navigation}}

Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.

__TOC__

== Localization Overview ==

Localization for BGA games happens largely on the CLIENT. Games must be developed in English and English strings are sent to the client.

It's only at the client that your English strings will be displayed with the translation for the user's language, when such a translation exists.

For anyone who has worked on a system where translation happens at the server and localized strings are sent to the client: you must unlearn what you have learned. Just stick with English and send the untranslated English strings. The magic happens at the client.

== How will my strings be translated? ==

When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.

Once your game enters Beta, the BGA player community will descend upon your game like a plague of locusts and translate it into dozens of languages before you can say "Je ne parle pas anglais".

== What do I have to do from a programming standpoint? ==

Not as much as you think. Read on for full details, but the golden rules are:

# Make sure that any string on the server side that needs to be translated on the client side is wrapped in a clienttranslate() function when defined. For example: $my_response = clienttranslate('Hey translators, please translate this string'). clienttranslate doesn't actually do anything at all (it just passes the text through) but the translation engine searches your code for strings wrapped in that function and uses them to build the list of strings that need to be translated.
# On the client side, just display your text, but wrap it in _().
## If you pass a string constant to _() - such as _('This is my string') then the parser will automatically detect and add your string to the list of strings that need to be translated, AND it will display the local translation for it when displaying.
## If you pass a variable to _() - such as _(args.my_message) then MAKE SURE that the variable is set to an English string that is either defined somewhere in your PHP code in a clienttranslate() function or somewhere else in your javascript code in a _() function. As long as it is, the translators will provide translations for it, and the _() function will display the local translation of your English string.
# A string used as the message for notifyAllPlayers or notifyPlayer will automatically have its translation displayed on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used as the "description" or "descriptionmyturn" for a state in your state machine will also be automatically translated on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used in the pre-games option screen will also automatically have any translation displayed at the client - you don't need to do anything EXCEPT make sure that it is wrapped in a totranslate() on the server (nota bene: you should not use clienttranslate() here as this file is processed specifically and those strings will not be included in the game translation file but in the main site translation file - with a prefix to keep translations isolated by module - as they have to be translated on main site pages. If you need exactly the same string in your game for a client side translation, it should be declared somewhere else in your code wrapped inside a clienttranslate() to be included in the game translation file.
# A string used in the statistics screen will operate like a string in the pre-game options screen. It will automatically have any translation displayed at the client as long as you make sure that it is wrapped in a totranslate() on the server.
# If you are using parameters for a call to notifyAllPlayers or notifyPlayers, or for a state's "description" or "descriptionmyturn" and those parameters contain text that needs to be translated, you will need to tell the system to display the translated versions of them by using the 'i18n' argument. See below for full details.

== What strings should be translated? ==

Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages.

This does NOT include error messages that are not supposed to happen (unexpected errors).

== What rules should I follow for the original English strings? ==

For a coherent and homogeneous interface, here are some rules about ending a sentence with a final period '.'

* As a general rule:
** If a sentence is displayed isolated in the interface => no final period
** If a sentence is followed or could be followed by another sentence in the same interface space => final period.

* In detail:
** No final period:
*** button labels
*** section titles
*** menu elements
*** links triggering an isolated action
*** anything that is not a full sentence
*** current actions in the status bar
** Final period:
*** complete sentences (e.g., explanations and descriptions) that can be chained with other sentences
** Either a period or no period is acceptable (but this should be consistent throughout the game) for:
*** isolated tooltips / small sentences
*** game logs (no period is usually preferable)
*** error messages (unless there is more than one sentence in the error message; final period is mandatory in this case)

Otherwise, you should try to follow as closely as possible the general style and format (including capitalization) used in the published English rulebook and game materials.

== Focus on translating notifications ==

Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.

However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.

== How to not make translators crazy ;) ==

* Try to reuse the exact same strings (with the same case, etc.) to minimize the number of strings to translate.
** '''Example''': Consider replacing <pre>self::_("Winner")</pre> and <pre>self::_("Winners")</pre> (two strings to translate) with <pre>self::_("Winner(s)")</pre>
** '''Example 2''': <pre>clienttranslate("play a card")</pre> and <pre>clienttranslate("Play a card")</pre> means there will be two strings to translate.
* Do not mark as translatable a game element that does not have to be translated (e.g., if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:
<pre>self::_("First part of the string, ").$argument.' '.self::_("second part of the string")</pre>
Write instead:
<pre>sprintf( self::_("First part of the string, %s second part of the string"), $argument )</pre>
(or the equivalent "dojo.string.substitute" in Javascript)
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The shorter the string is, the more difficult the task is for them. As a rule of thumb, try to avoid short, insignificant strings that require knowledge of their surrounding context. You can also leave a comment on the context of the string in the translation program (English to English) if you are the developer of the game.
* The BGA translation policy is to be flexible on grammar. We prefer to write "player gets 1 coin(s)" rather than write two versions of the same string for plural and singular - it reduces the number of strings to translate.
* Instead of writing elaborate strings like "With the effect of ZZZ, player XXX gains a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".
* Use present tense instead of past. E.g., "player gets wood" instead of "player got wood".
* Avoid using gender-specific wording as much as possible. If needed be aware that [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place, and cannot work if your use "their" as a singular genderless pronoun, as it removes the information that it's singular. E.g., you should write "playerX returns card to *his* hand" or "playerX returns card to *his/her* hand" and not "playerX returns card to *their* hand" as in the 2 first case the system will substitute the proper pronoun his/her/their depending on playerX declared/undeclared gender, but in the second case it will always stay "their" whatever the player preference setting.
* Where two strings are identical apart from (say) a number, use the same string with a ${parameter}, and call format_string_recursive (on the client) or use args (for notifications and state descriptions) to provide the details. But *never* do that for composing multiple sentences with words: other languages have different grammar and it would most likely create untranslatable strings.

== WARNING: Make sure your strings will be translated! ==

For each game, our translation tool does a full scan of the code, looking for translation markers like "_()" or "clienttranslate()". (See below for the full list of translation markers.)

If your original string is not completely contained inside one of these markers, it won't be translated.

<pre>
// Examples: the following strings will be translated:
var mystring_translated = _("my string"); // JS
$mystring_translated = self::_("my string"); // PHP
$mystring_translated = sprintf( self::_("my string with an %s argument"), $argument ); // PHP

// Examples: the following strings WILL NOT be translated:
$my_string = "my string";
$not_translated = self::_( $my_string ); // The original string is not contained within a translator marker => no translation
$not_translated = self::_( sprintf( "my string with a %s argument", $argument ) ); // Ditto
</pre>

== On client side (Javascript) ==

On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.

Examples:
<pre>
// Get a string in player's language:
var translated = _("original english string");

// Get a string in player's language with parameter:
var translated = dojo.string.substitute( _("You can pick ${p} cards and discard ${d}"), {
p: 2,
d: 4
} );
</pre>

'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.

'''ANOTHER WARNING:''' you cannot use this function _() in the javascript object constructor, but you can achieve the same if you use it the setup method

== On server side (PHP) ==

On PHP side, you can use 3 different functions to specify that a string must be translated.

=== Function clienttranslate ===

'''clienttranslate( 'string to translate' ):'''

This function is ''transparent'': it will return the original English string without any change. Its only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.

In general, you use clienttranslate:
* In your '''states.inc.php''', for the fields "description" and "descriptionmyturn".

<pre>
"description" => clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),
</pre>

* In '''material.inc.php''', when defining text for game materials that must be displayed on the client side.

<pre>
$this->card_types = array(

1 => array(
'name' => clienttranslate('Amulet of Air'), // Thus, we can use "_( card_name )" on Javascript side.
</pre>

* When sending a notification with ''notifyAllPlayers'' or ''notifyPlayer'', in the game log string and all game log arguments that need a translation.

<pre>
// A game log string with no argument:
self::notifyAllPlayers( 'pickLibraryCards', clienttranslate('Everyone draw cards from their library'), [] );
</pre>

As a consequence there is no point passing variables to this function. E.g.:

<pre>
notif="foo";
self::notifyAllPlayers( 'log', clienttranslate(notif),[]); // BAD

notif=clienttranslate("foo");
self::notifyAllPlayers( 'log', notif,[]); // GOOD

self::notifyAllPlayers( 'log', clienttranslate("player gains ${num} gems"),[num=>2]); // BAD it is dynamic string enterpreted by php
self::notifyAllPlayers( 'log', clienttranslate('player gains ${num} gems'),[num=>2]); // GOOD, difference is single quotes

self::notifyAllPlayers( 'log', clienttranslate("player gains ".${num}." gems"),[num=>2]); // BAD concatenation

</pre>

Translating arguments is a little bit more complex. This uses the '''i18n''' special argument as below:

<pre>
// In the following example, we translate the game log itself, but also the "card_name" argument:

self::notifyAllPlayers( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'points' => $points,
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.
) );
</pre>

To ensure the translation of the i18n argument will be made, clienttranslate must have been used somewhere, for instance:

<pre>
$this->card_types = array(
...
8 => array(
'name' => clienttranslate("Amulet of Fire"),
...
</pre>

Pay attention when using the '''i18n''' argument when translating arguments for the client: do NOT use same argument for both translations AND key codes for client-side actions (like using 'card_name' to move it on the player board as described in the example). It's pretty obvious in the example, but it can be very tricky when translation is made at the end of the development (which is often the case). Use explicit argument names like 'card_name_translated' by example.

'''WARNING:''' you should NEVER use concatenation with ''clienttranslate'', as it would result in a different string to translate at runtime than the one retrieved statically in the translation system, and so translation would not be applied. If you need to compose a string, use substitution and the i18n parameter (but you also have to pay attention not to compose sentences in a way that is dependent upon the English language specific syntax, or it may be impossible to translate correctly in another language: sometimes, you need multiple full sentences rather than relying on substitution).

=== Method _ (underscore) ===

'''self::_( "my string to translate" ):'''

This function returns a string translated in the language of CURRENT user (i.e. player who send the request to the server) (be careful, this is NOT the active player).

This can be used like self::_('bla') or this->('bla'). You cannot use static underscore function _('bla') in php, it is not the same, it will not translate strings from your game.

The returned string will be surrounded by HTML tags, so you cannot use it in places where pure text is required or your string already has another html markup.

Most of the time, you don't need to translate strings on server side, except on the following situations:
* Throwing user exceptions
* Creating the labels for the game interface used in your template
* Rarely, in your material.inc.php, if for example you need to use some string elements in your exceptions
* Rarely, in your "getAllDatas" PHP method, as the data return by this method is used only by current user

Imporant! This function does two things:
* Mark string for translation
* Translates in runtime
As a consequence you absolutely cannot have $var in there! Or string concatenations.
I.e.
$food=self::_("Banana");// good
self::_("User gives $food to a cat"); // bad
For the translator we will have two strings "Banana" and "User gives $food to a cat", but in runtime we will be
"Banana" and "User gives Banana to a cat" and second string would not match anything. And this is as bad
self::_("User gives ".$food." to a cat");// bad

==== Throwing an exception because the player did a forbidden move ====

<pre>
// This will display a translatable red message to the player that just did some wrong action:
throw new BgaUserException( self::_('You must choose 3 cards') );

// ... notice the use of BgaUserException that signals that this exception is "expected". In theory, all exception that are expected should be translated.
</pre>

==== Creating labels ====

In "yourgame.view.php", when creating the labels for the game interface used in your template (.tpl) file.

<pre>
$this->tpl['CARDS_FOR_YEAR_2'] = self::_("Your cards for year II");
</pre>

'''Nota bene:''' it is recommended to set translated text in your interface client side rather than use template variables and server translation, so that translation works natively in replays (that don't have server side translations). For simple strings, the framework will handle moving the translation client side, but for more complex strings it may not work. In particular, you should not use server side translation for templates with substitution variables (or use the specific function "gameview_str_replace( $search, $replace, $string )" if not possible otherwise or for old code compatibility). Also, you should never use a "to_translate" class in your .tpl as it is used internally by the framework.

Example with view.php:
in .tpl:
<pre>
<div id="empire_title_{COLOR}" class="side_title color_{COLOR}">{EMPIRE_LABEL}</div>
</pre>
in view.php:
$this->page->insert_block("player_board", array ("COLOR" => $color,"PLAYER_NAME" => $name,"PLAYER_NO" => $no,
"PLAYER_ID" => $player_id, "CLASSES" => $own?"own":"",
"EMPIRE_LABEL" => self::raw(gameview_str_replace('${player_name}', $name, self::_('${player_name}\'s EMPIRE')))
));
Example with client side:
in .tpl:
<pre>
<div id="empire_title_{COLOR}" class="side_title color_{COLOR}">Stub</div>
</pre>
in .js:
<pre>
for (var player_id in this.gamedatas.players) {
var player_color = this.gamedatas.players[player_id].color;
var player_name = this.gamedatas.players[player_id].name;
$('empire_title_'+player_color).innerHTML=this.format_string_recursive(_("${player_name}'s EMPIRE"), {player_name: player_name});
}
</pre>

==== Translating strings in material file ====

Rarely, in your material.inc.php, if for example you need to use some string elements in your exceptions.

<pre>
// In material.inc.php, $this->energies[n]['nametr'] has been created with the self::_() method. Now we can do this:
throw new BgaUserException( self::_("To execute this action you need more: ").' '.$this->energies[$resource_id]['nametr'] );
</pre>

Note: you could also do this, so you don't need to pollute your material file
throw new BgaUserException( self::_("To execute this action you need more: ").' '.self::_($this->energies[$resource_id]['name']) );

where $this->energies[$resource_id]['name'] were marked in material file using regular clienttranslate function
<pre>
$this->energies = [
22 => [
'name' => clienttranslate('Sun')
...
]
];
</pre>

==== Strings in getAllDatas ====

Rarely, in your "getAllDatas" PHP method, as the data return by this method is used only by current user.

Note: not sure why would you send strings from the server in this case, as same can be achieved on the client usually.

=== Function totranslate ===

'''totranslate( "my string to translate" ):'''

This function works exactly like 'clienttranslate', except it tells BGA that the string is not needed on client side.

You should not use this function, except on the following cases:
* Statistics name in stats.inc.php
* Option names and option values name in gameoptions.inc.php

== Top Secret Undocumented Features ==

If your string contains the clause '$${value}' (such as 'You gain $${value}.') then the translation system seems to move the position of the $ to a localized location (eg $5 in English but 5$ in French). This only seems to occur when using the argument 'value'.

In JavaScript, you can get the current user's language by retrieving the translation for the special string "$locale":

var lang = _('$locale'); // en, fr, etc.

== On server side - advanced (PHP) ==

If you want to use translation system in your custom static modules, you will first need to expose the _() function :
<pre>
class mygame extends Table {
// Exposing protected method translation
public static function totranslate($text) {
return self::_($text);
}
}
</pre>

Then you'll be able to use this directly in other modules by doing
<pre>
throw new BgaUserException(mygame::totranslate("Translated error from my awesome module file"));
</pre>

Notice how the "totranslate" is also used by the static analysis to detect your string. So the following will not work :
<pre>
$msg = "Translated error from my awesome module file";
throw new BgaUserException(mygame::totranslate($msg));
</pre>

== Analyze your project ==

It looks super complex but there is help!
On studio control panel you can find a button "Check project" - it runs bunch of static analysis on your project including scanning for bad translations and missing translations.
It also will extact all you translation keys as translator will see them so you can double check - and run spell checker on them.

== Other Useful Links ==

* BLOG post about translations https://bga-devs.github.io/blog/posts/translations-summary/

Studio:Home

2022-03-25T19:23:20Z

Archduke: Created page with "Placeholder content"

Placeholder content

Gamehelpfeastforodin

2021-09-18T08:15:00Z

Archduke: How to play A Feast for Odin

==Placing goods==

There are two placement controls available for the game. You can switch between them in options, but by default drag’n’drop will be used on desktop, and crosshair on mobile.

===Drag’n’drop===

Drag goods from your inventory to a board. You can click the expand icon above a board to make this easier. You can also drag ore and silver to boards in the same way.

===Crosshair===

Click the expand icon above a board to start placing goods. Click a good, ore or silver to select it, then click on the board to place it. There are buttons to rotate or cancel the last selected piece.

===Feast===

The feast board can only be saved during the Feast phase. You can provisionally place goods on the board outside of this phase, you just can’t save.

===Boats and houses===

To place ore on boats, or stone and wood in sheds and houses, simply click the appropriate slot. On mobile, you may find you need to tap twice.

==Raiding and Pillaging==

Once you roll the die for the first time, you cannot undo your turn. Before clicking “success”, make sure you select as many “sword” cards and stone as you would like to spend. After clicking “success”, you can select the reward you would like.

Your game state machine: states.inc.php

2014-06-16T09:38:51Z

Archduke: /* Private infos in args */

This file describes the game states machine of your game (all the game states properties, and the transitions to get from one state to another).

Important: to understand the game state machine, the best is to read this presentation first:

[http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine]

== Overall structure ==

The machine states is described by a PHP associative array.

Example:

<pre>
$machinestates = array(

// The initial state. Please do not modify.
1 => array(
"name" => "gameSetup",
"description" => clienttranslate("Game setup"),
"type" => "manager",
"action" => "stGameSetup",
"transitions" => array( "" => 2 )
),

// Note: ID=2 => your first state

2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a card or pass'),
"descriptionmyturn" => clienttranslate('${you} must play a card or pass'),
"type" => "activeplayer",
"possibleactions" => array( "playCard", "pass" ),
"transitions" => array( "playCard" => 2, "pass" => 2 )
),
</pre>

== Syntax ==

=== id ===

The keys determine game states IDs (in the example above: 1 and 2).

IDs must be positive integers.

ID=1 is reserved for the first game state and should not be used (and you must not modify it).

ID=99 is reserved for the last game state of the game (end of the game) (and you must not modify it).

Note: you may use any ID, even ID greater than 100. But you cannot use 1 and 99.

Note²: You can't of course use the same ID twice.

=== name ===

(mandatory)

The name of a game state is used to identify it in your game logic.

Several game states can share the same name, however this is not recommended.

PHP example:
<pre>

// Get current game state
$state = $this->gamestate->state();
if( $state['name'] == 'myGameState' )
{
...
}

</pre>

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

switch( stateName )
case 'myGameState':

// Do some stuff at the beginning at this game state
....

break;
</pre>

=== type ===

(mandatory)

You can use 3 types of game states:
* activeplayer (1 player is active and must play)
* multipleactiveplayer (1..N players can be active and must play)
* game (no player is active. This is a transitional state to do something automatic specified by game rules)

=== description ===

(mandatory)

The description is the string that is displayed in the main action bar (top of the screen) when the state is active.

When a string is specified as a description, you must use "clienttranslate" in order the string can be translate on the client side:

<pre>
"description" => clienttranslate('${actplayer} must play a card or pass'),
</pre>

In the description string, you can use ${actplayer} to refer to the active player.

You can also use custom arguments in your description. These custom arguments correspond to values returned by your "args" PHP method (see below "args" field).

Example of custom field:
<pre>

In states.inc.php:
"description" => clienttranslate('${actplayer} must choose ${nbr} identical energies'),
"args" => "argMyArgumentMethod"

In mygame.game.php:
function argMyArgumentMethod()
{
return array(
'nbr' => 2 // In this case ${nbr} in the description will be replaced by "2"
);
}
</pre>

Note: You may specify an empty string ("") here if it never happens that the game remains in this state (ie: if this state immediately jump to another state when activated).

Note²: Usually, you specify a string for "activeplayer" and "multipleactiveplayer" game states, and you specify an empty string for "game" game states. BUT, if you are using synchronous notifications, the client can remains few seconds on a "game" type game state, and in this case this may be useful to display a description in the status bar during this state.

=== descriptionmyturn ===

(mandatory for "activeplayer" and "multipleactiveplayer" game states type)

"descriptionmyturn" has exactly the same role and properties than "description", except that this value is displayed to the current active player - or to all active players in case of a multipleactiveplayer game state.

In general, we have this situation:

<pre>
"description" => clienttranslate('${actplayer} can take some actions'),
"descriptionmyturn" => clienttranslate('${you} can take some actions'),
</pre>

Note: you can use ${you} in description my turn in order the description can display "You" instead of the name of the player.

=== action ===

(mandatory for "game" game state type)

"action" specify a PHP method to call when entering into this game state.

Example:
<pre>
In states.inc.php:
28 => array(
"name" => "startPlayerTurn",
"description" => '',
"type" => "game",
"action" => "stStartPlayerTurn",

In mygame.game.php:
function stStartPlayerTurn()
{
// ... do something at the beginning of this game state
</pre>

Usually, for "game" game state type, the action method is used to do some automatic stuff specified by the rules (ex: check victory conditions, deal cards for a new round, go to the next player...) and then jump to another game state.

Note: a BGA convention specify that PHP method called with "action" are prefixed by "st".

=== transitions ===

(mandatory)

With "transition" you specify in which game state you can jump from a given game state.

Example:
<pre>
25 => array(
"name" => "myGameState",
"transitions" => array( "nextPlayer" => 27, "endRound" => 39 ),
....
}
</pre>

In the example above, if "myGameState" is the current active game state, I can jump to game state with ID 27, or game state with ID 39.

Example to jump to ID 27:
<pre>
In mygame.game.php:
$this->gamestate->nextState( "nextPlayer" );
</pre>

Important: "nextPlayer" is the name of the transition, and NOT the name of the target game state. Several transitions can lead to the same game state.

Note: if you have only 1 transition, you may give it an empty name.

Example:
<pre>
In states.inc.php:
"transitions" => array( "" => 27 ),

In mygame.game.php:
$this->gamestate->nextState( ); // We don't need to specify a transition as there is only one here
</pre>

=== possibleactions ===

(mandatory for "activeplayer" and "multipleactiveplayer" game states)

"possibleactions" defines the actions possible by the players at this game state.

By defining "possibleactions", you make sure players can't do actions that they are not allowed to do at this game states.

Example:

<pre>
In states.game.php:
"possibleactions" => array( "playCard", "pass" ),

In mygame.game.php:
function playCard( ...)
{
self::checkAction( "playCard" ); // Will failed if "playCard" is not specified in "possibleactions" in current game state.

....

In mygame.js:
playCard: function( ... )
{
if( this.checkAction( "playCard" ) ) // Will failed if "playCard" is not specified in "possibleactions" in current game state.
{ return ; }

....

</pre>

=== args ===

(optional)

From time to time, it happens that you need some information on the client side (ie : for your game interface) only for a specific game state.

Example 1 : for Reversi, the list of possible moves during playerTurn state.
Example 2 : in Caylus, the number of remaining king's favor to choose in the state where the player is choosing a favor.
Example 3 : in Can't stop, the list of possible die combination to be displayed to the active player in order he can choose among them.

In such a situation, you can specify a method name as the « args » argument for your game state. This method must get some piece of information about the game (ex : for Reversi, the possible moves) and return them.

Thus, this data can be transmitted to the clients and used by the clients to display it. It should always be an associative array.

Let's see a complete example using args with « Reversi » game :

In states.inc.php, we specify some « args » argument for gamestate « playerTurn » :
<pre>
10 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a disc'),
"descriptionmyturn" => clienttranslate('${you} must play a disc'),
"type" => "activeplayer",
"args" => "argPlayerTurn", <================================== HERE
"possibleactions" => array( 'playDisc' ),
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )
),
</pre>

It corresponds to a « argPlayerTurn » method in our PHP code (reversi.game.php):
<pre>
function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves()
);
}
</pre>

Then, when we enter into « playerTurn » game state on the client side, we can highlight the possible moves on the board using information returned by argPlayerTurn :

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

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

Note: you can also use values returned by your "args" method to have some custom values in your "description"/"descriptionmyturn" (see above).

Note: as a BGA convention, PHP methods called with "args" are prefixed by "arg" (ex: argPlayerTurn).

==== Private infos in args ====

By default, all data provided through this method are PUBLIC TO ALL PLAYERS. Please do not send any private data with this method, as a cheater could see it even it is not used explicitly by the game interface logic.

This is although possible to specify that some data should be sent to some specific players only:

Example 1: send an information to active player(s) only:

<pre>
function argPlayerTurn()
{
return array(
'_private' => array( // Using "_private" keyword, all data inside this array will be made private

'active' => array( // Using "active" keyword inside "_private", you select active player(s)
'somePrivateData' => self::getSomePrivateData() // will be send only to active player(s)
)
),

'possibleMoves' => self::getPossibleMoves() // will be send to all players
);
}
</pre>

Inside the js file, these variables will be available through `args._private`. (e.g. `args._private.somePrivateData` -- it is not `args._private.active.somePrivateData` nor is it `args.somePrivateData`)

Example 2: send an information to a specific player (<specific_player_id>) only:

<pre>
function argPlayerTurn()
{
return array(
'_private' => array( // Using "_private" keyword, all data inside this array will be made private

<specific_player_id> => array( // you select one specific player with its id
'somePrivateData' => self::getSomePrivateData() // will be send only to <specific_player_id>
)
),

'possibleMoves' => self::getPossibleMoves() // will be send to all players
);
}
</pre>

IMPORTANT: in certain situation (ex: multipleactiveplayer game state) these "private data" features can have a big performance impact. Please do not use if not needed.

=== updateGameProgression ===

(optional)

IF you specify "updateGameProgression => true" in a game state, your "getGameProgression" PHP method will be called at the beginning of this game state - and thus the game progression of the game will be updated.

At least one of your game state (any of them) must specify updateGameProgression=>true.