Board Game Arena - User contributions [en]

Practical debugging

2024-12-07T17:24:56Z

Fletcheese: /* Customizing the player id replacement */ loadBugReportSQL override not working

This page gives you practical tips to debug your game during development. Don't hesitate to share your difficulties with us so that we can improve this section.

__TOC__

== Tools ==

To work on BGA Studio, we recommend that you use [http://www.google.com/chrome Google Chrome] as it's currently the fastest browser for the BGA platform, and it's available for all OSes.

Another reason to use Chrome is that it embeds all the tools you need to work on BGA Studio. You can see them by pressing "F12" or from the menu ("Tools > Development tools").

A good practice is to use a second browser to develop the game, in order to verify that your game is working fine on this browser too.

To debug with Firefox browser, we advise you to use these 2 extensions:
* [https://addons.mozilla.org/firefox/addon/firebug/ Firebug]
* [https://addons.mozilla.org/firefox/addon/web-developer/ Web developer]

To debug with other browsers (IE, Edge, Opera), we advise you to use one of the most recent versions. Latest versions of the browser will likely have better development tools than the previous ones...

== General tip for debugging ==

=== Save & Restore ===

In general for debugging, think of using the '[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]] state' functionality. It enables you to save the state of your game just before the issue you are investigating, then come back to that point with one click as many times as needed to understand what is going wrong.

You can save up to 3 different states.

=== Refresh ===

If something does not seems to work properly even you "fixed it", it may be refresh issue. Not all files born equal. Some require a lot more steps to get into the game.

See https://en.doc.boardgamearena.com/Studio_file_reference for information on how to "refresh" each files.

== Debugging my game when it cannot start ==

If your game won't start because of an error, you are probably in one of these situations:
* There is a SQL error in your dbmodel.sql file.
* You have a syntax error in your PHP file.
* Your PHP "setupNewGame" generates exception
* You transition to new game state from the initial state which generates exception (or state is misconfigured)
* You transition to player state from the initial state which has excpetion in arg* or action* method (or state is misconfigured)

If the error is not explicitly displayed when you click on "Express start", you should check the "Gameserver error log" as per [[Studio logs]].
However errors and logs generated by setupNewGame not always (almost never) there, so see Debug setupNewGame session.
More cases of why game can't start are described on the [[Troubleshooting]] page.

== Debugging an issue with the waiting screen ==

BGA displays a waiting screen during a few seconds inviting free players to become premium when they are playing a lot.

This waiting screen should not in principle impact your game, but in some cases it might.

To test the waiting screen on the studio, you can set the desired duration by adding the get parameter studioLockingDuration with the number of seconds for the lock screen to be displayed. For example to have a 10 seconds waiting screen when you launch a game on the studio:
https://studio.boardgamearena.com?studioLockingDuration=10

Then you can just set it back to zero in the same way with https://studio.boardgamearena.com?studioLockingDuration=0 (or restart your browser to clear the session value).

== Debugging my PHP game logic (or my view) ==

=== Add traces to your code ===

You can use the following functions in your game to add server side logging:

'''$this->dump( 'name_of_variable', $variable );''' // dump variable, like var_dump but in the log debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]

'''$this->debug( $message );''' // debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]

'''$this->trace( $message );''' // info level logging, goes to [[Studio_logs|BGA request&SQL logs]]

'''$this->warn( $message );''' // warning level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]

'''$this->error( $message );''' // error level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]

Check [[Studio logs]] for more details on how to access your logs.

This can be useful when you need to follow the flow of your code and not just stop it to see how it goes at some point.

Only the error log level will appear in production. This level should be used only for critical problems.
Other levels will show only in the development environment and can be used as you see fit.

'''WARNING''': tracing does not work in constructor, setupNewGame and game states immediately following starting state (not sure why). Use other method described below in this case (seciton "Debugging setupNewGame").

To access logs on production, use button "Display recent errors from production (unexpected errors)" on control panel of your game

=== Call php functions from chat ===

This is best feature ever, you can call individual function in your game.php from chat window, see details
at https://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#Run_PHP_functions_from_the_chat

=== Dump data and die ===
First, make sure you can reproduce the needed game situation with one click. Use Save ("[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]]") function before doing some "test actions".

If you want to see what data looks like on some path you can simply throw this in exception, i.e.
<pre>
$value = var_export($my_var, true);
throw new BgaUserException('I am here: '.$value);
</pre>

Alternately use json instead of php formaing:
$value = json_encode($my_var, JSON_PRETTY_PRINT);

Another possibility for this is to place a '''die('ok')''' and '''var_dump(...)''' functions
<pre>
echo "<pre>";
var_dump( $my_variable );
echo "</pre>";
die('ok');
</pre>

Note: since this text will be returned back to client it will usually choke on this, but you can actually see it better if you wrap it some html (hence the <pre> tag)

=== Debug at home ===

If you develop some complex logic it is better sometimes to stub all external calls and debug it locally using command line or IDE debugger for php.
You can get some basic stubs here https://github.com/elaskavaia/bga-sharedcode/raw/master/misc/module/table/table.game.php

To run php locally you need to wrap it into test or something, see example https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Creating_a_test_class_to_run_PHP_locally

=== Debugging setupNewGame ===

This is separate section because tracing method do not work in this function.
Recommended way to debug it
* leave setupNewGame exactly as in template (inlcuding setting up player table and activating first player), and add a single call at the end
$this->initMyTables();
This will be your own function which you will be changing, so you don't touch setupNewGame anymore.

Remember that this function cannot send notification or query active or current player. If you need to get player data use $this->loadPlayersBasicInfos().

function initMyTables() {
try {
$players = $this->loadPlayersBasicInfos();
// ... code the function
} catch ( Exception $e ) {
// logging does not actually work in game init :(
// but if you calling from php chat it will work
$this->error("Fatal error while creating game");
$this->dump('err', $e);
}
}

Create a code for this function, and if it does not work run it from the chat window of the just created game (i.e. 'initMyTables()' without quotes). That way you can see debug output!
The only trick is you have to clear all your tables in the begging so when you run it multiple times your db does not puke.
If your game does not start at all - do not even call it from setupNewGame, comment it out and only call from chat window until it works.
Don't forget you can also look at tables in db using php-admin tool (link at the bottom of the game table in studio).

The same problem exists if you game state immediately follow starting state (problem of debugging it without the logs), in this case create a dummy player state in which player just press OK that will transition
to you game state, after you done debugging it remove the state and shortcut the transition to your game state.

Instead of calling initMyTables directly you can call helper function instead from chat window which will also reset the client, i.e.
<pre>
function debug_initMyTables() {
$this->deleteAllTables(); // this suppose to delete/reset all data - you have to implement this function
$this->initMyTables();
$newGameDatas = $this->getAllTableDatas(); // this is framework function
$this->notifyPlayer($this->getActivePlayerId(), 'resetInterfaceWithAllDatas', '', $newGameDatas); // this is notification to reset all data
$this->notifyAllPlayers("message",'setup called',[]);
}
</pre>HINT: This is a great suggestion. If you make any simple mistake in any code in setupNewGame, you may see "BGA Service Exception" instead of anything very useful, since setupNewGame failed. For example, even sending a bad SQL string to $this->dbQuery() will generate this error. Very hard to debug!

=== Debugging endOfGame ===

Debugging end of game is hard if game ends! Make sure it does not end, then you can restore to previous state using saved states.
In php file:

$this->processEndOfGame();
if ($this->getBgaEnvironment() == 'studio')
$this->gamestate->nextState('debuglast'); // debug end
else
$this->gamestate->nextState('last'); // real end

You have to add a special user state in states.inc.php file (note: this snippet uses php constants instead of state numbers)

<pre>
STATE_GAME_TURN_NEXT_PLAYER => array( // normal state
"name" => "gameTurnNextPlayer",
"description" => '',
"type" => "game",
"action" => "st_gameTurnNextPlayer",
"updateGameProgression" => true,
"transitions" => array(
"next" => STATE_PLAYER_TURN_ACTION,
"loopback" => STATE_GAME_TURN_NEXT_PLAYER,
"last" => STATE_END_GAME,
"debuglast" => STATE_PLAYER_GAME_END // for debugging on studio
),
),
// for debugging end of game
STATE_PLAYER_GAME_END => array(
"name" => "playerGameEnd",
"description" => clienttranslate('Game Over'),
"descriptionmyturn" => clienttranslate('Game Over'),
"type" => "activeplayer",
"args"=>"arg_playerTurnAction",
"possibleactions" => array( "end"),
"transitions" =>
array(
"next" => STATE_END_GAME,
"loopback"=> STATE_PLAYER_GAME_END)
),
</pre>

=== Writing custom debug functions ===
Sometimes you want to set up a situation to debug a special case, and you need tu update the game situation to fit your test. To do this quickly without needing to play a full game and hope to get the card you want to test, you can write custom debug functions.

For example, if I need to change the type of a card to your need, you can write a function like this :

<pre>
function debug_setCardType(int $id, int $type, int $typeArg = 0) {
$this->DbQuery("UPDATE card SET card_type = $type, card_type_arg = $typeArg WHERE card_id = $id" );
}
</pre>Then you can call this function by writing in the chat (on studio only) :<pre>
debug_setCardType(46,2,3)
</pre>
If you want this debug function to be quickly accessible, you need to prefix it with '''debug_''' to make it show in the debug menu of the Studio :
[[File:Custom-debug-function-example.png]]

BGA will detect methods with this prefix and the associated parameters.

Functions with parameters will show with "..." in the debug menu and will show a popin to set the parameters. Functions without parameters will be called directly. The result in the end is the same as calling the function from the chat.

== Debugging my HTML/CSS layout ==

Example situations

* Why doesn't my game element show up in the interface?
* Why hasn't my CSS property been applied to this element?
* Why is this game element displayed at this position?

A useful tip when an element does not show up in the interface is to give it a red background:
<pre>
#my_element {
... some CSS definitions ...
background-color: red;
}
</pre>

This way, you know if the element is not visible because of some CSS property or because of something else.

Another tip: sometimes, changing a CSS property has no visible effect on your interface. In that case, add a "display:none" property. If your element does not disappear, the bug probably comes from your CSS selector and not from your CSS property.

Using Chrome "Elements" tab (the first one), you can:
* See the CURRENT HTML of your page. Remember that the classical "show page source" is inefficient with BGA as you are modifying the page source with your Javascript code.
* Using the "magnifying glass", you can click on any part of your game interface and check its HTML code and associated CSS styles.
* You can even modify directly some CSS properties and see how it looks immediately in the game interface.

When changing css you have to force reload (Ctrl+R). But it also reloads all images which is long, if you want it faster you can click the Reload CSS button.
=== Debugging Toolips CSS/Layout ===

To inspect tooltip you need to pin it so it does not disappear.
* Chrome tools:
** Open dev tools and switch to Source tab to engage with debugger
** Hover over you element until tooltip showing
** Press F8 - that stops the JS, so tooltip should freeze
** Now you can go to Elements tab and find your tooltip at the botton in dijitTooltip div
** Don't forget to resume it again to continue (F8 again or resume button)
* Other method: Open the console (dev tools) large enough window, hover to make the tooltip appear and alt + tab to focus the console that will cover the tooltip. That way the onmouseout will never be triggered.

=== Debugging my Javascript game interface logic ===

To debug javascript you just use embedded browser debugger, usually found in Source tab of dev tools (F12)

Modern browsers also allow you to put breakpoints in your js code. It is in source tab, but its a bit difficult to find (your code that is), see picture below on how to insert breakpoints.

You can do this by pressing Ctrl + B when your cursor is on the line where you want to set the breakpoint, or by clicking just to the left of the line number. One thing to be aware of is that refreshing via F5 removes set breakpoints, due to some cache busting values added to the URL. This can be remedied by adding this line to the end of your javascript source file, which enables the proper source mapping:

<pre>//# sourceURL=myjsfile.js</pre>

[[File:Bga-debug.jpg]]

The easier method is to add breakpoint directly into your code and reload.

In Chrome, to add a breakpoint: add a line to your .js file

<pre>debugger; </pre>

Refresh the page F5, and make sure you have the Developer tools window open, press F12.
When the break-point is hit you can then step through your code and visualise variables, etc.

=== Do complex things on the PHP side ===

The most frequent case is the following: you want to compute possible moves in a game situation. Doing it in Javascript is a nightmare. Do it in PHP, and transfer the results to your client interface using the "args" game state property.

Note: See the Reversi tutorial for an example.

=== Add traces in your code ===

You can use the following:

'''console.log( variable_to_inspect )'''

It will give you the object structure of the variable in the Javascript console, without blocking the execution.

It's often a good idea to precede this call with a console.log( '### HERE ###' ); to find more easily the appropriate line in the console log.

'''alert( variable_to_inspect )'''

It will popup what you wish and pause the execution until you click ok.

This won't be useful for complex structures; only native types will be plainly displayed. But this is sometimes useful just with messages to make sure which way the execution goes.

== Online format checkers ==
Copy and paste code for a quick code sanity check like the right number of brackets.

PHP: [https://phpcodechecker.com/ https://phpcodechecker.com/]

JS: [http://esprima.org/demo/validate.html http://esprima.org/demo/validate.html]

Checks for proper attributes values and browser's compatibility

CSS: http://jigsaw.w3.org/css-validator/

== Some frequent errors ==

See [[Troubleshooting]].

== Get the database matching a bug report ==

When a player creates a bug report in production, a snapshot of the game database is taken. You can get access to this snapshot from the studio by following the steps below:
* Create a table in the studio with the same game and number of players as the table for which the report has been written. Launch this table.
* Load the bug dump by entering the bug report ID this debug section
[[File:LoadBugReportInput.png]]

=== Customizing the player id replacement ===
<blockquote>'''''Note''': as of 7 Dec 2024, this method may not actually work. In most cases the above ootb loading should handle player_id replacement correctly. For edge cases (e.g. php serialize), DB can be fixed during getAllDatas''</blockquote>By default, the tool will replace any production player ids in the dump by the studio player ids of the created table.

In case you want more control, setup a `loadBugReportSQL` method in your game php file (in the DebugTrait if you have one).
If a function with this name is detected on your game, the framework will not replace the ids, and it's up to you to change them.

Example of `loadBugReportSQL` function:
<pre>
public function loadBugReportSQL(int $reportId, array $studioPlayers): void
{
$prodPlayers = $this->getObjectListFromDb("SELECT `player_id` FROM `player`", true);
$prodCount = count($prodPlayers);
$studioCount = count($studioPlayers);
if ($prodCount != $studioCount) {
throw new BgaVisibleSystemException("Incorrect player count (bug report has $prodCount players, studio table has $studioCount players)");
}

// SQL specific to your game
// For example, reset the current state if it's already game over
$sql = [
"UPDATE `global` SET `global_value` = 10 WHERE `global_id` = 1 AND `global_value` = 99"
];
foreach ($prodPlayers as $index => $prodId) {
$studioId = $studioPlayers[$index];
// SQL common to all games
$sql[] = "UPDATE `player` SET `player_id` = $studioId WHERE `player_id` = $prodId";
$sql[] = "UPDATE `global` SET `global_value` = $studioId WHERE `global_value` = $prodId";
$sql[] = "UPDATE `stats` SET `stats_player_id` = $studioId WHERE `stats_player_id` = $prodId";
$sql[] = "UPDATE `bga_globals` set `name` = REPLACE(`name`, '$prodId', '$studioId'), `value` = REPLACE(`value`, '$prodId', '$studioId')";

// SQL specific to your game
$sql[] = "UPDATE `card` SET `card_location_arg` = $studioId WHERE `card_location_arg` = $prodId";
$sql[] = "UPDATE `my_table` SET `my_column` = REPLACE(`my_column`, '$prodId', '$studioId')";
}
foreach ($sql as $q) {
$this->DbQuery($q);
}
$this->reloadPlayersBasicInfos();
}
</pre>
If you used quietmint's `loadBugSQL` function, there are slight changes: the method name changed, and the studio players ids are plassed as method's second param, instead of computing them.
All other parts added in PHP/JS files for loadBug method can be removed.

''Note: If you get a "Not logged" error showing, you probably left a getCurrentPlayerId call in the `loadBugReportSQL` method.''

== Studio environment ==

Some developers have requested a method allowing to know which environment the module is running on. While in general, your code should be the same on all environments so that the validation process makes sense, this may allow for example to display some helpers for testing during development while being sure that they'll never show up outside of the studio.

From your <gamename>.game.php file you can use:

<pre>if ($this->getBgaEnvironment() == 'studio') { ... }</pre>

Or if needed from your <gamename>.view.php file:

<pre>if ($this->game->getBgaEnvironment() == 'studio') { ... }</pre>

[[Category:Studio]]

Gamehelplivingforest

2024-09-26T17:13:34Z

Fletcheese: Added details on what Fire Varans do

==Summary==
'''Draw phase'''

Draw Guardian Animals. If you draw 3 solitary symbols [[File:Solitary1.PNG]] (top-left of the Guardian Animals cards) you cannot draw anymore (unless you've drawn gregarious symbols). You only get to use 1 standard Action (there are ways in the next phase to get bonus Actions). If you stop at a point where you have less then 3 solitary symbols, you get to use 2 standard different Actions. Solitary symbols can be canceled by gregarious symbols [[File:Gregarious.png]]. So 3 solitary symbols - 1 gregarious symbol = 2 solitary symbols = 2 different standard Actions.

'''Action phase'''

Choose one or more of the following Actions:
* ''Take a Fragment tile'': Take a Fragment tile. It can be played in a future Guardian Animal Phase to destroy a Fire Varan (fire card) or place a Guardian Animal card that you have just drawn back to your personal discard stack, regardless of its type.
* ''Attract one or more Guardian Animals'': Add up the amount of suns [[File:Sun.PNG]] you have to take one or more Guardian Animal cards visible in the reserve of Guardian Animals, for a total cost equal to or lower than your number of suns. The cost of a Guardian Animal is visible in the right-bottom corner of the card.
* ''Extinguish the Fire'': Add up the amount of water [[File:Water.PNG]] you have and pick one or more Fire tiles from the Circle of Spirits for a total cost equal to or lower than your number of water.
* ''Move forward on the Circle of Spirits'': Add up the number of spirals [[File:Spiral.PNG]] and move your Spirit of Nature standee clockwise on the Circle of Spirits by a number of rocks equal to or lower than your number of spirals. Gain the bonus of the rock you land on (may give specific extra Action), take a Victory tile of every player you jump over.
* ''Plant one and only one Protective Tree'': Add up the amount of leaves [[File:Leaf.PNG]] and take one, and only one, Protective Tree for a total cost equal to or lower than your number of leaves. By placing a Protective Tree on specific corners you gain a specific extra Action.

'''End of Game turn'''

It's fully automated, so you don't have to do a thing. Next turn starts after this.

== Goal of the game ==
The winner is the player that fulfills at least one of these 3 objectives:
* Plant 12 '''different''' Protective Trees
* Collect 12 Sacred Flowers
* Extinguish 12 Fires

The game stops at the end of a complete Action phase when one of the players has managed to complete one of these. If several players complete one of the three victory conditions at the end of a turn, then they add up the values of all three victory conditions. The player with the highest total wins.

== Game turn ==
Each Game turn includes 3 phases:

1. Guardian Animals (draw phase)

2. Action(s)

3. End of Game turn (''automated in BGA'')

=== 1. Guardian Animals ===
During this phase, all the Spirits of Nature (= players) play at the same time.

You draw and turn face up the Guardian Animals cards from your personal draw stack. This way you form your '''Guardian Animal Help Line'''.

If you want to draw a new Guardian Animal card to place in your Help Line , but your draw stack runs empty, then your discard stack gets shuffled to make a new draw stack. It is when you want to draw, and not when your draw stack turns empty, that you can make a new one.

You '''can''' stop drawing cards whenever you want. However, if you reveal a card showing a third solitary symbol [[File:Solitary1.PNG]], then you '''must''' stop drawing cards. This card closes your Help Line.

'''Important!''' A gregarious symbol [[File:Gregarious.png]] cancels a solitary symbol. It will therefore be possible to play more than 3 solitary Guardian Animals in the same turn, provided that you have already revealed one or more gregarious Guardian Animals. Note that only the symbol of the solitary Guardian Animal is canceled, the Elements will be taken into account in the Action phase.

You can find both the solitary and gregarious symbol in the top left corner of a Guardian Animals card.

'''Fragment tiles'''

[[File:Fragment.PNG]]

Whenever you want during this phase, you can discard a Fragment tile in order to, at choice:
* Destroy a Fire Varan card that you have just drawn. It is put back in the Fire Varan stack.
* Place a Guardian Animal card that you have just drawn back to your personal discard stack, regardless of its type.

After playing a Fragment, you can either stop or continue to draw.

Once all players have finished drawing their cards, the guardian Animals phase ends and you can move on to the Action phase.

===2. Action Phase===
During this phase, the players play '''in turn''', starting with the player possessing the Sacred Tree. At the start of the game the Sacred Tree is given to a random player. After every Game turn it is given to the next player clockwise.

If your Help Line shows '''less than 3 solitary symbols''' (not counting the ones canceled by gregarious symbols), you can then perform '''2 different Actions'''. For example, in your Help Line are 3 solitary symbols and 1 gregarious symbol, then only 2 solitary symbols count and you get 2 Actions.

If your Help Line shows '''3 solitary symbols''' (not canceled by gregarious symbols), you can then perform '''only 1 Action'''.

'''The different Actions:'''
* ''Take a Fragment tile'': Take a Fragment tile. It can be played in a future Guardian Animal Phase.
* ''Attract one or more Guardian Animals'': Add up the amount of suns [[File:Sun.PNG]] you have to take one or more Guardian Animal cards visible in the reserve of Guardian Animals, for a total cost equal to or lower than your number of suns. Place the card(s) '''on top''' of your personal draw stack. The cost of a Guardian Animal is visible in the right-bottom corner of the card.
* ''Extinguish the Fire'': Add up the amount of water [[File:Water.PNG]] you have and pick one or more Fire tiles from the Circle of Spirits for a total cost equal to or lower than your number of water. Reminder: having 12 Fire tiles (tiles, not the number on the Fire tile) is a way to win the game.
* ''Move forward on the Circle of Spirits'': Add up the number of spirals [[File:Spiral.PNG]] and move your Spirit of Nature standee clockwise on the Circle of Spirits by a number of rocks equal to or lower than your number of spirals.
If one or more Spirits of Nature are on a rock ahead of you, jump over them without counting their rocks and take one of their Victory tiles of your choice, whether it originally belongs to them or was taken from another player.

The rock you land on triggers a bonus. This an additional Action, it is added and may be different from or identical to the other Actions you take in your turn.
* ''Plant one and only one Protective Tree'': Add up the amount of leaves [[File:Leaf.PNG]] and take one, and only one, Protective Tree for a total cost equal to or lower than your number of leaves. Place it in your Forest, on a space adjacent to a Protective Tree already planted. Diagonal spaces do not count. Reminder: having 12 different Protective Trees is a way to win the game.
By completing specific rows or columns you gain extra permanent bonuses on top of the permanent bonuses provided by the Protective Trees. You can take it into account for your second Action and in following Game turns.

Planting a Protective Tree in a corner triggers an immediate bonus Action. This can only be used once per corner.

===3. End of Game turn===
''This phase is fully automated in BGA.''

'''Stage 1: Onibi attacks!'''

If some Fire tiles remain at the center of the Circle of Spirits, add up their values. Then, each player adds up their value in water [[File:Water.PNG]]. If this value in water is strictly lower than the strength of the Fire, add as many Fire Varan cards to your discard stack as there are Fire tiles at the center of the Circle of Spirits. Fire Varan cards count as solitary animals when drawn with no benefit - you do not want these.

'''Stage 2: Onibi is attacking the Sacred Tree'''

For each Guardian Animals card taken this turn, a Fire of a corresponding value is added to the Circle of Spirits:

*Level 1: Fire of value 2
*Level 2: Fire of value 3
*Level 3: Fire of value 4

There can never be more than 7 Fires in the center of the Circle of Spirits. If there are no more Fire tiles in the Circle of Spirits after stage 1, a Fire tile of value 2 is added, even if no Guardian Animals have been taken.

'''Stage 3: The arrival of new Guardian Animals'''

The Guardian Animals reserve is refilled by revealing as many new cards per level as there were cards taken this turn.

'''Stage 4: The Return of Guardian Animals'''

All Guardian Animals cards from your Help Line are moved to your personal discard stack.

'''Stage 5: Giving the Sacred Tree'''

The Sacred Tree (the starting token) is given to the next player clockwise.

The next Game turn begins.

== Kodama Expansion ==
The Kodama expansion adds a Kodama market and symbols, new trees, new guardian spirits, the Onibi standee, and new element tiles. Mainly, this expansion gives a new use for the pink flower symbol aside from the win condition. Additionally, the new win condition is set to 13, and not 12.

=== Kodama Symbols ===
Each player starts with 1 card with a solitary Kodama symbol in their deck. They can get more Kodama symbol cards from the market or one of the new trees available in the expansion. During a player's Guardian Animal draw phase, the receive bonuses when they reveal a certain number of Kodama symbols.

* 2 Kodama symbols can net you a (x) Fragment tile.
* 3 Kodama symbols can net you a (2Water/2Sun/2Tree) or (1Wind/1Flower) tile. Each of these tiles can only count as one of the listed element bonuses.
* 4 Kodama symbols can net you an additional action. This additional action cannot be the same as your other actions unless a new lvl 2 Guardian Animal Card or the 11 tree is in your play area.

=== New Kodama Trees ===
Except for the tree that says +1 Kodama, the other trees are bonuses multiplied by the Kodama symbols in your Guardian Animal run. e.g. the (Kodama) Water tree counts as 3 water if you pull 3 Kodama symbols in your Guardian Animal Run.

=== New Guardian Animals ===
There are 5 new lvl 2 and lvl 3 Guardian Animals in the market. The new lvl 2 animals allow you to take the action listed twice in the same turn (like the 11 tree, but temporary and specifically for one listed action.) The new lvl 3 Guardian Animals allow you to take an additional action of the listed type.

=== Kodama Market ===
The Kodama market is where you can add Kodama cards to your deck, using pink flower symbols as currency. Much like buying with sun, the new Kodama card is added face down to the top of your deck. You cannot buy more than 1 Kodama card even if you have a lot of flower symbols. When a Kodama card is purchased, the new Onibi standee will go around the wind board, jumping over any players tokens. Whenever Onibi jumps a player's token, a fire 2 is added to the center. Onibi will move:

* 3 wind spaces for a 2 player game;
* 2 wind spaces for a 3 player game; or
* 1 wind space for a 4 player game.

Main game logic: Game.php

2024-07-13T18:23:25Z

Fletcheese: /* Using player names */

{{Studio_Framework_Navigation}}

This is the main file for your game logic. Here you initialize the game, persist data, implement the rules and notify the client interface of changes.

This is the main class that implements the "server" callbacks. As it is a server it cannot initiate any data communicate with the game client (running in browser) and only can respond to client using notifications.

Your php class instance won't be in memory between two callbacks, every time client send a request a new class will be created, constructor will be called and eventually your callback function.

== File Structure ==

The details of how the file is structured are described directly with comments in the code skeleton provided to you.

Here is the basic structure:

* '''__construct''': the game constructor, where you define global variables and initiaze class members.
* '''setupNewGame''': initial setup of the game. Takes an array of players, indexed by player_id. Structure of each player includes player_name, player_canal, player_avatar, and flags indicating admin/ai/premium/order/language/beginner.
* '''getAllDatas''': where you retrieve all game data during a complete reload of the game. Return value must be associative array. Value of 'players' is reserved for returning players data from players table, if you set it it must follow certain rules
$result ['players'] = $this->getCollectionFromDb("SELECT player_id id, player_score score, player_no no, player_color color FROM player");
// Returned value must include ['players'][$player_id]]['score'] for scores to populate when F5 is pressed.
* '''getGameProgression''': where you compute the game progression indicator. Returns a number indicating percent of progression (0-100). Used to calculate ELO changes of remaining players when a player quits, or as a conceding requirement (in non-tournament 2 player games, a player may concede if the progression is at least 50%).
* Utility functions: your utility functions.
* Player actions: the entry points for players actions ([https://en.doc.boardgamearena.com/Players_actions:_yourgamename.action.php more info here]).
* Game state arguments: methods to return additional data on specific game states ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#args more info here]).
* Game state actions: the logic to run when entering a new game state ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#action more info here]).
* '''initTable''': (not part of template) - this function is called for every php callback by the framework and it can be implement by the game (empty by default). You can use it in rare cases where you need to read database and manipulate some data before any ANY php entry functions are called (such as getAllDatas,action*,st*, etc). Note: it is not called before arg* methods
* '''zombieTurn''': what to do it's the turn of a zombie player.
* '''upgradeTableDb''': function to migrate database if you change it after release on production.
* '''getGameName''': returns the game name. This will be setup when you create the project. If you are copying files in from another project, make sure you keep this function intact. It must return the right game name, or lots of things will be broken.

== Accessing player information ==

'''Important''': In the following methods, be mindful of the difference between the "active" player and the "current" player. The '''active''' player is the player whose turn it is - not necessarily the player who sent a request! The '''current''' player is the player who sent the request and will see the results returned by your methods: not necessarily the player whose turn it is!

; getPlayersNumber()
: Returns the number of players playing at the table
: Note: doesn't work in the beggining of setupNewGame (use count($players) instead). It will work after initialization of player table.

; getActivePlayerId()
: Get the "active_player", whatever what is the current state type.
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multiplayer"
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.

; getActivePlayerName()
: Get the "active_player" name
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.

; getPlayerNameById($player_id)
: Get the name by id

; getPlayerColorById($player_id)
: Get the color by id

; getPlayerNoById($player_id)
: Get 'player_no' (number) by id

; loadPlayersBasicInfos()
: Get an associative array with generic data about players (ie: not game specific data).
: The key of the associative array is the player id. The returned table is cached, so ok to call multiple times without performance concerns.
: The content of each value is:
: * player_name - the name of the player
: * player_color (ex: ff0000) - the color code of the player (as string)
: * player_no - the position of the player at the start of the game in natural table order, i.e. 1,2,3

<pre>
$players = $this->loadPlayersBasicInfos();
foreach ($players as $player_id => $info) {
$player_color = $info['player_color'];
...
}
</pre>
Note: if you want array of player ids only you can do this:
$player_ids = array_keys($this->loadPlayersBasicInfos());

; getCurrentPlayerId(bool $bReturnNullIfNotLogged = false) int
: Get the "current_player". The current player is the one from which the action originated (the one who sent the request).
: '''Be careful''': This is not necessarily the active player!
: In general, you shouldn't use this method, unless you are in "multiplayer" state.
: '''Very important''': in your setupNewGame and zombieTurn function, you must never use getCurrentPlayerId() or getCurrentPlayerName(),
: otherwise it will fail with a "Not logged" error message (these actions are triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to these actions).

; getCurrentPlayerName(bool $bReturnEmptyIfNotLogged = false) string
: Get the "current_player" name.
: Note: this will throw an exception if current player is not at the table, i.e. spectator
: Be careful using this method (see above).

; getCurrentPlayerColor()
: Get the "current_player" color.
: Note: this will throw an exception if current player is not at the table, i.e. spectator
: Be careful using this method (see above).

; isCurrentPlayerZombie()
: Check the "current_player" zombie status. If true, player is zombie, i.e. left or was kicked out of the game.
: Note: this will throw an exception if current player is not at the table, i.e. spectator

; isSpectator()
: Check the "current_player" spectator status. If true, the user accessing the game is a spectator (not part of the game). For this user, the interface should display all public information, and no private information (like a friend sitting at the same table as players and just spectating the game).

; getActivePlayerColor()
: This function does not seems to exist in API, if you need it here is implementation
function getActivePlayerColor() {
$player_id = $this->getActivePlayerId();
$players = $this->loadPlayersBasicInfos();
if (isset($players[$player_id]))
return $players[$player_id]['player_color'];
else
return null;
}
; isPlayerZombie($player_id)
: This method does not exists, but if you need it it looks like this
protected function isPlayerZombie($player_id) {
$players = $this->loadPlayersBasicInfos();
if (! isset($players[$player_id]))
throw new BgaSystemException("Player $player_id is not playing here");

return ($players[$player_id]['player_zombie'] == 1);
}

== Accessing the database ==

The main game logic should be the only point from which you should access the game database. You access your database using SQL queries with the methods below.

'''IMPORTANT'''

BGA uses [http://dev.mysql.com/doc/refman/5.0/en/sql-syntax-transactions.html database transactions]. This means that your database changes WON'T BE APPLIED to the database until your request ends normally (web request, not database request). Using transactions is in fact very useful for you; at any time, if your game logic detects that something is wrong (example: a disallowed move), you just have to throw an exception and all changes to the game situation will be removed. This also means that you need not (and in fact cannot) use your own transactions for multiple related database operations.

However there are sets of database operation that will do implicit commit (most common mistake is to use "TRUNCATE"), you cannot use these operations during the game, it breaks the unrolling of transactions and will lead to nasty issues
(https://mariadb.com/kb/en/sql-statements-that-cause-an-implicit-commit).

All methods below are part of game class (and view class) and can be accessed using $this->

; DbQuery( string $sql )
: This is the generic method to access the database.
: It can execute any type of SELECT/UPDATE/DELETE/REPLACE/INSERT query on the database. Returns result of the query.
: For SELECT queries, the specialized methods below are much better.
: Do not use method for TRUNCATE, DROP and other table altering operations. See disclamer above about implicit commits. If you really need TRUNCATE use DELETE FROM xxx instead.

; getUniqueValueFromDB( string $sql )
: Returns a unique value from DB or null if no value is found.
: $sql must be a SELECT query.
: Raise an exception if more than 1 row is returned.

; getCollectionFromDB( string $sql, bool $bSingleValue=false ) array
: Returns an associative array of rows for a sql SELECT query.
: The key of the resulting associative array is the first field specified in the SELECT query.
: The value of the resulting associative array is an associative array with all the field specified in the SELECT query and associated values.
: First column must be a primary or alternate key (semantically, it does not actually have to declared in sql as such).
: The resulting collection can be empty (it won't be null).
: If you specified $bSingleValue=true and if your SQL query requests 2 fields A and B, the method returns an associative array "A=>B", otherwise its A=>[A,B]
: Note: The name a bit misleading, it really return associative array, i.e. map and NOT a collection. You cannot use it to get list of values which may have duplicates (hence primary key requirement on first column). If you need simple array use getObjectListFromDB() method.

Example 1:
<pre>
$result = $this->getCollectionFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );

Result:
[
1234 => [ 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ],
1235 => [ 'id'=>1235, 'name'=>'myuser1', 'score'=>0 ]
]
</pre>

Example 2:
<pre>
$result = $this->getCollectionFromDB( "SELECT player_id id, player_name name FROM player", true );

Result:
[
1234 => 'myuser0',
1235 => 'myuser1'
]

</pre>

; getNonEmptyCollectionFromDB(string $sql) array
: Same as getCollectionFromDB($sdl), but raise an exception if the collection is empty. Note: this function does NOT have 2nd argument as previous one does.

; getObjectFromDB(string $sql) array
: Returns one row for the sql SELECT query as an associative array or null if there is no result (where fields are keys mapped to values)
: Raise an exception if the query return more than one row (you can use LIMIT 1 in the query to avoid the exception)

Example:
<pre>
$result = $this->getObjectFromDB( "SELECT player_id id, player_name name, player_score score FROM player WHERE player_id='$player_id'" );

Result:
[
'id'=>1234, 'name'=>'myuser0', 'score'=>1
]
</pre>

; getNonEmptyObjectFromDB(string $sql) array
: Similar to previous one, but raise an exception if no row is found

; getObjectListFromDB(string $sql, bool $bUniqueValue=false) array
: Return an array of rows for a sql SELECT query.
: The result is the same as "getCollectionFromDB" except that the result is a simple array (and not an associative array).
: The result can be empty.
: If you specified $bUniqueValue=true and if your SQL query request 1 field, the method returns directly an array of values.

Example 1:
<pre>
$result = $this->getObjectListFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );

Result:
[
[ 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ],
[ 'id'=>1235, 'name'=>'myuser1', 'score'=>0 ]
]
</pre>

Example 2:
<pre>
$result = $this->getObjectListFromDB( "SELECT player_name name FROM player", true );

Result:
[
'myuser0',
'myuser1'
]

</pre>

; getDoubleKeyCollectionFromDB(string $sql, bool $bSingleValue=false) array
: Return an associative array of associative array, from a SQL SELECT query.
: First array level correspond to first column specified in SQL query.
: Second array level correspond to second column specified in SQL query.
: If $bSingleValue = true, keep only third column on result

; DbGetLastId()
: Return the PRIMARY key of the last inserted row (see PHP mysql_insert_id function).

; DbAffectedRow() int
: Return the number of row affected by the last operation

; escapeStringForDB(string $string) string
: You must use this function on every string type data in your database that contains unsafe data.
: (unsafe = can be modified by a player).
: This method makes sure that no SQL injection will be done through the string used.
: Note: if you using standard types in ajax actions, like AT_alphanum it is sanitized before arrival,
: this is only needed if you manage to get unchecked string, like in the games where user has to enter text as a response.

<pre>

</pre>

Note: see Editing [[Game database model: dbmodel.sql]] to know how to define your database model.

== Use globals ==

Sometimes, you want a single global integer value for your game, and you don't want to create a DB table specifically for it.

You can do this with the BGA framework "global". Your value will be stored in the "global" table in the database, and you can access it with simple methods.

All methods below are members of the game class and should be accessed via $this->

'''initGameStateLabels(array $labelsMap): void'''

This method should be located at the beginning of constructor of ''yourgamename.game.php''. This is where you define the globals used in your game logic, by assigning them IDs.

You can define up to 80 globals, with IDs from 10 to 89 (inclusive, there can be gaps).
Also you must use this method to access value of game options [[Game_options_and_preferences:_gameoptions.inc.php]], in that case, IDs need to be between 100 and 199.
You must '''not''' use globals outside the range defined above, as those values are used by other components of the framework.

<pre>
function __construct() {
parent::__construct();
$this->initGameStateLabels([
"my_first_global_variable" => 10,
"my_second_global_variable" => 11,
"my_game_variant" => 100
]);
// other code ...
}
</pre>

NOTE: The methods below WILL throw an exception if label is not defined using the call above.

'''setGameStateInitialValue( string $label, int $value ): void'''

Initialize global value. This is not required if you ok with default value if 0. This should be called from setupNewGame function.

'''getGameStateValue( string $label, int $default = 0): int'''

Retrieve the value of a global. Returns $default if global is not been initialized (by setGameStateInitialValue).

NOTE: this method use globals "cache" if you directly manipulated globals table OR call this function after undoRestorePoint() - it won't work as expected.

<pre>
$value = $this->getGameStateValue('my_first_global_variable');
</pre>

For debugging purposes, you can have labels and value pairs send to client side by inserting that code in your "getAllDatas":

<pre>
$labels = array_keys($this->mygamestatelabels);
$result['myglobals'] = array_combine($labels, array_map([$this,'getGameStateValue'],$labels));
</pre>

That assumes you stored your label mapping in $this->mygamestatelabels in constructor
<pre>
$this->mygamestatelabels=["my_first_global_variable" => 10, ...];
$this->initGameStateLabels($this->mygamestatelabels);
</pre>

'''setGameStateValue( string $label, int $value ): void'''

Set the current value of a global.
<pre>
$this->setGameStateValue('my_first_global_variable', 42);
</pre>

'''incGameStateValue( string $label, int $increment ): int'''

Increment the current value of a global. If increment is negative, decrement the value of the global.

Return the final value of the global. If global was not initialized it will initialize it as 0.

NOTE: this method use globals "cache" if you directly manipulated globals table OR call this function after undoRestorePoint() - it won't work as expected.

<pre>
$value = $this->incGameStateValue('my_first_global_variable', 1);
</pre>

=== BGA predefined globals ===

BGA already defines some globals in the ''global'' database table. You should not change them directly but it can be useful to know what they mean when debugging:

{| class="wikitable"
|-
! global_id !! label !! Meaning
|-
| 1 || || Current state
|-
| 2 || || Active player id
|-
| 3 || next_move_id || Next move number
|-
| 4 || || Game id
|-
| 5 || || Table creator id
|-
| 6 || playerturn_nbr || Player turn number
|-
| 7 || gameprogression || Game progression
|-
| 8 || initial_reflexion_time || Initial reflection time
|-
| 9 || additional_reflexion_time || Additional reflection time
|-
| 200 || reflexion_time_profile || Reflexion time profile
|-
| 201 || bgaranking_mode || BGA ranking mode
|-
| 207 || game_language ||GAMESTATE_GAME_LANG
|-
| 300 || game_db_version ||GAMESTATE_GAMEVERSION: Current version of the game (when in production)
|-
| 301 || game_result_neutralized ||GAMESTATE_GAME_RESULT_NEUTRALIZED
|-
| 302 || neutralized_player_id ||GAMESTATE_NEUTRALIZED_PLAYER_ID
|-
| 304 || undo_moves_stored ||GAMESTATE_UNDO_MOVES_STORED
|-
| 305 || undo_moves_player ||GAMESTATE_UNDO_MOVES_PLAYER
|-
| 306 || lock_screen_timestamp ||GAMESTATE_LOCK_TIMESTAMP
|}

== Game states and active players ==

=== Activate player handling ===

; $this->activeNextPlayer()
: Make the next player active in the natural player order.
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.

; $this->activePrevPlayer()
: Make the previous player active (in the natural player order).
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.

; $this->gamestate->changeActivePlayer( $player_id )
: You can call this method to make any player active.
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.

; $this->getActivePlayerId()
: Return the "active_player" id
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multipleactiveplayer"
: Note: avoid using this method in a "multipleactiveplayer" state because it does not mean anything.

=== Multiple activate player handling ===

; $this->gamestate->setAllPlayersMultiactive()
: All playing players are made active. Update notification is sent to all players (this will trigger '''onUpdateActionButtons''').
: Usually, you use this method at the beginning of a game state (e.g., "stGameState") which transitions to a ''multipleactiveplayer'' state in which multiple players have to perform some action. Do not use this method if you going to make some more changes in the active player list. (I.e., if you want to take away multipleactiveplayer status immediately afterwards, use setPlayersMultiactive instead.)

Example of usage:
<pre>
function st_MultiPlayerInit() {
$this->gamestate->setAllPlayersMultiactive();
}
</pre>

; $this->stMakeEveryoneActive()
:this method can be used in state machine to make everybody active as "st" method of multiplayeractive state, it just calls $this->gamestate->setAllPlayersMultiactive()

This is to be used in state declaration:
<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' => 'stMakeEveryoneActive',
'args' => 'arg_playerTurnPlace',
"possibleactions" => array( "actionBla" ),
"transitions" => array( "next" => 4, "last" => 99)
),
</pre>

; $this->gamestate->setAllPlayersNonMultiactive( $next_state )
: All playing players are made inactive. Transition to next state

; $this->gamestate->setPlayersMultiactive( $players, $next_state, $bExclusive = false )
: Make a specific list of players active during a multiactive gamestate. Update notification is sent to all players whose state changed.
: "players" is the array of player id that should be made active. If "players" is not empty the value of "next_state" will be ignored (you can put whatever you want)
: If "bExclusive" parameter is not set or false it doesn't deactivate other previously active players. If its set to true, the players who will be multiactive at the end are only these in "$players" array

: In case "players" is empty, the method trigger the "next_state" transition to go to the next game state.
: returns true if state transition happened, false otherwise

; $this->gamestate->setPlayerNonMultiactive( $player_id, $next_state )
: During a multiactive game state, make the specified player inactive.
: Usually, you call this method during a multiactive game state after a player did his action. It is also possible to call it directly from multiplayer action handler.
: If this player was the last active player, the method trigger the "next_state" transition to go to the next game state.
: returns true if state transition happened, false otherwise
Example of usage (see state declaration of playerTurnPlace above):
<pre>
function actionBla($args) {
$this->checkAction('actionBla');
// handle the action using $this->getCurrentPlayerId()
$this->gamestate->setPlayerNonMultiactive( $this->getCurrentPlayerId(), 'next');
}
</pre>

; $this->gamestate->getActivePlayerList()
: With this method you can retrieve the list of the active player at any time.
: During a "game" type gamestate, it will return a void array.
: During a "activeplayer" type gamestate, it will return an array with one value (the active player id).
: During a "multipleactiveplayer" type gamestate, it will return an array of the active players id.
: Note: you should only use this method in the latter case.

; $this->gamestate->updateMultiactiveOrNextState( $next_state_if_none )
: Sends update notification about multiplayer changes. All multiactive set* functions above do that, however if you want to change state manually using db queries for complex calculations, you have to call this yourself after. Do not call this if you calling one of the other setters above.
Example: you have player teams and you want to activate all players in one team
<pre>
$sql = "UPDATE player SET player_is_multiactive='0'";
$this->DbQuery( $sql );
$sql = "UPDATE player SET player_is_multiactive='1' WHERE player_id='$player_id' AND player_team='$team_no'";
$this->DbQuery( $sql );

$this->gamestate->updateMultiactiveOrNextState( 'error' );
</pre>

; updating database manually
: Use this helper function to change multiactive state without sending notification
<pre>
/**
* Changes values of multiactivity in db, does not sent notifications.
* To send notifications after use updateMultiactiveOrNextState
* @param number $player_id, player id <=0 or null - means ALL
* @param number $value - 1 multiactive, 0 non multiactive
*/
function dbSetPlayerMultiactive($player_id = -1, $value = 1) {
if (! $value)
$value = 0;
else
$value = 1;
$sql = "UPDATE player SET player_is_multiactive = '$value' WHERE player_zombie = 0 and player_eliminated = 0";
if ($player_id > 0) {
$sql .= " AND player_id = $player_id";
}
$this->DbQuery($sql);
}
</pre>

;$this->gamestate->isPlayerActive($player_id)
:Return true if specified player is active right now.
:This method take into account game state type, ie nobody is active if game state is "game" and several players can be active if game state is "multiplayer"

;$this->bIndependantMultiactiveTable
:This flag can be set to true in constructor of game.php to force creation of second table to handle multiplayer states (normally these are in player table), this is very advanced feature.
:ONLY use it after you deploy you game to production if you receive unusual amount of bug report with dead lock symptoms DURING multiactiveplayer states
function __construct() {
...
$this->bIndependantMultiactiveTable=true;
}

=== States functions ===
; $this->gamestate->nextState( $transition )
: Change current state to a new state. Important: the $transition parameter is the name of the transition, and NOT the name of the target game state, see [[Your game state machine: states.inc.php]] for more information about states.

'''$this->gamestate->jumpToState($stateNum)'''
: Change current state to a new state. Important: the $stateNum parameter is the key of the state. See [[Your game state machine: states.inc.php]] for more information about states.
: Note: this is very advanced method, it should not be used in normal cases. Specific advanced cases include - jumping to specific state from "do_anytime" actions, jumping to dispatcher state or jumping to recovery state from zombie player function

; $this->checkAction( $actionName, $bThrowException=true )
: Check if the current player can perform a specific action in the current game state, and optionally throw an exception if they can't.
: The action is valid if it is listed in the "possibleactions" array for the current game state (see game state description).
: This method MUST be the first one called in ALL your PHP methods that handle player actions, in order to make sure a player doesn't perform an action not allowed by the rules at the point in the game. It should not be called from methods where the current player is not necessarily the active player, otherwise it may fail with an "It is not your turn" exception.
: If "bThrowException" is set to "false", the function returns '''false''' in case of failure instead of throwing an exception. This is useful when several actions are possible, in order to test each of them without throwing exceptions.

; $this->gamestate->checkPossibleAction( $action )
: (rarely used)
: This works exactly like "checkAction" (above), except that it does NOT check if the current player is active.
: '''Note: This does NOT check either spectator or eliminated status, so those checks must be done manually.'''
: This is used specifically in certain game states when you want to authorize additional actions for players that are not active at the moment.
: Example: in ''Libertalia'', you want to authorize players to change their mind about the card played. They are of course not active at the time they change their mind, so you cannot use "checkAction"; use "checkPossibleAction" instead.

This is how PHP action looks that returns player to active state (only for multiplayeractive states). To be able to execute this on client do not call checkAction on js side for this specific action.

function actionUnpass() {
$this->gamestate->checkPossibleAction('actUnpass'); // player changed mind about passing while others were thinking
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);
}

; $this->gamestate->state()
: Get an associative array of current game state attributes, see [[Your game state machine: states.inc.php]] for state attributes.

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

I suggest to define and use this function in your php class to access state name:

public function getStateName() {
$state = $this->gamestate->state();
return $state['name'];
}

; $this->gamestate->state_id()
: Get the id of the current game state (rarely useful, its best to use name, unless you use constants for state ids)

; $this->gamestate->isMutiactiveState()
: Return true if we are in multipleactiveplayer state, false otherwise

=== Private parallel states ===

See the overview of private parallel states [[Your_game_state_machine:_states.inc.php#Private_parallel_states|here]].

; $this->gamestate->initializePrivateStateForAllActivePlayers()
: All active players in a multiactive state are entering a first private state defined in the master state's initialprivate parameter.
: Every time you need to start a private parallel states you need to call this or similar methods below.
: Note: at least one player needs to be active (see [[#Multiple_activate_player_handling|above]]) and current game state must be a multiactive state with initialprivate parameter defined
: Note: initialprivate parameter of master state should be set to the id of the first private state. This private state needs to be defined in states.php with the type set to 'private'.
: Note: this method is usually preceded with activating some or all players
: Note: initializing private state can run action or args methods of the initial private state

Example of usage:
<pre>
function stStartPlayerTurn() {
// This is usually done in master state action method

$this->gamestate->setAllPlayersMultiactive();
$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("some_transition");
}

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

; $this->gamestate->initializePrivateStateForPlayers($playerIds)
: Players with specified ids are entering a first private state defined in the master state initialprivate parameter.
: Same considerations apply as for the method above.

; $this->gamestate->initializePrivateState($playerId)
: Player with the specified id is entering a first private state defined in the master state initialprivate parameter.
: Everytime you need to start a private parallel states you need to call this or similar methods above
: Note: player needs to be active (see [[#Multiple_activate_player_handling|above]]) and current game state must be a multiactive state with initialprivate parameter defined
: Note: initialprivate parameter of master state should be set to the id of the first private state. This private state needs to be defined in states.php with the type set to 'private'.
: Note: this method is usually preceded with activating that player
: Note: initializing private state can run action or args methods of the initial private state

Example of usage:
<pre>
function st_ChangeMind() {
// This player finished his move before, but now decides change something while other players are still active
// We activate the player and initialize his private state
$this->gamestate->setPlayersMultiactive([$this->getCurrentPlayerId()], "");
$this->gamestate->initializePrivateState(this->getCurrentPlayerId());

// It is also possible to move the player to some other specific state immediately
$this->gamestate->nextPrivateState($this->getCurrentPlayerId(), "some_transition");
}
</pre>

; $this->gamestate->nextPrivateStateForAllActivePlayers($transition)
: All active players will transition to next private state by specified transition
: Note: game needs to be in a master state which allows private parallel states
: Note: transition should lead to another private state (i.e. a state with type defined as 'private'
: Note: transition should be defined in private state in which the players currently are.
: Note: this method can run action or args methods of the target state
: Note: this is usually used after initializing the private state to move players to specific private state according to the game logic

Example of usage:
<pre>
function stStartPlayerTurn() {
// This is usually done in master state action method
$this->gamestate->setAllPlayersMultiactive();
$this->gamestate->initializePrivateStateForAllActivePlayers();

if ($specificOption) {
//move all players to different state
$this->gamestate->nextPrivateStateForAllActivePlayers("some_transition");
}
}
</pre>

; $this->gamestate->nextPrivateStateForPlayers($playerIds, $transition)
: Players with specified ids will transition to next private state specified by provided transition.
: Same considerations apply as for the method above.

; $this->gamestate->nextPrivateState($playerId, $transition)
: Player with specified id will transition to next private state specified by provided transition
: Note: game needs to be in a master state which allows private parallel states
: Note: transition should lead to another private state (i.e. a state with type defined as 'private'
: Note: transition should be defined in private state in which the players currently are.
: Note: this method can run action or args methods of the target state for specified player
: Note: this is usually used after some player actions to move to next private state

Example of usage:
<pre>
function actSomeAction() {
$this->checkAction("actSomeAction"); //needs to be defined in the current state
$this->gamestate->nextPrivateState($this->getCurrentPlayerId(), "some_transition");
}
</pre>

; $this->gamestate->unsetPrivateStateForAllPlayers()
: All players private state will be reset to null, which means they will get out of private parallel states and be in a master state like the private states are not used
: Note: game needs to be in a master state which allows private parallel states
: Note: this is usually used to clean up after leaving a master state in which private states were used, but can be used in other cases when we want to exit private parallel states and use a regular multiactive state for all players
: Note: After unseting private state only actions on master state are possible
: Note: Usually it is not necessary to unset private states as they will be initialized to first private state when private states are needed again. Nevertheless it is generally better to clean private state after exiting private parallel states to avoid bugs.

Example of usage:
<pre>
function stNextRound() {
$this->gamestate->unsetPrivateStateForAllPlayers();
}
</pre>

; $this->gamestate->unsetPrivateStateForPlayers($playerIds, $transition)
: For players with specified ids private state will be reset to null, which means they will get out of private parallel states and be in a master state like the private states are not used.
: Same considerations apply as for the method above.

; $this->gamestate->unsetPrivateState($playerId)
: For player with specified id private state will be reset to null, which means they will get out of private parallel states and be in a master state like the private states are not used
: Note: game needs to be in a master state which allows private parallel states
: Note: this is usually used when deactivating player to clean up their parallel state
: Note: After unseting private state only actions on master state are possible
: Note: Usually it is not necessary to unset private state as it will be initialized to first private state when private states are needed again. Nevertheless it is generally better to clean private state when not needed to avoid bugs.

Example of usage:
<pre>
function done() {
$this->gamestate->setPlayerNonMultiactive( $this->getCurrentPlayerId(), "newTurn" );
$this->gamestate->unsetPrivateState($this->getCurrentPlayerId());
}
</pre>

; $this->gamestate->setPrivateState($playerId, $newStateId)
: For player with specified id a new private state would be set
: Note: game needs to be in a master state which allows private parallel states
: Note: this should be rarely used as it doesn't check if the transition is allowed (it doesn't even specifies transition). This can be useful in very complex cases when standard state machine is not adequate (i.e. specific cards can lead to some micro action in various states where defining transitions back and forth can become very tedious.)
: Note: this method can run action or args methods of the target state for specified player

Example of usage:
<pre>
function actSomeAction() {
$this->checkAction("actSomeAction"); //needs to be defined in the current state

if ($playerHaveSpecificCard)
return $this->gamestate->setPrivateState($this->getCurrentPlayerId(), 35);

$this->gamestate->nextPrivateState($this->getCurrentPlayerId(), "some_transition");
}
</pre>

; $this->gamestate->getPrivateState($playerId)
: This return the private state or null if not initialized or not in private state

==== State Arguments in Private parallel states ====

The args method called for private states will have the player_id passed to it, allowing you to customise the arguments returned for that player.

Example of usage:
<pre>
function argMyPrivateState($player_id) {
return array(
'my_data' => $this->getPlayerSpecificData($player_id)
);
}
</pre>

==== Inactive Players ====

During Private Parallel State, active players will be managed by the private state that is current assigned to them.

Inactive players will be managed by the master multipleactiveplayer state, so your client should respond to that state in order to display any status message advising players that they are waiting for others to have their turn, or to add any buttons that allow players to potentially "break in" and become active.

== Players turn order ==

When table is created the "natural" player order is assigned to player at random, and stored in "read-only" field "player_no".
If you need to create a custom order you should never change natural order but have a separate data structure.
For example you can alter the players table to add another "custom_order" field, you can use state globals or you can use your natural board database,
to store meeple_color/position_location pair.
BGA currently does not provide any API to create/store custom player order.

'''getNextPlayerTable()'''

Return an associative array which associate each player with the next player around the table.

In addition, key 0 is associated to the first player to play.

Example: if three player with ID 1000, 2000 and 3000 are around the table, in this order, the method returns:
<pre>
array(
1000 => 2000,
2000 => 3000,
3000 => 1000,
0 => 1000
);
</pre>

'''getPrevPlayerTable()'''

Same as above, but the associative array associate the previous player around the table. However there no 0 index here.

'''getPlayerAfter( $player_id )'''

Get player playing after given player in natural playing order.

'''getPlayerBefore( $player_id )'''

Get player playing before given player in natural playing order.

Note: There is no API to modify this order, if you have custom player order you have to maintain it in your database
and have custom function to access it.

'''createNextPlayerTable( $players, $bLoop=true )'''

Using $players array creates a map of current => next as in example from getNextPlayerTable(), however you can use custom order here.
If parmeter $bLoop is set to true then last player will points to first (creaing a loop), false otherwise.
In any case index 0 points to first player (first element of $players array). $players is array of player ids in desired order.

Note: This function '''DOES NOT''' change the order in database, it only creates a map using key/values as descibed.

Example of usage:
<pre>
function getNextPlayerTableCustom() {
$starting = $this->getStartingPlayer(); // custom function to get starting player
$player_ids = $this->getPlayerIdsInOrder($starting); // custom function to create players array starting from starting player
return $this->createNextPlayerTable($player_ids, false); // create next player table in custom order
}
</pre>

<pre>
$table = $this->createNextPlayerTable([3000,2000,1000], false);

will return:
[
3000 => 2000,
2000 => 1000,
1000 => null,
0 => 3000
]
</pre>

== Notifications ==

To understand notifications, please read [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] first.

'''IMPORTANT'''

Notifications are crutial part of BGA framework. Everything players see, all changes which happen on frontend (including setup) are done via notfications.
Some of the are framework notifications and some of them are custom (game specific).
Generally you should not send or handle stanard notifications, except exposed APIs.
Example of standard notifications:
* game setup (first time client connects to game)
* game state change
* active player change
Example of custom notification
* game piece moved
* player scored points

Notifications are queued, i.e. sent at the very end of the action, when it ends normally. It means that if you throw an exception for any reason (i.e: move is not allowed), no notifications will be sent to players.

Notification can be sent from the following functions (and transive calls obviosly):

* action handler (action* in game.php). It is a MUST actually. At least one notificaton must be sent (but it includes state transition which sends it)
* game state transition (st* in game.php)
* setupNewGame (after player tables setup is finished)

Notification cannot be sent from the following:
* .view.php
* .action.php
* material.inc.php
* constructor of .game.php
* arg* methods of .game.php

There are conceptually two types of notification:
* public - sent to all client who are listening - that includes all players in the table and spectators
* private - that can only be sent to a player

The bundle of notifications is sent at the end action considered a single "move" and move counter increases.
If you ONLY sending private notifications during action handling - they will not have associate move_id (to avoid it add simple public notification with empty message).
In rare case if you want to change this behavior, you can apply some hackery described in [[BGA_Studio_Cookbook]]

Note: total notification size is now limited to 128K. It seems a lot, but don't forget that notification are bundled and only send at the end of action which also INCLUDES all game state transitions that follow.

The notifications are handled on JS side by subscribing to notifications (only do it for custom notifications!). See [Game_interface_logic:_yourgamename.js#Notifications]

=== NotifyAllPlayers ===

'''notifyAllPlayers(string $notification_type,string $message,array $notification_args )'''

Send a notification to all players of the game and spectators (public).

* notification_type: A string that defines the type of your notification.

Your game interface Javascript logic will use this to know what is the type of the received notification (and to trigger the corresponding method).

* message: A string that defines what is to be displayed in the game log.

You can use an empty string here (''). In this case, nothing is displayed in the game log.

Unless its empty, use "clienttranslate" method to make sure string is translated.

You can use arguments in your $notification_log string, that refers to values defines in the "$notification_args" argument (see below).
Note: Make sure you only use single quotes ('), otherwise PHP will try to interpolate the variable and will ignore the values in the args array.

* notification_args: The arguments of your notifications, as an associative array.

This array will be transmitted to the game interface logic, in order the game interface can be updated.

Complete notifyAllPlayers example (from "Reversi"):

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

You can see in the example above the use of the "clienttranslate" method, and the use of 2 arguments "player_name" and "returned_nbr" in the notification log.

'''Important''': NO private data must be sent with this method, as a cheater could see it even if it is not used explicitly by the game interface logic. If you want to send private information to a player, please use notifyPlayer below.

'''Important''': this array is serialized to be sent to the browsers, and will be saved with the notification to be able to replay the game later. If it is too big, it can make notifications slower / less reliable, and replay archives very big (to the point of failing). So as a general rule, you should send only the minimum of information necessary to update the client interface with no overhead in order to keep the notifications as light as possible.

'''Important''': When the game page is reloaded (i.e. F5 or when loading turn based game) all previous notifications are replayed as history notifications. These notifications do not trigger notification handlers and are used basically to build the game log. Because of that most of the notification arguments (except i18n, player_id and all arguments referenced in the message), are removed from these history notifications. If you need additional arguments in history notifications you can add special field preserve to notification arguments, like this:

<pre>
$this->notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),
array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'returned_nbr' => count( $turnedOverDiscs ),
'x' => $x,
'y' => $y,
'preserve' => [ 'x', 'y' ]
) );
</pre>
In this example, fields x and y will be preserved when replaying history notification at the game load.

NOTE: The ONLY reason 'preserve' is useful if you have custom method to render notifications in game log which changes some text arguments into html (i.e. to insert the images instead of plain text). Do not use preserve "just in case" - it will only bloat the logs and make game load VERY slow.

'''Important''': If both public and private notifications are sent to the same player in the same action (AJAX call), they will initially appear in the log in the order in which they were called, but they are placed into the game log in the following order: All private notifications first, then all public notifications. This means that when the page is refreshed, or when a player loads an asynchronous game, if you have called any public notifications ''before'' the last private notification, they will appear out of order in the log.

==== HTML in Notifications ====

You CAN use some HTML inside your notification log, however it not recommended for many reasons:
* Its bad architecture, ui elements leak into server now you have to manage ui in many places
* If you decided to change something in ui in a future version, old games replay and tutorials may not work, since they use stored notifications (for example if the change occured during the game and later this game is used for tutorial)
* When you read log preview for old games its unreadable (this is log before you enter the game replay, useful for troubleshooting or game analysis)
* Its more data to transfer and store in db
* Its nightmare for translators, at least don't put HTML tags inside the "clienttranslate" method. You can use a notification argument instead, and provide your HTML through this argument.

If you still want to have pretty pictures in the log check this [[BGA_Studio_Cookbook#Inject_images_and_styled_html_in_the_log]].

==== Recursive Notifications ====

If your notification contains some phrases that build programmatically you may need to use recursive notifications. In this case the argument can be not only the string but
an array itself, which contains 'log' and 'args', i.e.

$this->notifyAllPlayers('message',clienttranslate('Game moves ${token_name_rec}'),
['token_name_rec'=>['log'=>'${token_name} #${token_number}',
'args'=> ['token_name'=>clienttranslate('Boo'), 'token_number'=>$number, 'i18n'=>['token_name'] ]
]
]);

==== Excluding some players ====

Sometimes you want to notify all players of a message but not have it appear in the log of specific players (for example, have every player see "Player X draws a card" but have Player X will get a private notification "You draw the Ace of Spades", so you want them not to see the public one).

To send a notification to all players but have some clients ignore it, send it as normal from the server, but implement '''setIgnoreNotificationCheck''' on the client to ignore the message under given conditions. See the [[Game_interface_logic:_yourgamename.js#Ignoring_notifications]] documentation for more details. Note: do not sent private info with such notification, hiding something on client side is not a hacker safe.

==== Using player names ====

The variable for player name must be ${player_name} in order to be highlighted with the player color in the game log, it has to have matching 'player_id' argument in $notification_args. If you want a second player name in the log, name the variable ${player_name2} and $player_id2, etc. For the multiple player case, usage of player_id and player_name is not mandatory i.e. skipping to player_id1 and player_name1 is fine.

Special handling of arguments:
* ${player_name} - this will be wrapped in html and text shown using color of the corresponding player, some colors also have reserved background. This will apply recursively as well.
* ${player_name1}, ${player_name2}, ${player_name3}, etc. work the same as above
In order for this to work you must pass corresponding player_idX AND player_nameX in args i.e.

$this->notifyAllPlayers(
'buyAndPassCard',
clienttranslate('${player_name} buys ${card_name} and passes it to ${player_name2}'),
[
'player_id' => $player1['id'],
'player_name' => $player1['name'],
'player_id2' => $player2['id'],
'player_name2' => $player2['name'],
...
]
);

Note: player_name is not translatable, never add it to i18n array

=== NotifyPlayer ===

'''notifyPlayer(int $player_id, string $notification_type, string $message, $notification_args )'''

Same as above, except that the notification is sent to one player only. The player must be the player at the game table.

This method must be used each time some private information must be transmitted to a player.

Important: the variable for player name must be ${player_name} in order to be highlighted with the player color in the game log. Since its a private notification it may be more appropriate to use "you" insted

$this->notifyPlayer($player_id,'message',clienttranslate('You draw ${card_name}'), [ ... ]);
or
$this->notifyPlayer($player_id,'message',clienttranslate('${player_name} draws ${card_name}'), [ 'player_name' => $this->getPlayerNameById($player_id), ... ]);

Note: Spectators cannot be notified using this method, because their player ID is not available via loadPlayersBasicInfos() or otherwise. You must use notifyAllPlayers() for any notification that spectators should get.

== Randomization ==

A large number of board games rely on random, most often based on dice, cards shuffling, picking some item in a bag, and so on. This is very important to ensure a high level of randomness for each of these situations.

Here's are a list of techniques you should use in these situations, from the best to the worst.

=== Dice and bga_rand ===

'''bga_rand( min, max )'''
This is a BGA framework function that provides you a random number between "min" and "max" (inclusive), using the best available random method available on the system.

This is the preferred function you should use, because we are updating it when a better method is introduced.

As of now, bga_rand is based on the PHP function "random_int", which ensures a cryptographic level of randomness.

In particular, it is '''mandatory''' to use it for all '''dice throw''' (ie: games using other methods for dice throwing will be rejected by BGA during review).

Note: rand() and mt_rand() are deprecated on BGA and should not be used anymore, as their randomness is not as good as "bga_rand".

=== Arrays ===

Although PHP's "shuffle()" is generally considered good enough (see below, BGA's own Deck component uses this), the following PHP code based on "random_int" provides a cryptographically-secure method to choose a random key, value, or slice of an array. (the slice preserves keys)

<pre>
private function getRandomKey(array &$array)
{
$size = count($array);
if ($size == 0) {
trigger_error("getRandomKey(): Array is empty", E_USER_WARNING);
return null;
}
$rand = random_int(0, $size - 1);
$slice = array_slice($array, $rand, 1, true);
foreach ($slice as $key => $value) {
return $key;
}
}

private function getRandomValue(array &$array)
{
$size = count($array);
if ($size == 0) {
trigger_error("getRandomValue(): Array is empty", E_USER_WARNING);
return null;
}
$rand = random_int(0, $size - 1);
$slice = array_slice($array, $rand, 1, true);
foreach ($slice as $key => $value) {
return $value;
}
}

private function getRandomSlice(array &$array, int $count)
{
$size = count($array);
if ($size == 0) {
trigger_error("getRandomSlice(): Array is empty", E_USER_WARNING);
return null;
}
if ($count < 1 || $count > $size) {
trigger_error("getRandomSlice(): Invalid count $count for array with size $size", E_USER_WARNING);
return null;
}
$slice = [];
$randUnique = [];
while (count($randUnique) < $count) {
$rand = random_int(0, $size - 1);
if (array_key_exists($rand, $randUnique)) {
continue;
}
$randUnique[$rand] = true;
$slice += array_slice($array, $rand, 1, true);
}
return $slice;
}
</pre>

=== shuffle and cards shuffling ===

To shuffle items, like a pile of cards, the best way is to use the BGA PHP [[Deck]] component and to use "shuffle" method. This ensures that the best available shuffling method is used, and that if in the future we improve it your game will be up to date.

As of now, the Deck component shuffle method is based on PHP "shuffle" method, which has quite good randomness (even if not as good as bga_rand). In consequence, we accept other shuffling methods during reviews, as long as they are based on PHP "shuffle" function (or similar, like "array_rand").

=== Other methods ===

Mysql "RAND()" function has not enough randomness to be a valid method to get a random element on BGA. This function has been used in some existing games and has given acceptable results, but now it should be avoided and you should use other methods instead.

== Game statistics ==

There are 2 types of statistics:
* a "player" statistic is a statistic associated to a player
* a "table" statistic is a statistic not associated to a player (global statistic for this game).

See [[Game statistics: stats.inc.php]] to see how you define statistics for your game.

'''initStat( $table_or_player, $name, $value, $player_id = null )'''

Create a statistic entry with a default value.

This method must be called for each statistic of your game, in your setupNewGame method.
If you neglect to call this for a statistic, and also do not update the value during the course of a certain game using setStat or incStat, the value of the stat will be undefined rather than 0. This will result in it being ignored at the end of the game, as if it didn't apply to that particular game, and excluded from cumulative statistics. As a consequence - if do not want statistic to be applied, do not init it, or call set or inc on it.

'$table_or_player' must be set to "table" if this is a table statistic, or "player" if this is a player statistic.

'$name' is the name of your statistic, as it has been defined in your stats.inc.php file.

'$value' is the initial value of the statistic. If this is a player statistic and if the player is not specified by "$player_id" argument, the value is set for ALL players.

'''setStat( $value, $name, $player_id = null )'''

Set a statistic $name to $value.

If "$player_id" is not specified, setStat consider it is a TABLE statistic.

If "$player_id" is specified, setStat consider it is a PLAYER statistic.

'''incStat( $delta, $name, $player_id = null )'''

Increment (or decrement) specified statistic value by $delta value. Same behavior as setStat function.

'''getStat( $name, $player_id = null )'''

Return the value of statistic specified by $name. Useful when creating derivative statistics such as average.

== Translations ==

See [[Translations]]

== Manage player scores and Tie breaker ==

=== Normal scoring ===

At the end of the game, players automatically get a rank depending on their score: the player with the biggest score is #1, the player with the second biggest score is #2, and so on...

During the game, you update player's score directly by updating "player_score" field of "player" table in database.

Examples:
<pre>

// +2 points to active player
$this->DbQuery( "UPDATE player SET player_score=player_score+2 WHERE player_id='".self::getActivePlayerId()."'" );

// Set score of active player to 5
$this->DbQuery( "UPDATE player SET player_score=5 WHERE player_id='".self::getActivePlayerId()."'" );

</pre>

Note: don't forget to notify the client side in order the score control can be updated accordingly.

=== Tie breaker ===

Tie breaker is used when two players get the same score at the end of a game.

Tie breaker is using "player_score_aux" field of "player" table. It is updated exactly like the "player_score" field.

Tie breaker score is displayed only for players who are tied at the end of the game. Most of the time, it is not supposed to be displayed explicitly during the game.

When you are using "player_score_aux" functionality, you must describe the formula to use in your gameinfos.inc.php file like this:

<pre>
'tie_breaker_description' => totranslate("Describe here your tie breaker formula"),
</pre>

This description will be used as a tooltip to explain to players how this auxiliary score has been calculated.

See also [https://en.doc.boardgamearena.com/Game_meta-information:_gameinfos.inc.php#Multiple_tie_breaker_management Multiple Tie Breaker Management].

=== Co-operative game ===

To make everyone win/lose together in a full-coop game:

Add the following in gameinfos.inc.php :
'is_coop' => 1, // full cooperative

Assign a score of zero to everyone if it's a loss.
Assign the same score > 0 to everyone if it's a win.

=== Semi-coop ===

If the game is not full-coop, then everyone loses = everyone is tied. I.e. set score to 0 to everybody.

=== Only "winners" and "losers" ===

For some games, there is only a group (or a single) "winner", and everyone else is a "loser", with no "end of game rank" (1st, 2nd, 3rd...).

Examples:
* Coup
* Not Alone
* Werewolves
* Quantum

In this case:
* Set the scores so that the winner has the best score, and the other players have the same (lower) score.
* Add the following lines to gameinfos.inc.php:

<pre>
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true
// The game end result will display "Winner" for the 1st player and "Loser" for all other players
'losers_not_ranked' => true,
</pre>

Werewolves and Coup are implemented like this, as you can see here:
* https://boardgamearena.com/#!gamepanel?game=werewolves&section=lastresults
* https://boardgamearena.com/#!gamepanel?game=coupcitystate&section=lastresults

Adding this has the following effects:
* On game results for this game, "Winner" or "Loser" is going to appear instead of the usual "1st, 2nd, 3rd, ...".
* When a game is over, the result of the game will be "End of game: Victory" or "End of game: Defeat" depending on the result of the CURRENT player (instead of the usual "Victory of XXX").
* When calculating ELO points, if there is at least one "Loser", no "victorious" player can lose ELO points, and no "losing" player can win ELO point. Usually it may happened because being tie with many players with a low rank is considered as a tie and may cost you points. If losers_not_ranked is set, we prevent this behavior and make sure you only gain/loss ELO when you get the corresponding results.

Important: this SHOULD NOT be used for cooperative games (see is_coop parameter), or for 2 players games (it makes no sense in this case).

=== Solo ===

If game supports solo variant, a negative or zero score means defeat, a positive score means victory.

=== Player elimination ===

In some games, this is useful to eliminate a player from the game in order he/she can start another game without waiting for the current game end.

This case should be rare. Please don't use player elimination feature if some player just has to wait the last 10% of the game for game end. This feature should be used only in games where players are eliminated all along the game (typical examples: "Perudo" or "The Werewolves of Miller's Hollow").

Usage:

* Player to eliminate should NOT be active anymore (preferably use the feature in a "game" type game state).
* In your PHP code:
$this->eliminatePlayer( <player_to_eliminate_id> );
* the player is informed in a dialog box that he no longer have to play and can start another game if he/she wants too (with buttons "stay at this table" "quit table and back to main site"). In any case, the player is free to start & join another table from now.
* When your game is over, all players who have been eliminated before receive a "notification" (the small "!" icon on the top right of the BGA interface) that indicate them that "the game has ended" and invite them to review the game results.

'''Important:''' this should not be used on a player who has already left the game ("zombie") as leaving/being kicked of the game (outside of the scope of the rules) is not the same as being eliminated from the game (according to the rules), except if in the course of the game, the zombie player is eliminated according to the rules.

'''Important:''' When all surviving players are eliminated at the same time BGA framework causes the game to be abandoned automatically.
To circumvent this, the game should leave 1 player not eliminated but change final scores accordingly and end the game.

=== Scoring Helper functions ===

These functions should have been API but they are not, just add them to your php game and use for every game.

// get score
function dbGetScore($player_id) {
return $this->getUniqueValueFromDB("SELECT player_score FROM player WHERE player_id='$player_id'");
}

// set score
function dbSetScore($player_id, $count) {
$this->DbQuery("UPDATE player SET player_score='$count' WHERE player_id='$player_id'");
}

// set aux score (tie breaker)
function dbSetAuxScore($player_id, $score) {
$this->DbQuery("UPDATE player SET player_score_aux=$score WHERE player_id='$player_id'");
}

// increment score (can be negative too)
function dbIncScore($player_id, $inc) {
$count = $this->dbGetScore($player_id);
if ($inc != 0) {
$count += $inc;
$this->dbSetScore($player_id, $count);
}
return $count;
}

== Reflexion time ==

; function giveExtraTime( $player_id, $specific_time=null )
: Give standard extra time to this player.
: Standard extra time depends on the speed of the game (small with "slow" game option, bigger with other options).
: You can also specify an exact time to add, in seconds, with the "specified_time" argument (rarely used).

; function isAsync()
: Returns true if game is turn based, false if it is realtime

== Undo moves ==

Please read our [[BGA Undo policy]] before.

'''Important''': Before using these methods, you must also add the following to your "gameinfos.inc.php" file, otherwise these methods are ineffective:
'db_undo_support' => true

Note: if you deploy undo support after game is in production this will take into effect for new games only, old games will give user an error if user choses Undo action, but otherwise it should not affect them.

; function undoSavepoint( )
: Save the whole game situation inside an "Undo save point".
: There is only ONE undo save point available (see [[BGA Undo policy]]). Cannot use in multiactivate state or in game state where next state is multiactive.
: Note: this function does not actually do anything when it is called, it only raises the flag to store the database AFTER transaction is over. So the actual state will be saved when you exit the function calling it (technically before first queued notification is sent, which matters if you transition to game state not to user state after), this may affect what you end up saving.

; function undoRestorePoint()
: Restore the situation previously saved as an "Undo save point".
: You must make sure that the active player is the same after and before the undoRestorePoint (ie: this is your responsibility to ensure that the player that is active when this method is called is exactly the same than the player that was active when the undoSavePoint method has been called).

function actionUndo() {
$this->checkAction('actionUndo');
$this->undoRestorePoint();
$this->gamestate->nextState('next'); // transition to single player state (i.e. beginning of player actions for this turn)
}

'''Important note''': if you are reading game state variable right after restore (without changing state first) it won't work properly as the global table cache is not automatically refreshed after undoRestorePoint(). So you should either change state immediately to refresh game state values, or use $this->gamestate->reloadState() to refresh the state. If you choose to do the latest, be aware that this will bring the state machine back to the state during which the save point snapshot has been taken using undoSavepoint() (which means your transition you do after has to declared in the state which was saved, not in the state which was active for your actionUndo())

== Managing errors and exceptions ==

Note: when you throw an exception, all database changes and all notifications are cancelled immediately. This way, the game situation that existed before the request is completely restored.

; throw new BgaUserException ( $error_message)
: Base class to notify a user error
: You must throw this exception when a player wants to do something that they are not allowed to do.
: The error message will be shown to the player as a "red message".
: The error message must be translated, make sure you use self::_() or $this->_() here and NOT clientranslate()
: Throwing such an exception is NOT considered a bug, so it is not traced in BGA error logs.

Example from Gomoku:
<pre>
throw new BgaUserException( $this->_("There is already a stone on this intersection, you can't play there") );
</pre>

; throw new BgaVisibleSystemException ( $error_message)
: You must throw this exception when you detect something that is not supposed to happened in your code.
: The error message is shown to the user as an "Unexpected error", in order that he can report it in the forum.
: The error message is logged in BGA error logs. If it happens regularly, we will report it to you.

; throw new BgaSystemException ( $error_message)
: Base class to notify a system exception. The message will be hidden from the user, but show in the logs. Use this if the message contains technical information.
: You shouldn't use this type of exception except if you think the information shown could be critical. Indeed: a generic error message will be shown to the user, so it's going to be difficult for you to see what happened.

== Zombie mode ==

When a player leaves a game for any reason (expelled, quit), he becomes a "zombie player". In this case, the results of the game won't count for statistics, but this is cool if the other players can finish the game anyway. That's why zombie mode exists: allow the other player to finish the game, even if the situation is not ideal.

While developing your zombie mode, keep in mind that:
* Do not refer to the rules, because this situation is not planned by the rules.
* Try to figure that you are playing with your friends and one of them has to leave: how can we finish the game without killing the spirit of the game?
* The idea is NOT to develop an artificial intelligence for the game.
* Do not try to end the game early, even in a two-player game. The zombie is there to allow the game to continue, not to end it. Trying to end the game is not supported by the framework and will likely cause unexpected errors.

Most of the time, the best thing to do when it is zombie player turn is to jump immediately to a state where he is not active anymore. For example, if he is in a game state where he has a choice between playing A and playing B, the best thing to do is NOT to choose A or B, but to pass. So, even if there's no "pass" action in the rules, add a "zombiepass" transitition in your game state and use it.

Each time a zombie player must play, your "zombieTurn" method is called.

Parameters:
* $state: the name of the current game state.
* $active_player: the id of the active player.

Most of the time, your zombieTurn method looks like this:

<pre>
function zombieTurn( $state, $active_player )
{
$statename = $state['name'];

if( $statename == 'myFirstGameState'
|| $statename == 'my2ndGameState'
|| $statename == 'my3rdGameState'
....
)
{
$this->gamestate->nextState( "zombiePass" );
}
else
throw new BgaVisibleSystemException( "Zombie mode not supported at this game state: ".$statename );
}
</pre>

Note that in the example above, all corresponding game state should implement "zombiePass" as a transition.

'''Very important''': your zombie code will be called when the player leaves the game. This action is triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to this action. In your zombieTurn function, you must '''never''' use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message.

== User preferences ==
'''getGameUserPreference(int $playerId, int $prefId): ?int'''

Return the value of a user preference for a player. It will return the value currently selected in the select combo box, in the top-right menu.

== Player color preferences ==

BGA premium users may choose their preferred color for playing. For example, if they are used to play green for every board game, they can select "green" in their BGA preferences page.

Making your game compatible with colors preferences is very easy and requires only 1 line of configuration change:

On your gameinfos.inc.php file, add the following lines :

// Favorite colors support: if set to "true", support attribution of favorite colors based on player's preferences (see reattributeColorsBasedOnPreferences PHP method)
// NB: this parameter is used only to flag games supporting this feature; you must use (or not use) reattributeColorsBasedOnPreferences PHP method to actually enable or disable the feature.
'favorite_colors_support' => true,

Then, on your main <your_game>.game.php file check the code of "setupNewGame". New template already have correct code, but if you editing very old game and it may be absent.

$gameinfos = $this->getGameinfos();
...
if ($gameinfos['favorite_colors_support'])
$this->reattributeColorsBasedOnPreferences($players, $gameinfos['player_colors']); // this should be above reloadPlayersBasicInfos()
$this->reloadPlayersBasicInfos();

The "reattributeColorsBasedOnPreferences" method reattributes all colors, taking into account players color preferences and available colors.

Note that you must update the colors to indicate the colors available for your game.

Some important remarks:
* for some games (i.e. Chess), the color has an influence on a mechanism of the game, most of the time by giving a special advantage to a player (i.e. Starting the game). Color preference mechanism must NOT be used in such a case.
* your logic should NEVER consider that the first player has the color X, that the second player has the color Y, and so on. If this is the case, your game will NOT be compatible with reattributeColorsBasedOnPreferences as this method attribute colors to players based on their preferences and not based as their order at the table.

=== Custom color assignments ===
Some colors don't play nicely with BGA's color difference algorithm. If you receive feedback that colors are not well chosen, you can bypass the BGA algorithm by specifying a map from user preference colors to game colors.

For example, you may wish to assign BGA's blue to your game's baby blue: <code>"0000ff" /* Blue */ => "89CFF0",</code> whereas otherwise, a deep purple might be chosen instead. Just be sure that the assigned colors are also present in the <code>player_colors</code> array passed to <code>reattributeColorsBasedOnPreferences</code>, otherwise the assignment will be ignored.

To do this, implement this method in your <code>X.game.php</code> class.

Note: the user preference colors (the keys in the returned array) should not be modified, or the code may not work as expected. These are the colors players can choose between in their profile.
/**
* Returns an array of user preference colors to game colors.
* Game colors must be among those which are passed to reattributeColorsBasedOnPreferences()
* Each game color can be an array of suitable colors, or a single color:
* [
* // The first available color chosen:
* 'ff0000' => ['990000', 'aa1122'],
* // This color is chosen, if available
* '0000ff' => '000099',
* ]
* If no color can be matched from this array, then the default implementation is used.
*/
function getSpecificColorPairings(): array {
return array(
"ff0000" /* Red */ => null,
"008000" /* Green */ => null,
"0000ff" /* Blue */ => null,
"ffa500" /* Yellow */ => null,
"000000" /* Black */ => null,
"ffffff" /* White */ => null,
"e94190" /* Pink */ => null,
"982fff" /* Purple */ => null,
"72c3b1" /* Cyan */ => null,
"f07f16" /* Orange */ => null,
"bdd002" /* Khaki green */ => null,
"7b7b7b" /* Gray */ => null,
);
}

== Legacy games API ==

For some very specific games ("legacy", "campaign"), you need to keep some informations from a game to another.

This should be an exceptional situation: the legacy API is costing resources on Board Game Arena databases, and is slowing down the game setup process + game end of game process. Please do not use it for things like:
* keeping a player preference/settings (=> player preferences and game options should be used instead)
* keeping a statistics, a score, or a ranking, while it is not planned in the physical board game, or while there is no added value compared to BGA statistics / rankings.

You should use it for:
* legacy games: when some components of the game has been altered in a previous game and should be kept as it is.
* "campaign style" games: when a player is getting a "reward" at the end of a game, and should be able to use it in further games.

Important: you cannot store more than 64k of data (serialized as JSON) per player per game. If you go over 64k, storeLegacyData function is going to FAIL, and there is a risk to create a major bug (= players blocked) in your game. You MUST make sure that no more than 64k of data is used for each player for your game. For example, if you are implementing a "campaign style" game and if you allow a player to start multiple campaign, you must LIMIT the number of different campaign so that the total data size to not go over the limit. We strongly recommend you to use this:

try
{
$this->storeLegacyTeamData( $my_data );
}
catch( feException $e ) // feException is a base class of BgaSystemException and others...
{
if( $e->getCode() == FEX_legacy_size_exceeded )
{
// Do something here to free some space in Legacy data (ex: by removing some variables)
}
else
throw $e;
}

The keys may only contain letters and numbers, underscore seems not to be allowed.

; function storeLegacyData( $player_id, $key, $data, $ttl = 365 )
: Store some data associated with $key for the given user / current game
: In the opposite of all other game data, this data will PERSIST after the end of this table, and can be re-used
: in a future table with the same game.
: IMPORTANT: The only possible place where you can use this method is when the game is over at your table (last game action). Otherwise, there is a risk of conflicts between ongoing games.
: TTL is a time-to-live: the maximum, and default, is 365 days.
: In any way, the total data (= all keys) you can store for a given user+game is 64k (note: data is store serialized as JSON data)
: NOTICE: You can store some persistant data across all tables from your game using the specific player_id 0 which is unused. In such case, it's even more important to manage correctly the size of your data to avoid any exception or issue while storing updated data (ie. you can use this for some kind of leaderbord for solo game or contest)
: Note: This function cannot be called during game setup (will throw an error).

; function retrieveLegacyData( $player_id, $key )
: Get data associated with $key for the current game
: This data is common to ALL tables from the same game for this player, and persist from one table to another.
: Note: calling this function has an important cost => please call it few times (possibly: only ONCE) for each player for 1 game if possible
: Note: you can use '%' in $key to retrieve all keys matching the given patterns

; function removeLegacyData( $player_id, $key )
: Remove some legacy data with the given key
: (useful to free some data to avoid going over 64k)

; function storeLegacyTeamData( $data, $ttl = 365 )
: Same as storeLegacyData, except that it stores some data for the whole team within the current table and does not use a key
: Ie: if players A, B and C are at a table, the legacy data will be saved for future table with (exactly) A, B and C on the table.
: This is useful for games which are intended to be played several time by the same team.
: Note: the data total size is still limited, so you must implement catch the FEX_legacy_size_exceeded exception if it happens

; function retrieveLegacyTeamData()
: Same as retrieveLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)

; function removeLegacyTeamData()
: Same as removeLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)

== Players text input and moderation ==
This section concerns only games where the players have to write some words to play: games based on words, like "Just one" or "Codenames".

Some players will use your game to write insults or profanities. As this is part of the game and not in the game chat, these words cannot be reported by players and moderated.

If you met the following situation:

* You are asking a player to type a text (word(s) or sentence)
* The player can enter any text (this is not a pre-selection or anything you can control)
* This text is visible by at least one other player

Then, you must use the following method:

'''function logTextForModeration( $player_id, $text )'''

player_id = player who write the text

text = text that has been written

This function will have no visible consequence for your game, but will allow players to report the text to moderators if something happens.

== Language dependent games API ==

This API is used for games that are heavily language dependent. Two most common use cases are:
* Games that have a language dependent component that are not necessarily translatable, typically a list of words. (Think of games like Codenames, Decrypto, Just One...)
* Games with massive communication where players would like to ensure that all participants speak the same language. (Think of games like Werewolf, The Resistance, maybe even dixit...)

If this option is used, the table created will be limited only to users that have specific language in their profile. Player starting the game would be able to chose one of the languages they speak.

There is a new property language_dependency in gameinfos.inc.php which can be set like this:
'language_dependency' => false, //or if the property is missing, the game is not language dependent
'language_dependency' => true, //all players at the table must speak the same language
'language_dependency' => array( 1 => 'en', 2 => 'fr', 3 => 'it' ), //1-based list of supported languages

In the gamename.game.php file, you can get the id of selected language with the method '''getGameLanguage'''.
; function getGameLanguage()
: Returns an index of the selected language as defined in gameinfos.inc.php.

Languages currently available on BGA are:
'ar' => array( 'name' => "العربية", 'code' => 'ar_AE' ), // Arabic
'be' => array( 'name' => "беларуская мова", 'code' => 'be_BY' ), // Belarusian
'bn' => array( 'name' => "বাংলা", 'code' => 'bn_BD' ), // Bengali
'bg' => array( 'name' => "български език", 'code' => 'bg_BG' ), // Bulgarian
'ca' => array( 'name' => "català", 'code' => 'ca_ES' ), // Catalan
'cs' => array( 'name' => "čeština", 'code' => 'cs_CZ' ), // Czech
'da' => array( 'name' => "dansk", 'code' => 'da_DK' ), // Danish
'de' => array( 'name' => "deutsch", 'code' => 'de_DE' ), // German
'el' => array( 'name' => "Ελληνικά", 'code' => 'el_GR' ), // Greek
'en' => array( 'name' => "English", 'code' => 'en_US' ), // English
'es' => array( 'name' => "español", 'code' => 'es_ES' ), // Spanish
'et' => array( 'name' => "eesti keel", 'code' => 'et_EE' ), // Estonian
'fi' => array( 'name' => "suomi", 'code' => 'fi_FI' ), // Finnish
'fr' => array( 'name' => "français", 'code' => 'fr_FR' ), // French
'he' => array( 'name' => "עברית", 'code' => 'he_IL' ), // Hebrew
'hi' => array( 'name' => "हिन्दी", 'code' => 'hi_IN' ), // Hindi
'hr' => array( 'name' => "Hrvatski", 'code' => 'hr_HR' ), // Croatian
'hu' => array( 'name' => "magyar", 'code' => 'hu_HU' ), // Hungarian
'id' => array( 'name' => "Bahasa Indonesia", 'code' => 'id_ID' ), // Indonesian
'ms' => array( 'name' => "Bahasa Malaysia", 'code' => 'ms_MY' ), // Malaysian
'it' => array( 'name' => "italiano", 'code' => 'it_IT' ), // Italian
'ja' => array( 'name' => "日本語", 'code' => 'ja_JP' ), // Japanese
'jv' => array( 'name' => "Basa Jawa", 'code' => 'jv_JV' ), // Javanese
'ko' => array( 'name' => "한국어", 'code' => 'ko_KR' ), // Korean
'lt' => array( 'name' => "lietuvių", 'code' => 'lt_LT' ), // Lithuanian
'lv' => array( 'name' => "latviešu", 'code' => 'lv_LV' ), // Latvian
'nl' => array( 'name' => "nederlands", 'code' => 'nl_NL' ), // Dutch
'no' => array( 'name' => "norsk", 'code' => 'nb_NO' ), // Norwegian
'oc' => array( 'name' => "occitan", 'code' => 'oc_FR' ), // Occitan
'pl' => array( 'name' => "polski", 'code' => 'pl_PL' ), // Polish
'pt' => array( 'name' => "português", 'code' => 'pt_PT' ), // Portuguese
'ro' => array( 'name' => "română", 'code' => 'ro_RO' ), // Romanian
'ru' => array( 'name' => "Русский язык", 'code' => 'ru_RU' ), // Russian
'sk' => array( 'name' => "slovenčina", 'code' => 'sk_SK' ), // Slovak
'sl' => array( 'name' => "slovenščina", 'code' => 'sl_SI' ), // Slovenian
'sr' => array( 'name' => "Српски", 'code' => 'sr_RS' ), // Serbian
'sv' => array( 'name' => "svenska", 'code' => 'sv_SE' ), // Swedish
'tr' => array( 'name' => "Türkçe", 'code' => 'tr_TR' ), // Turkish
'uk' => array( 'name' => "Українська мова", 'code' => 'uk_UA' ), // Ukrainian
'zh' => array( 'name' => "中文 (漢)", 'code' => 'zh_TW' ), // Traditional Chinese (Hong Kong, Macau, Taiwan)
'zh-cn' => array( 'name' => "中文 (汉)", 'code' => 'zh_CN' ), // Simplified Chinese (Mainland China, Singapore)

== Debugging and Tracing ==

To debug php code you can use some tracing functions available from the parent class such as debug, trace, error, warn, dump.

$this->debug("Ahh!");
$this->dump('my_var',$my_var);

See [[Practical_debugging]] section for complete information about debugging interfaces and where to find logs.

== PHP 8 upgrade ==

See [[PHP 8 upgrade]]

[[Category:Studio]]

Tips earth

2024-04-15T00:06:53Z

Fletcheese: /* Ecosystem / Terrain */

== Overview ==

Earth is an engine building resource management with min-max/optimization at its core. There are numerous factors to consider for every decision. This is overwhelming at first, but as you play more you start recognizing more and more factors and begin to understand how to weigh them against each other. Some decisions come down to card knowledge. E.g. where do I place this card now to account for a maximum number of future drawn cards that consider position? The most weight should be placed on factors that exist now, but the best players will eek out edges by considering potential future factors too.
 
• Note that this advice is largely geared toward 2-player games because this is the competitive format.

== Which action to pick? ==

=== Planting ===

The highest interaction point of Earth is on planting. Whoever completes their board first not only gets 7 bonus points (you should think of this as a 14-point swing in 2-player games because zero-sum), but also is setting the pace for the game. This principle rules in most if not all games where the end criteria is determined by some form of board completion - the player who is ahead on completion status is controlling the pace of the game and *much* more likely to win. If you have two things that you can Plant and a fairly high likelihood of being able to follow your opponent's Plant action (consider that you get to choose 1 of 4 which is fairly likely to yield a cheap option) then you should do it. At its core, there is a race happening in this game and the player who picks Plant more frequently is winning it.
 
This leads us into the next question: what should I plant and where? Early in the game, the answer is usually "whatever you have". But later in the game as you get more cards, the answer becomes more nuanced.

==== Engine ====

• Green cards are very good. Plant is the most picked action so anything extra you can do in response to Planting is guaranteed money in the bank.
 
• After Green, the best actions are those that let you do more Planting. Some consideration should be given to "what color does my opponent have a lot of and is thus more likely to pick?" If you Plant actions of that color, then you can get more "follow" bonuses. But as we've already said, they should be picking Plant as often as possible so this is less important than:
 
• "What do I want to do if I can't plant?" The answer is either get more cards or get more soil. Ideally both. So the best thing you can do is add card draw to your Red/Blue action OR add Soil gain to your Yellow action. Then when you can't Plant, use the action that lets you double-dip on Soil and card draw.
 
• Don't forget that Sprouts are just inefficient soil (3->2) so the Blue action actually yields *6* Soil, 1 MORE than Red at the cost of 2 Compost (assuming you have the prerequisite number of open Sprout places, but you can always convert them to Soil beforehand). Until the late game, you should be using your sprouts for soil whenever you need it to do more Planting. In the late game you have to weigh the points lost in Sprouts against the extra points gained from planting a "better" card.

==== Fauna ====

This is the second highest interaction element of Earth after Planting. The player who first achieves each goal is getting +4 points (8-point swing for 2-player). While less important than Plant-maxing, this is still a considerable difference. And you know about all Fauna from the start of the game so it should immediately begin impacting all of your decisions adding a little bit of weight to Plant each card that matches some Fauna conditions especially for those that match multiple.
 
Even if you lose the race to a Fauna, it's still 11 points which weighs pretty heavily. It can still be correct to give up or forgo Fauna, just depends on the options being weighed.

==== Ecosystem / Terrain ====

These are being lumped together because they're effectively the same thing. There is no race with the opponent so they amount to solo goals. Ecosystems are known from the start so you can immediately start factoring them into what you play whereas Terrain can be drawn at any point in the game. This is why card knowledge is important. You cannot *rely* on getting a specific Terrain, but if you've accounted for it with your board positioning, then you've set yourself up for additional beneficial scenarios if you get lucky. Success is when preparation meets opportunity :)

==== Where? ====

Considerations for where to Plant each card are fairly limited, but this is a potential area for gaining an edge in close games:
 
• Stay open as long as reasonably possible. Once you have a row or column of length 4, your board is "locked". Until then you have the freedom to plant in more positions. Maintaining this freedom can net you better opportunities later in the game.
 
• Most important is Ecosystems and Terrain that have already been played or you have in hand and plan to play over the course of the game.
 
• After that is logical order of resolution. You want to draw cards before you have to Compost from your hand via some other action. Secondary to that are things like gaining Growth/Sprouts to later spend in your turn for costs, but you will almost always already have this so you can simply replace it later in the turn.
 
• Then the last consideration is what position-based Terrain cards could I draw into later in the game that I want to be able to play? I still don't know all the cards, but ones that come to mind are the Habitat-based "path" cards (draw a line of cards that share a habitat) and the plant-type directionals (in this row, in this column, orthogonally adjacent, etc). It is impossible to account for every Terrain, but accounting for as many as possible will help you win more games

=== Not Planting (anything else) ===

See the Engine section above. None of the actions are bad, but what to pick just depends on what you and the opponent have already played. Always look at your opponent's board - don't pick actions that help your opponent more than they help you. You're typically only even considering this if you can't pick Plant or if you're in a late game situation where you can dominate your opponent on points per action.

== End Game ==

As the end of the game approaches (one player has 3 empty spaces on the board), there are new important considerations.
 
• Double check who went first. If the second/last player completes their board, then the game ends after their turn. Otherwise everyone after that player gets another turn. Make sure you factor this into your plans for what you want to Plant before the game ends.
 
• Tally up your Terrain and Ecosystem goals. Many of these give points based on sets/pairs/trios. If you're close to one of these thresholds (e.g. odd number for a pair-based bonus), add some priority to getting that last item.
 
• There is a lot of nuance around picking Plant later in the game depending on who is winning the race and how many empty spaces each player has left. The ideal scenario is one in which you have 1 empty space and your opponent has at least 3 empty spaces. The key to manufacturing this game state is to Plant early and often which is why this is emphasized so heavily
 
• Example 1: you have 3 empty board spaces and your opponent has 4. If you pick Plant then the result is you have 1 and opponent has 3. This is good because if your opponent picks Plant, you get the 7-point bonus and the game will end. A similar scenario occurs even if it is your opponent's turn. They Plant down to 2 empty spaces as do you. You can pick your final Plant, get the 7 points, and the opponent only has 1 empty spot at which point the game ends if you're second or they can do one last "inefficient" Plant action for the last space.
 
• Example 2: you have 2 empty and your opponent has 3 and it's your turn. If you went second then picking Plant ends the game - great. But if you went first, then your opponent is effectively given a "free" Plant where you cannot follow. You plant to 0 empty, opponent is at 2, then they can Plant again while you can't. A notably exception to this is if you have some Terrain that lets you replace it with a Plant from your hand. Choosing not to plant is just as bad because you now have to pick an "inefficient" last Plant of 1 or forgo the 7-point bonus entirely.
 
• Example 3: you both have 3 empty board spaces. This is a standoff position. Neither player wants to Plant because the result is that the opponent will win the 7-point bonus (tie for completion on the same turn goes to turn-player). Whoever has the bigger engine is favored here. By that we mean some combination of Sprout/Growth room and the resulting points per action noting that Compost and some specific Terrain bonuses do not have limits (e.g. 1 point per card in hand).

=== Conclusion ===

Hope this is helpful to some people. I have still not played many Earth games, but it clearly has high strategic depth. You may or may not find that depth to be interesting as the highest levels of play emphasize deep knowledge of all the cards, but there's a lot of room for interesting decisions leading up to that level.

Troubleshooting

2024-03-17T21:32:07Z

Fletcheese: Undo revision 20505 by Fletcheese (talk) - error already covered, but I missed it

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]]

Troubleshooting

2024-03-17T21:30:30Z

Fletcheese: Added error case and fix

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.

=== Javascript error: During pageload undefined no_stack_avail ===
Ensure that handlers exist for all notifications that are being subscribed in setupNotifications. E.g. if you have the following:

dojo.subscribe( 'name', this, 'notif_name' );

Ensure that a function named exactly "notif_name" exists '''in your base game.js 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]]

Tips earth

2024-02-16T18:09:17Z

Fletcheese:

== Overview ==

Earth is an engine building resource management with min-max/optimization at its core. There are numerous factors to consider for every decision. This is overwhelming at first, but as you play more you start recognizing more and more factors and begin to understand how to weigh them against each other. Some decisions come down to card knowledge. E.g. where do I place this card now to account for a maximum number of future drawn cards that consider position? The most weight should be placed on factors that exist now, but the best players will eek out edges by considering potential future factors too.
 
• Note that this advice is largely geared toward 2-player games because this is the competitive format.

== Which action to pick? ==

=== Planting ===

The highest interaction point of Earth is on planting. Whoever completes their board first not only gets 7 bonus points (you should think of this as a 14-point swing in 2-player games because zero-sum), but also is setting the pace for the game. This principle rules in most if not all games where the end criteria is determined by some form of board completion - the player who is ahead on completion status is controlling the pace of the game and *much* more likely to win. If you have two things that you can Plant and a fairly high likelihood of being able to follow your opponent's Plant action (consider that you get to choose 1 of 4 which is fairly likely to yield a cheap option) then you should do it. At its core, there is a race happening in this game and the player who picks Plant more frequently is winning it.
 
This leads us into the next question: what should I plant and where? Early in the game, the answer is usually "whatever you have". But later in the game as you get more cards, the answer becomes more nuanced.

==== Engine ====

• Green cards are very good. Plant is the most picked action so anything extra you can do in response to Planting is guaranteed money in the bank.
 
• After Green, the best actions are those that let you do more Planting. Some consideration should be given to "what color does my opponent have a lot of and is thus more likely to pick?" If you Plant actions of that color, then you can get more "follow" bonuses. But as we've already said, they should be picking Plant as often as possible so this is less important than:
 
• "What do I want to do if I can't plant?" The answer is either get more cards or get more soil. Ideally both. So the best thing you can do is add card draw to your Red/Blue action OR add Soil gain to your Yellow action. Then when you can't Plant, use the action that lets you double-dip on Soil and card draw.
 
• Don't forget that Sprouts are just inefficient soil (3->2) so the Blue action actually yields *6* Soil, 1 MORE than Red at the cost of 2 Compost (assuming you have the prerequisite number of open Sprout places, but you can always convert them to Soil beforehand). Until the late game, you should be using your sprouts for soil whenever you need it to do more Planting. In the late game you have to weigh the points lost in Sprouts against the extra points gained from planting a "better" card.

==== Fauna ====

This is the second highest interaction element of Earth after Planting. The player who first achieves each goal is getting +4 points (8-point swing for 2-player). While less important than Plant-maxing, this is still a considerable difference. And you know about all Fauna from the start of the game so it should immediately begin impacting all of your decisions adding a little bit of weight to Plant each card that matches some Fauna conditions especially for those that match multiple.
 
Even if you lose the race to a Fauna, it's still 11 points which weighs pretty heavily. It can still be correct to give up or forgo Fauna, just depends on the options being weighed.

==== Ecosystem / Terrain ====

These are being lumped together because they're effectively the same thing. There is no race with the opponent so they amount to solo goals. Ecosystems are known from the start so you can immediately start factoring them into what you play whereas Terrain can be drawn at any point in the game. This is why card knowledge is important. You cannot *rely* on getting a specific Terrain, but if you've accounted for it with your board positioning, then you've set yourself up for additional beneficial scenarios if you get lucky. Success is when luck meets opportunity :)

==== Where? ====

Considerations for where to Plant each card are fairly limited, but this is a potential area for gaining an edge in close games:
 
• Stay open as long as reasonably possible. Once you have a row or column of length 4, your board is "locked". Until then you have the freedom to plant in more positions. Maintaining this freedom can net you better opportunities later in the game.
 
• Most important is Ecosystems and Terrain that have already been played or you have in hand and plan to play over the course of the game.
 
• After that is logical order of resolution. You want to draw cards before you have to Compost from your hand via some other action. Secondary to that are things like gaining Growth/Sprouts to later spend in your turn for costs, but you will almost always already have this so you can simply replace it later in the turn.
 
• Then the last consideration is what position-based Terrain cards could I draw into later in the game that I want to be able to play? I still don't know all the cards, but ones that come to mind are the Habitat-based "path" cards (draw a line of cards that share a habitat) and the plant-type directionals (in this row, in this column, orthogonally adjacent, etc). It is impossible to account for every Terrain, but accounting for as many as possible will help you win more games

=== Not Planting (anything else) ===

See the Engine section above. None of the actions are bad, but what to pick just depends on what you and the opponent have already played. Always look at your opponent's board - don't pick actions that help your opponent more than they help you. You're typically only even considering this if you can't pick Plant or if you're in a late game situation where you can dominate your opponent on points per action.

== End Game ==

As the end of the game approaches (one player has 3 empty spaces on the board), there are new important considerations.
 
• Double check who went first. If the second/last player completes their board, then the game ends after their turn. Otherwise everyone after that player gets another turn. Make sure you factor this into your plans for what you want to Plant before the game ends.
 
• Tally up your Terrain and Ecosystem goals. Many of these give points based on sets/pairs/trios. If you're close to one of these thresholds (e.g. odd number for a pair-based bonus), add some priority to getting that last item.
 
• There is a lot of nuance around picking Plant later in the game depending on who is winning the race and how many empty spaces each player has left. The ideal scenario is one in which you have 1 empty space and your opponent has at least 3 empty spaces. The key to manufacturing this game state is to Plant early and often which is why this is emphasized so heavily
 
• Example 1: you have 3 empty board spaces and your opponent has 4. If you pick Plant then the result is you have 1 and opponent has 3. This is good because if your opponent picks Plant, you get the 7-point bonus and the game will end. A similar scenario occurs even if it is your opponent's turn. They Plant down to 2 empty spaces as do you. You can pick your final Plant, get the 7 points, and the opponent only has 1 empty spot at which point the game ends if you're second or they can do one last "inefficient" Plant action for the last space.
 
• Example 2: you have 2 empty and your opponent has 3 and it's your turn. If you went second then picking Plant ends the game - great. But if you went first, then your opponent is effectively given a "free" Plant where you cannot follow. You plant to 0 empty, opponent is at 2, then they can Plant again while you can't. A notably exception to this is if you have some Terrain that lets you replace it with a Plant from your hand. Choosing not to plant is just as bad because you now have to pick an "inefficient" last Plant of 1 or forgo the 7-point bonus entirely.
 
• Example 3: you both have 3 empty board spaces. This is a standoff position. Neither player wants to Plant because the result is that the opponent will win the 7-point bonus (tie for completion on the same turn goes to turn-player). Whoever has the bigger engine is favored here. By that we mean some combination of Sprout/Growth room and the resulting points per action noting that Compost and some specific Terrain bonuses do not have limits (e.g. 1 point per card in hand).

=== Conclusion ===

Hope this is helpful to some people. I have still not played many Earth games, but it clearly has high strategic depth. You may or may not find that depth to be interesting as the highest levels of play emphasize deep knowledge of all the cards, but there's a lot of room for interesting decisions leading up to that level.

Tips barenpark

2024-01-17T23:25:01Z

Fletcheese:

Bärenpark is mostly about tactics rather than long term strategy. The two key points are: 1) be efficient filling your park, and 2) pay attention to what your opponents are doing.

== Be efficient ==

Being efficient at filling up your park means things that you may have already realised if you've been playing Bärenpark for a while such as:

a) Never end your turn without a tile in hand that you can place on your next turn.

b) Minimize the number of 1 square holes you end up. Typically if you are forced into taking a 1 square piece to fill a gap, then that means you made a mistake. Review your game and try to play more flexibly

c) Take the best tile you can. While you are allowed to pick up a tile from a lower tier when you cover up an orange excavator or white cement truck, this is always the wrong decision unless the supply has run out. You should plan ahead to ensure that you are able to play maximum value pieces

d) Use the "try mode" to help you work out how you can best fit tiles in your park efficiently.

e) Think carefully about how you place your new park areas. You probably want to cover up either the orange excavator and/or the white cement mixers quickly. Getting early pick of the enclosure tiles means getting more choice of shapes and tiles worth more points. Similarly being able to get more than your share of animal houses can give you a significant advantage over your opponent/s.

f) Try to remain flexible and leave yourself open to multiple options for efficiently filling up your remaining space, when possible.

Beginners quite often overvalue completing park areas for the bear statues points. The difference between a bear statue and the one underneath it is only 1 point (or 2 points in 2p which amounts to a 4p swing because zero-sum). You don't want to ignore this entirely but putting off completing an area for a few turns may allow you to get more points from claiming achievements or getting higher value animal houses (3p diff, 6p swing for 2-player) and enclosures than you would've got from getting an earlier bear statue. The real trick is to know when to do this which leads into point 2...

== Pay attention to what your opponents are doing ==

All the ways to score points in Bärenpark are potentially worth more points the earlier you do them (achievements, bear statues, animal houses & enclosures). But it's just not possible to be quick at all of these at once. Take a quick moment to assess your opponents' boards and the supply. What are your opponents working towards? What tiles in the supply might be gone before your next turn?

No matter what an opponent is focusing on, they will be neglecting something else. Or even better, you may see an opportunity where you can beat them to an achievement they've been working towards and then they'll have to settle for a lower amount of points for it.

Generally the best time to claim any achievement (or bear statue) is the exact turn before your opponent is about to get it. If there's no way your opponents can beat you to the achievement you've been working towards before your next turn, it may be worth doing something else with this turn and claiming the achievement next turn instead. But remember to always be efficient at filling up your park too.

Tips barenpark

2024-01-17T23:23:16Z

Fletcheese: Clarifying some language

Bärenpark is mostly about tactics rather than long term strategy. The two key points are: 1) be efficient filling your park, and 2) pay attention to what your opponents are doing.

== Be efficient ==

Being efficient at filling up your park means things that you may have already realised if you've been playing Bärenpark for a while such as:

a) Never end your turn without a tile in hand that you can place on your next turn.

b) Minimize the number of 1 square holes you end up. Typically if you are forced into taking a 1 square piece to fill a gap, then that means you made a mistake. Review your game and try to play more flexibly

c) Take the best tile you can. While you are allowed to pick up a tile from a lower tier when you cover up an orange excavator or white cement truck, this is always the wrong decision unless the supply has run out. You should plan ahead to ensure that you are able to play maximum value pieces

d) Use the "try mode" to help you work out how you can best fit tiles in your park efficiently.

e) Think carefully about how you place your new park areas. You probably want to cover up either the orange excavator and/or the white cement mixers quickly. Getting early pick of the enclosure tiles means getting more choice of shapes and tiles worth more points. Similarly being able to get more than your share of animal houses can give you a significant advantage over your opponent/s.

f) Try to remain flexible and leave yourself open to multiple options for efficiently filling up your remaining space, when possible.

Beginners quite often overvalue completing park areas for the bear statues points. The difference between a bear statue and the one underneath it is only 1 point (or 2 points in 2p). You don't want to ignore this entirely but putting off completing an area for a few turns may allow you to get more points from claiming achievements or getting higher value animal houses and enclosures than you would've got from getting an earlier bear statue. The real trick is to know when to do this which leads into point 2...

== Pay attention to what your opponents are doing ==

All the ways to score points in Bärenpark are potentially worth more points the earlier you do them (achievements, bear statues, animal houses & enclosures). But it's just not possible to be quick at all of these at once. Take a quick moment to assess your opponents' boards and the supply. What are your opponents working towards? What tiles in the supply might be gone before your next turn?

No matter what an opponent is focusing on, they will be neglecting something else. Or even better, you may see an opportunity where you can beat them to an achievement they've been working towards and then they'll have to settle for a lower amount of points for it.

Generally the best time to claim any achievement (or bear statue) is the exact turn before your opponent is about to get it. If there's no way your opponents can beat you to the achievement you've been working towards before your next turn, it may be worth doing something else with this turn and claiming the achievement next turn instead. But remember to always be efficient at filling up your park too.

Tips earth

2024-01-10T17:43:21Z

Fletcheese: Initial creation with general strategy

== Overview ==

Earth is an engine building resource management with min-max/optimization at its core. There are numerous factors to consider for every decision. This is overwhelming at first, but as you play more you start recognizing more and more factors and begin to understand how to weigh them against each other. Some decisions come down to card knowledge. E.g. where do I place this card now to account for a maximum number of future drawn cards that consider position? The most weight should be placed on factors that exist now, but the best players will eek out edges by considering potential future factors too.
 
• Note that this advice is largely geared toward 2-player games because this is the competitive format.

== Which action to pick? ==

=== Planting ===

The highest interaction point of Earth is on planting. Whoever completes their board first not only gets 7 bonus points (you should think of this as a 14-point swing in 2-player games because zero-sum), but also is setting the pace for the game. This principle rules in most if not all games where the end criteria is determined by some form of board completion - the player who is ahead on completion status is controlling the pace of the game and *much* more likely to win. If you have two things that you can Plant and a fairly high likelihood of being able to follow your opponent's Plant action (consider that you get to choose 1 of 4 which is fairly likely to yield a cheap option) then you should do it. At its core, there is a race happening in this game and the player who picks Plant more frequently is winning it.
 
This leads us into the next question: what should I plant and where? Early in the game, the answer is usually "whatever you have". But later in the game as you get more cards, the answer becomes more nuanced.

==== Engine ====

• Green cards are very good. Plant is the most picked action so anything extra you can do in response to Planting is guaranteed money in the bank.
 
• After Green, the best actions are those that let you do more Planting. Some consideration should be given to "what color does my opponent have a lot of and is thus more likely to pick?" If you Plant actions of that color, then you can get more "follow" bonuses. But as we've already said, they should be picking Plant as often as possible so this is less important than:
 
• "What do I want to do if I can't plant?" The answer is either get more cards or get more soil. Ideally both. So the best thing you can do is add card draw to your Red/Blue action OR add Soil gain to your Yellow action. Then when you can't Plant, use the action that lets you double-dip on Soil and card draw.
 
• Don't forget that Sprouts are just inefficient soil (3->2) so the Blue action actually yields *6* Soil, 1 MORE than Red at the cost of 2 Compost (assuming you have the prerequisite number of open Sprout places, but you can always convert them to Soil beforehand). Until the late game, you should be using your sprouts for soil whenever you need it to do more Planting. In the late game you have to weigh the points lost in Sprouts against the extra points gained from planting a "better" card.

==== Fauna ====

This is the second highest interaction element of Earth after Planting. The player who first achieves each goal is getting +4 points (8-point swing for 2-player). While less important than Plant-maxing, this is still a considerable difference. And you know about all Fauna from the start of the game so it should immediately begin impacting all of your decisions adding a little bit of weight to Plant each card that matches some Fauna conditions especially for those that match multiple.
 
Even if you lose the race to a Fauna, it's still 11 points which weighs pretty heavily. It can still be correct to give up or forgo Fauna, just depends on the options being weighed.

==== Ecosystem / Terrain ====

These are being lumped together because they're effectively the same thing. There is no race with the opponent so they amount to solo goals. Ecosystems are known from the start so you can immediately start factoring them into what you play whereas Terrain can be drawn at any point in the game. This is why card knowledge is important. You cannot *rely* on getting a specific Terrain, but if you've accounted for it with your board positioning, then you've set yourself up for additional beneficial scenarios if you get lucky. Success is when luck meets opportunity :)

==== Where? ====

Considerations for where to Plant each card are fairly limited, but this is a potential area for gaining an edge in close games:
 
• Stay open as long as reasonably possible. Once you have a row or column of length 4, your board is "locked". Until then you have the freedom to plant in more positions. Maintaining this freedom can net you better opportunities later in the game.
 
• Most important is Ecosystems and Terrain that have already been played or you have in hand and plan to play over the course of the game.
 
• After that is logical order of resolution. You want to draw cards before you have to Compost from your hand via some other action. Secondary to that are things like gaining Growth/Sprouts to later spend in your turn for costs, but you will almost always already have this so you can simply replace it later in the turn.
 
• Then the last consideration is what position-based Terrain cards could I draw into later in the game that I want to be able to play? I still don't know all the cards, but ones that come to mind are the Habitat-based "path" cards (draw a line of cards that share a habitat) and the plant-type directionals (in this row, in this column, orthogonally adjacent, etc). It is impossible to account for every Terrain, but accounting for as many as possible will help you win more games

=== Not Planting (anything else) ===

See the Engine section above. None of the actions are bad, but what to pick just depends on what you and the opponent have already played. Always look at your opponent's board - don't pick actions that help your opponent more than they help you. You're typically only even considering this if you can't pick Plant.

== End Game ==

As the end of the game approaches (one player has 3 empty spaces on the board), there are new important considerations.
 
• Double check who went first. If the second/last player completes their board, then the game ends after their turn. Otherwise everyone after that player gets another turn. Make sure you factor this into your plans for what you want to Plant before the game ends.
 
• Tally up your Terrain and Ecosystem goals. Many of these give points based on sets/pairs/trios. If you're close to one of these thresholds (e.g. odd number for a pair-based bonus), add some priority to getting that last item.
 
• There is a lot of nuance around picking Plant later in the game depending on who is winning the race and how many empty spaces each player has left. The ideal scenario is one in which you have 1 empty space and your opponent has at least 3 empty spaces. The key to manufacturing this game state is to Plant early and often which is why this is emphasized so heavily
 
• Example 1: you have 3 empty board spaces and your opponent has 4. If you pick Plant then the result is you have 1 and opponent has 3. This is good because if your opponent picks Plant, you get the 7-point bonus and the game will end. A similar scenario occurs even if it is your opponent's turn. They Plant down to 2 empty spaces as do you. You can pick your final Plant, get the 7 points, and the opponent only has 1 empty spot at which point the game ends if you're second or they can do one last "inefficient" Plant action for the last space.
 
• Example 2: you have 2 empty and your opponent has 3 and it's your turn. If you went second then picking Plant ends the game - great. But if you went first, then your opponent is effectively given a "free" Plant where you cannot follow. You plant to 0 empty, opponent is at 2, then they can Plant again while you can't. A notably exception to this is if you have some Terrain that lets you replace it with a Plant from your hand. Choosing not to plant is just as bad because you now have to pick an "inefficient" last Plant of 1 or forgo the 7-point bonus entirely.
 
• Example 3: you both have 3 empty board spaces. This is a standoff position. Neither player wants to Plant because the result is that the opponent will win the 7-point bonus (tie for completion on the same turn goes to turn-player). Whoever has the bigger engine is favored here. By that we mean some combination of Sprout/Growth room and the resulting points per action noting that Compost and some specific Terrain bonuses do not have limits (e.g. 1 point per card in hand).

=== Conclusion ===

Hope this is helpful to some people. I have still not played many Earth games, but it clearly has high strategic depth. You may or may not find that depth to be interesting as the highest levels of play emphasize deep knowledge of all the cards, but there's a lot of room for interesting decisions leading up to that level.

Tips spacebase

2023-10-23T20:18:03Z

Fletcheese: Added 2 bullets

== Dice Statistics ==
The lower sectors are more likely to be activated than higher sectors, since players can select either individual die values or their sum:
* Sectors 1-6 will trigger much more often than 7-12, but rewards for higher sectors are typically better.
*The probability distribution of outcomes is:
** 1 ''(11%)'', 2 ''(12%)'', 3 ''(13%)'', 4 ''(14%)'', 5 ''(15%)'', 6 ''(16%)'', 7 ''(6%)'', 8 ''(5%)'', 9 ''(4%)'', 10 ''(3%)'', 11 ''(2%)'', 12 ''(1%)''
*These values expressed as the likelihood of getting an outcome based rolling two dice is:
** 1 ''(33%)'', 2 ''(36%)'', 3 ''(39%)'', 4 ''(42%)'', 5 ''(44%)'', 6 ''(47%)'', 7 ''(17%)'', 8 ''(14%)'', 9 ''(11%)'', 10 ''(8%)'', 11 ''(6%)'', 12 ''(3%)''

== General Strategy ==
* Purchase cards from a variety of sectors, to maximize the chance of deployed cards triggering on other players' turns.
* Player Count impacts which rewards are most important: deployed (red) rewards trigger more often in higher-player-count games.
* Don't purchase Colony Cards too early, to avoid locking out sectors
* Use "arrow" rewards/abilities to mitigate the luck of die rolls and have more control over which sectors are triggered.
* Balance the type of rewards on your board - you can't win without VPs, but high income and credits are needed to purchase the best cards.
* Remember it is a race to 40 points, so if one person is getting ahead on VPs then prioritize getting VPs to catch-up (e.g. buy Colony cards)
* Focus less on the price of cards and more on their sector and effect. It's okay to overspend for a card that works better with your strategy
* A single point is worth 3 credits as clearly demonstrated by the colony cards. Early in the game prioritizing credits is sometimes okay to get better cards but more often than not, you should just choose points

Try new strategies!
* Bet heavily on a single sector. Purchase many cards in one sector and hope for good rolls. Clever use of "arrow" rewards can help maximize your gains.
* Race to get a deployed card in every sector. You'll be able to trigger rewards on every dice roll, and even have some options on what to choose!
* Try for the elusive "You Win" card. It may take incredible luck (or skill), but what a dramatic way to win! Who needs other sources of VPs if you can instantly win?

Tips challengers

2023-06-27T21:15:34Z

Fletcheese: More detailed strategies - less emphasis on luck

Challengers is a card drafting auto-battler game. Naturally the cards you are offered and the order in which your deck appears is based on luck, but there are still many important and often difficult decisions to be made which will impact how successful you are.

== General Strategy ==

The goal of the draft is to maximize your deck's power/size while minimizing the likelihood of "benching out" (7th bench card). This is an oversimplification but a good first principle to work from. With that in mind, the following is implied:

• Drafting duplicates is crucial. These will increase your deck size and power while not making you bench out. Ignoring synergy a pair of 2-power cards is generally as good as 1 4-power card. The 2-power cards are sometimes better on the attack but worse on defense. The 4-power is sometimes worse on attack but better on defense
 
• Synergy is key. Cards like Vendor, A.I., Stable Boy, Make-up Artist, Band, Blacksmith, etc can be extremely strong if the rest of your deck support them. Learning what all the cards do and what your "outs" are to improve your deck is crucial
 
• Winning the later rounds is way more important than the early rounds. It's okay to take losses with a bloated deck early to maximize your odds of getting lucky with a later draft. Winning only rounds 5, 6, and 7 will almost always get you into the final
 
• Know when to reroll. This is probably the most skill-testing part of the entire game. If your deck has a lot of one-ofs, you probably need to reroll when you're not offered any duplicates
 
• Know when to cut. Generally speaking, you want 6 or 7 unique cards. Until the last few rounds of the game, sticking at 7 or 8 can be okay to have more potential pair opportunities on the next draft. In the last round or two, you should hopefully have doubled up on enough of your deck that having more than 6 cards is too risky to be worth it. If your decks overall power is low, you may need to sit at 7 and hope you draw a single as the last card
 
• Relying on bench cleaners sometimes works but is very risky. If you roll your bench cleaners before any singletons, then their effect is wasted. Usually you're better off cutting the one-of Vacuum Cleaner or Butler. Only consider playing them in duplicates
 
• Check which set is removed at the beginning of the game. This can influence your early picks in so far as what to look for and what to avoid

== Sets ==
Very rough/general breakdown of each set which realistically is not all that useful - keeping in mind individual card effects will be much more helpful:

• City (Light Blue) - Cards in this set tend to depend on cards in other sets to boost them.
 
• Castle (Dark Blue) - Cards in this set tend to boost cards in other sets.
 
• Film Studio (Green) - Cards in this set tend to focus on the attack.
 
• Funfair (Yellow) - Cards in this set tend to focus on rearranging your deck.
 
• Haunted House (Orange) - Cards in this set tend to remove cards from your bench (either to your deck or to your exhaust pile).
 
• Outer Space (Red) - Cards in this set tend to replace themselves or other cards in your deck.
 
• Shipwreck (Purple) - Cards in this set tend to give defensive boosts.

There are cross-over cards in each set, but your early picks tend to reflect these themes.

Good luck!

Tips patchwork

2023-06-17T23:42:36Z

Fletcheese: Added piece evaluation section

For the rules of patchwork, see [[Gamehelppatchwork|GameHelpPatchwork]]

== General ==

* Patchwork seems like a simple game of placing Tetris-like pieces into a grid by paying for them with buttons.
* However, it's complex in that you have to balance the time vs. the cost to get a piece.
* Use up too much time you will have an unfinished quilt, costing you -2 points per empty space.
* Spend too much at the wrong time you could get button poor and be forced to jump when you don't want to.

=== Some key things to consider ===
'''Evaluating Pieces'''

* ''Not all pieces are created equal''.
* There are 5 metrics to evaluate a piece on which include: button cost, time cost, button income, number of squares, and ease of fit
* All of these are easily quantified except ease of fit, but this is a crucial metric because the most efficient pieces (minimum cost, maximum squares/income) are the ones that seem hardest to fit into your quilt
* Takeaway: pick the most efficient pieces early in the game while you have plenty of time to fit other pieces around them

==== Patches with buttons ====

* Getting patches with buttons early is '''critical'''.
* You get more buttons when you pass one of the 9 buttons spots on the board, so the early you get them the more buttons you will get over the course of the game.
* ''For example:'' if you get a two-button patch in your first turn it will pay off with 18 buttons!
** But getting it later will have diminishing returns.

==== Jumping ====

* Jumping over an opponent and losing time to get buttons is '''sometimes''' a good thing.
** Early in the game, it allows you to get more buttons (money) early and buy better pieces (i.e., pieces with more buttons on them) earlier in the game.
** For why this is good refer to '''[[#Patches_with_buttons|Patches with buttons]]'''.
* If you do jump over an opponent, try to do it between buttons spots on the board, jumping over an opponent between button spots so you can buy the patch with buttons is preferred.
** Jumping over button spot misses a chance to buy a piece and get the buttons from it.

==== Sides ====

* Don't be afraid to leave an opening on the sides of the board, you can likely get a patch to fill it later, and you will not likely fill all your board anyway.
** This helps you avoid placing a piece in a bad spot because you are trying to fill every space - bad placement will then get you into trouble later when the board is tighter.

==== Strategy ====

* Some prefer to start from the bottom up, or a corner up, as they find it easier to fill the board.
** Others work from the centre out.
* Figure out what works for you!

==== 7×7 bonus ====

* Getting the 7×7 bonus for 7 points is '''great''' - '''however''' - going for it at the cost of not filling your board or bad placement which will make it hard to fill your board later will likely result in a loss anyway.
** Remember, it's -2 points for empty spaces, so the 7 point bonus only pays for 3.5 empty spaces, so getting the bonus but ending up with 6 openings for -12 points is counterproductive.

Good luck and have fun, it's a great game live or virtually!

Tips nextstation

2023-04-24T21:32:53Z

Fletcheese: Detail

==General Strategy==

1. Try to maximize the chance that any given card being drawn is both playable '''and''' contributes to your score
 2. You will frequently find yourself in the situation where you have to "guess" which of the remaining cards is next to determine which station you should draw toward. But it's never truly a 50/50 decision - there are tie breakers to be taken into account. Which outcome has higher upside? Does one result include more red card(s) which are guaranteed to be drawn eventually vs blue cards which may or may not be?
 3. Aim to draw each route such that you have many stations in one district and then '''at most one''' station in any other district. Drawing 2 stations in 2 different districts means you have effectively thrown away a station losing you an opportunity for about 5 or 6 points. A good route where all blue cards were drawn should score at '''least''' 5x6
 4. In the event that you are forced into taking a bad station (this will happen) try to take the station that has the highest opportunity for future upside - usually an interchange with a later route. In some cases not drawing the station at all is the best option because it can get in the way
 5. Every route start point has 8 adjacent stations, 2 of each type. Keep this in mind while drawing earlier routes. You should avoid making both stations of any given type inaccessible from a start point
 6. Consider the trade-offs of drawing a "long" connection between stations. This will limit your future options, but may let you score more points now. It's usually obvious which color route is most effected by drawing one of the long connections. If you haven't drawn that route yet, you often should not use that connection

==Objectives==

At the start of the game analyze the objectives. These can have a significant impact on how you should prioritize drawing each route as missing an objective will usually mean you lose. Break down of each objective:

1. 6 River crossings - there isn't much to say on this one. Usually you should be crossing the river 6 times regardless of how you're drawing, but do keep it in mind and try to prioritize getting to the river a little more than normal
 2. 9 Central District Stations - again fairly simple. This one should not be very hard to achieve assuming you're pushing 2 of your routes through the center like you should be
 3. 8 Interchanges - this is a bit more challenging. Draw 2 of your routes with the central district as their majority which should get you 4-5 interchanges. Sending a route through one of your future route start points can be good but be careful that you're not ruining that route's regular scoring
 4. 13 Districts - this is the most difficult objective. Certain card orderings can make the objective impossible or at least not worth pursuing. Drawing into an outer corner district is inherently sketchy. We want to keep both segments of our route playable as long as possible. But if we draw into the corner, there are now no longer any good stations for that segment (results in a 2nd station in the inner corner district which is almost always 0 points). If you're playing super hard for this objective, you may almost always achieve it, but if you sacrifice more than 10 points from your regular scoring (~2 "missed" stations) then it wasn't worth it.
 5. 5 Tourist Sites - plays interestingly with normal scoring. Each tourist site except the central one has a natural route for scoring it. But that forces you into drawing at least 2 routes in its starting district which means you would forgo any central district majority which is bad because the central district majority routes have the highest scoring potential. So the best way to play this is to try to hit tourist sites in non-start districts on 2 of our routes which also draw their majority through the center

==Pencil Powers==

Each pencil power has a unique impact on your route. You should always aim to use it, but you also need to be careful not to waste it.

1. Joker - this lets you play a little more "loosey goosey". You can take bigger risks knowing there's a wild card to get you out of it. Until it's gone
 2. Draw a second station of same type - this is probably the hardest power to use effectively. I usually end up using it more liberally than any of the other powers because you can often find yourself in a position where doubling up any of the remaining stations doesn't actually score more points
 3. Railroad Switch - plays somewhat similarly to Joker. Makes it much easier to play into a dead end knowing you can start up another segment on demand
 4. 2x Station - the easiest card to play. Note how the math changes making drawing across additional districts more valuable

Game interface logic: Game.js

2023-04-22T22:17:09Z

Fletcheese: /* Connecting */ This method does NOT work with string id, must be element $(id)

{{Studio_Framework_Navigation}}

__TOC__

This is the main file for your game interface. Here you will define:

* Which actions on the page will generate calls to the server.
* What happens when you get a notification for a change from the server and how it will show in the browser.
* Setup user interface

== File structure ==

The details of how the file is structured are described below with comments in the code skeleton provided to you.

Here is the basic structure:

* '''constructor''': here you can define global variables for your whole interface.
* '''setup''': this method is called when the page is refreshed, and sets up the game interface.
* '''onEnteringState''': this method is called when entering a new game state. You can use it to customize the view for each game state.
* '''onLeavingState''': this method is called when leaving a game state.
* '''onUpdateActionButtons''': called when entering a new state, in order to add action buttons to the status bar.
* ''(utility methods)'': this is where you can define your utility methods.
* ''(player's actions)'': this is where you can write your handlers for player actions on the interface (example: click on an item).
* '''setupNotifications''': this method associates notifications with notification handlers. For each game notification, you can trigger a javascript method to handle it and update the game interface.
* ''(notification handlers)'': this is where you define the notifications handlers associated with notifications in '''setupNotifications''', above.

More details:

'''setup(gamedatas: object) '''
This method must set up the game user interface according to current game situation specified in parameters.
The method is called each time the game interface is displayed to a player, ie:

* when the game starts
* when a player opens a game in the browser later
* when a player refreshes the game page (F5)
* when player does a server side Undo

"gamedatas" argument contains all data retrieved by your "getAllDatas" PHP method and some more.

'''onEnteringState(stateName: string, args: { args: any } | null): void'''

This method is called each time we enter a new game state.
You can use this method to perform some user interface changes at this moment.
To access state arguments passed via calling php arg* method use args?.args.
Typically you would do something only for active player, using this.isCurrentPlayerActive() check.
It is also called (for the current game state only) when doing a browser refresh (after the setup method is called).

'''Warning''': for multipleactiveplayer states:
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.
If you are doing initialization of some structures which do not depend on the active player, you can just replace (this.isCurrentPlayerActive()) with (!this.isSpectator)
for the main switch in that method.

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

'''onLeavingState(stateName: string): void'''

This method is called each time we leave a game state.
You can use this method to perform some user interface changes at this point (i.e. cleanup).

'''onUpdateActionButtons(stateName: string, args: object | null): void'''

In this method you can manage "action buttons" that are displayed in the action status bar and highlight active UI elements.
To access state arguments passed via calling php arg* method use '''args''' parameter. Note: args can be null! For '''game''' states and when you don't supply state args function - it is null.
This method is called when the active or multiactive player changes. In a classic "activePlayer" state this method is called before the onEnteringState state.
In multipleactiveplayer state it is a mess. The sequencing of calls depends on whether you get into that state from transitions OR from reloading the whole game (i.e. F5).

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

== Dojo framework ==

BGA uses the [http://dojotoolkit.org/ Dojo Javascript framework].

The Dojo framework allows us to do complex things more easily. The BGA framework uses Dojo extensively.

To implement a game, you only need to use a few parts of the Dojo framework. All the Dojo methods you need are described on this page.

== Javascript minimization (after July 2020) ==

For performance reasons, when deploying a game the javascript code is minimized using '''terser''' (https://github.com/terser/terser). This minifier works with modern javascript syntax. From your project "Manage game" page, you can now test a minified version of your javascript on the studio (and revert to the original).

NB: it has been reported that there is an issue with this minifier and percentage values for opacity.

== Accessing Players Information ==

'''player_id: number'''
id of the player who is looking at the game. The player may not be part of the game (i.e. spectator)
if (notif.args.player_id == this.player_id) {
...
}

'''isSpectator: boolean'''
Flag set to true if the user at the table is a spectator (not a player).

Example:
<pre>
if (this.isSpectator) {
this.player_color = 'ffffff';
} else {
this.player_color = gamedatas.players[this.player_id].color;
}
</pre>

Note: If you want to hide an element from spectators, you should use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

You may consider making a function like this, to detect if the game is in a read-only state (i.e. non-interactive):
// Returns true for spectators, instant replay (during game), archive mode (after game end)
isReadOnly: function () {
return this.isSpectator || typeof g_replayFrom != 'undefined' || g_archive_mode;
}

'''gamedatas: object'''
Contains the initial set of data to init the game, created at game start or by game refresh (F5).
You can update it as needed to keep an up-to-date reference of the game on the client side if you need it, however most of the time this is unnecessary.

Note: In hotseat mode, the framework does not keep this.gamedatas of hotseat players and shares the same set as the main player to store data.

Note: be careful when you update this data structurally, many framework functions expect data to be certain way and they will break if they see something else.

Typical example of accessing player's info
<pre>
for (var player_id in this.gamedatas.players) {
var playerInfo = this.gamedatas.players [player_id];
var c = playerInfo.color;
var name = playerInfo.name;
// do something
}
</pre>

'''isCurrentPlayerActive(): boolean'''
Returns true if the player on whose browser the code is running is currently active (it's his turn to play). Note: see remarks above about usage of this function inside onEnteringState method.
if (this.isCurrentPlayerActive()) {

'''getActivePlayerId(): number'''
Return the ID of the active player, or null if we are not in an "activeplayer" type state.
if (this.player_id == this.getActivePlayerId()) ...

'''getActivePlayers(): number[]'''
Return an array with the IDs of players who are currently active (or an empty array if there are none).

== Accessing and manipulating the DOM ==

=== Element by Id ===

'''$(elementId: ElementOrId)'''

The $ function is used to get an HTML element using its "id" attribute.

Example: modify the content of a "span" element:

<pre>
In your HTML code:
1234

In your Javascript code:
$('a_value_in_the_game_interface').innerHTML = "9999";
</pre>

Note: It is safe to use if you don't know if variable is string (id of element) or element itself, i.e.
<pre>
foo: function(card) {
card = $(card); // now its node, no need to write if (typeof card === 'string') ...
// but its good idea to check for null here
...
}
</pre>

'''getElementById(elementId: string)'''

Note: $() is the standard method to access some HTML element with the BGA Framework. You can use '''getElementById''' but a longer to type and less handy as it does not do some checks.

=== Style ===

'''dojo.style(node: ElementOrId, styleName: string, styleValue: any): void'''

With dojo.style you can modify the CSS property of any HTML element in your interface.

Examples:

<pre>
// Make an element disappear
dojo.style( 'my_element', 'display', 'none' );

// Give an element a 2px border
dojo.style( 'my_element', 'borderWidth', '2px' );

// Change the background position of an element
// (very practical when you are using CSS sprites to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

Note: if you have to modify several CSS properties of an element, or if you have a complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).

You can also use object to set multiple values
<pre>
dojo.setStyle("thinger", {
"opacity": 0.5,
"border": "3px solid black",
"height": "300px"
});
</pre>

'''addStyleToClass(cssClassName: string, styleName: string, styleValue: any):void'''

Same as dojo.style(), but for all the nodes set with the specified cssClassName
Equivalent of

dojo.query(`.${aclass}`).style(styleName, styleValue)

<pre>
dojo.query("#baz > div").style({
opacity:0.75,
fontSize:"13pt"
});
</pre>

'''Vanila JS style'''
$('my_element').style.display='none'; // set
var display = $('my_element').style.display; // get
$('my_element').style.removeProperty('display'); // remove

=== Classes ===

'''dojo.addClass(node: ElementOrId, classes: string): void'''

'''dojo.removeClass(node: ElementOrId, classes: string): void'''

'''dojo.hasClass(node: ElementOrId, aclass: string): void'''

'''dojo.toggleClass(node: ElementOrId, aclass: string): void'''

In many situations, many small CSS property updates can be replaced by a CSS class change (i.e., you add a CSS class to your element instead of applying all modifications manually).

Advantages are:
* All your CSS stuff remains in your CSS file.
* You can add/remove a list of CSS modifications with a simple function and without error.
* You can test whether you applied the CSS to an element with the '''dojo.hasClass''' method.

Example from ''Reversi'':

<pre>
// We add "possibleMove" to an element
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );

// In our CSS file, the class is defined as:
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}

// So we've applied 4 CSS property changes in one line of code.

// ... and when we need to check if a square is a possible move on the client side:
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{ ... }

// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
</pre>

'''Vanila JS classList'''

This is the only exception where dojo versions are better
// add class
$(token_id).classList.addClass('possibleMove');
// remove class
$(token_id).classList.removeClass('possibleMove');
// add 2 classes
const myclasses = ['a','b'];
$(token_id).classList.addClass(...myclasses);
// add classes to query result
document.querySelectorAll(".hand .card").forEach((node)=>node.classList.addClass('possibleMove'));

=== Attributes ===

;dojo.attr

With dojo.attr you can access or change the value of an attribute or property of any HTML element in your interface.

Exemple:
<pre>
// Get the title of a node
var title = dojo.attr( id, 'title' );
// Change the height of a node
dojo.attr( 'img_growing_tree', 'height', 100 );
</pre>

'''Vanila JS attr'''

$(token).id=new_id; // set attr for "id"
var id = $(token).id; // get

=== Queries ===

'''dojo.query(cssSelector: string): Element[]'''

With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.

Example:
<pre>
// All elements with class "possibleMove":
var elements = dojo.query( '.possibleMove' );

// Count number of tokens (i.e., elements of class "token") on the board (i.e., the element with id "board"):
dojo.query( '#board .token' ).length;
</pre>

But what is really cool with dojo.query is that you can combine it with almost all methods above.

Examples:
<pre>
// Trigger a method when the mouse enter in any element with class "meeple":
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );

// Hide all meeples who are on the board
dojo.query( '#board .meeple' ).style( 'display', 'none' );
</pre>

'''Vanila JS query'''

var cards=document.querySelectorAll(".hand .card");// all cards in all hands
var cards=$('hand').querySelectorAll(".card");// all cards in specific hand
var card=document.querySelector(".hand .card");// first card or null if none (super handy)

=== Creating and Destroying elements ===

'''dojo.empty(node: ElementOrId)'''

Remove all children of the node element
dojo.empty('my_hand');

'''dojo.destroy(node: ElementOrId)'''

Remove the element
dojo.destroy('my_token');

dojo.query(".green", mynode).forEach(dojo.destroy); // this remove all subnode of class green from mynode

'''dojo.create(tag: string, attributes?: obj, parent?: ElementOrId): Element'''

Create element

dojo.create("div", { class: "yellow_arrow" }, parent); // this creates div with class yellow_array and places it in "parent"

'''this.format_block(name: string, args: object): string'''
This bga function that takes global var from template file and substitute variables, typical use would be

var player = gamedatas.players[player_id];
var div = this.format_block('jstpl_player_board', player ); // var jstpl_player_board = ... is defined in .tpl file
Note: result is trimmed

'''this.format_string(name: string, args: object): string'''
This bga function just substitute variables in a string, i.e.
<pre>
var div = this.format_string('<div color="${player_color}"></div>', {player_color: '#ff0000'} );
</pre>
Note: result is trimmed

Note: this can be replaced by using backquoted string now:
const player_color = '#ff0000';
const div = `<div color="${player_color}"></div>`;

'''this.format_string_recursive'''
This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.

TODO: find better place for these function docs

=== Moving elements ===

'''dojo.place(node: string | Element, refNode: ElementOrId, pos?: string | number): Element'''

dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.

node:

Can be a String or a DOM node. If it is a string starting with “<”, it is assumed to be an HTML fragment, which will be created. Otherwise it is assumed to be an id of a DOM node.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<div class='foo'></div>", "your_container_element_id" );
</pre>

pos:

Optional argument. Can be a number or one of the following strings: “before”, “after”, “replace”, “only”, “first”, or “last”. If omitted, “last” is assumed.

"replace": Replace the container element with my_node element

"first": Places the node as a child of the reference node. The node is placed as the first child.

"last" (default): Places the node as a child of the reference node. The node is placed as the last child.

"before": places the node right before the reference node.

"after": places the node right after the reference node.

"only": replaces all children of the reference node with the node.

positive integer: This parameter can be a positive integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

<pre>
// Replace all children of container with my_node
dojo.place( $('my_node'), "your_container_element_id", "only" );
</pre>

See also full doc on dojo.place: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''placeOnObject(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

places mobile_obj on target_obj, set the absolute positions and centers the mobile_obj on target_obj,
effect is immediate

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''placeOnObjectPos( mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number ): void'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates (in px). This way, the center of "mobile_obj" will be placed to the specified x,y position relatively to the center of "target_obj".

''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.attachToNewParent(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

With this method, you change the HTML parent of "mobile_obj" element without moving it.
"target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

What happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

'''CAREFUL''': this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).
If you need version that does not destroy the object but the same otherwise see [[BGA_Studio_Cookbook#Attach_to_new_parent_without_destroying_the_object]]

== Animations ==

===Dojo Animations===

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

===Sliding===

'''slideToObject(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''slideToObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number, duration?: number, delay?: number ): Animation'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels from the top:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''slideTemporaryObject( mobile_obj_html: string, parent: ElementOrId, from: ElementOrId, to: ElementOrId, duration?: number, delay?: number ): Animation'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();
</pre>

===Destroy===
'''slideToObjectAndDestroy: function(mobile_obj: string | Element, target_obj: string | Element, duration?: number, delay?: number): void'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments, but it starts the animation.

CAREFUL: Make sure nothing is creating the same object at the same time the animation is running, because this will cause some random disappearing effects

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):void'''

This function fade out the target node, then destroy it. Its starts the animation.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.
Make sure nothing is creating same object at the same time as animation is running, because you will be some random dissapearing effects

===Rotating elements===

This example combines "Dojo.Animation" method and a CSS property transform that allow you to rotate the element.
<pre>
// node is Element we rotating
var animation = new dojo.Animation({
curve: [fromDegree, toDegree],
onAnimate: (v) => {
node.style.transform = 'rotate(' + v + 'deg)';
}
});

animation.play();
</pre>

BGA has its own interface to rotate

'''rotateTo(node: string | Element, degree: number): void'''

It starts the animation, and stored the rotation degree in the class, so next time you rotate object - it is additive.
There is no animation hooks in this one, if you need to change any parameters use dojo animation above.

There is also '''rotateInstantTo''' with same signature which does not animate

===Animation Callbacks===

If you wish to run some code only after an animation has completed you can do this by linking a callback method to 'onEnd'.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, 500 );
dojo.connect(animation_id, 'onEnd', () => {
// do something here
});
animation_id.play();
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

== Players input ==

=== Connecting ===
'''dojo.connect(element: Element, event: string, context: object, method: eventHandler): any'''

'''dojo.connect(element: Element, event: string, hander: eventHandler): any'''

Used to associate a player event with one of your notification methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Same idea but base on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: if you need to disconnect the handler you have to store handler returned from this method, i.e.

<pre>
var handler = dojo.connect(...);
...
dojo.disconnect(handler);
</pre>

If you don't store the handler - you have to destroy the object to disconnect it

Typical function that implements the input handler will look like this

<pre>
onPet: function(event) {
var id = event.currentTarget.id;
console.log('onPet ' + id);
dojo.stopEvent(event);
if (this.gamedatas.gamestate.name == 'playerTurnPet') {
this.ajaxcallwrapper('playPet', {card: id});
} else {
this.showMoveUnauthorized();
}
}
</pre>

'''connect(element: ElementOrId, event: string, method: eventHandler): void'''

Used to associate a player event with one of your notification methods.

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.
This function is mainly for permanent objects - if you just want to connect the temp object you should probably not use this method but use dojo.connect which won't require any clean-up.

'''connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.
<pre>
this.connectClass('pet', 'onclick', 'onPet');
</pre>

'''disconnect(element: ElementOrId, event: string): void'''

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

;disconnectAll()

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

this.disconnectAll();

=== Actions ===
'''this.ajaxcall(url, parameters, obj_callback, callback, callback_anycase?, ajax_method?: string)'''

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features. It should be used only in reaction to a user action in the interface.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server.
** Note that "lock: true" must always be specified in this list of parameters in order the interface can be locked during the server call. Cannot use lock: false - to not lock it has to be undefined.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback (non-optional but rarely used): a function to trigger when the server returns result and everything went fine (not used, as all data handling is done via notifications).
* callback_anycase: (optional) a function to trigger when the server returns ok OR error. If no error this function is called with parameter value false. If an error occurred, the first parameter will be set to true, the second will contain the error message sent by the PHP back-end, and the third will contain an error code.
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

Note: to reduce the boilerplate code you can define your own wrapper, which will do checking, locking and allow to skip parameters, for example
<pre>
ajaxcallwrapper: function(action, args, handler) {
if (!args) {
args = {};
}
args.lock = true;

if (this.checkAction(action)) {
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args, this, (result) => { }, handler);
}
},
</pre>
This can be called like this which is a lot more compact
<pre>
this.ajaxcallwrapper('playDraw');
this.ajaxcallwrapper('playMove', {card: id})
</pre>

'''checkAction(action: string, nomessage?: boolean): boolean '''

Check if player can do the specified action by taking into account:
* if interface is locked it will return false and show message "An action is already in progress", unless nomessage set to true
* if player is not active it will return false and show message "This is not your turn", unless nomessage set to true
* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

Example:
<pre>
function onClickOnGameElement( evt ) {
if( this.checkAction( "my_action" ) ) {
// Do the action
}
}
</pre>

'''checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account

* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

function onChangeMyMind( evt ) {
if( this.checkPossibleActions( "my_action" ) ) {
// Do the action
}
}

'''checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors. Note: normally you only need to use this.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.checkLock() ) {
// Do the action
}
}

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

'''dojo.subscribe(notif_type: string, callback_obj: Object, handler: string|handler)'''
* notif_type - notification type/name send by php server
* callback_obj - usually this
* handler - if string method of callback_obj with name name is called, when notification is called, with notification object as parameter (see below)

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
setupNotifications: function() {
...
dojo.subscribe('playDisc', this, "notif_playDisc");
},
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function(notif) {
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access all notifications arguments with "notif.args".

Example:

PHP

<pre>
$this->notifyAllPlayers( "apples", clienttranslate('player takes ${count} apples'), [ "count" => 3 ] );
</pre>

JavaScript

<pre>
setupNotifications: function() {
dojo.subscribe( 'apples', this, 'notif_apples' );
},

notif_apples: function(notif) {
//You can access the "count" like this:
alert("count = " + notif.args.count);
}
</pre>

=== The notification Object received by client ===

When sending a notification on your PHP, the client side will receive an Object with the following attributes:

* type - type of the notification (as passed by php function)
* log - the log string passed from php notification
* args - This is the arguments that you passed on your notification method on php
* bIsTableMsg - is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)
* channelorig - information about table ID (formatted as : "/table/t[TABLE_NUMBER]")
* gamenameorig - name of the game
* move_id - ID of the move associated with the notification
* table_id - ID of the table (comes as string)
* time - UNIX GMT timestamp
* uid - unique identifier of the notification
* h - unknown

'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''

=== Ignoring notifications ===
Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring.

NOTE: You can think that it would be possible to send such notification to all players except active just by using notifyPlayer and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''
This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notif_type: type of the notification
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

Before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored, if it return true - the notification will be dispatched, i.e. logged or handled.

<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should '''preserve''' it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, there are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

You can also manually call this.notifqueue.setSynchronousDuration(0) once client operations are finished, but be careful that even fast replay still has a path to call it.

'''WARNING: combining synchronous and ignored notifications'''
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):

<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre>

then you CANNOT do

<pre>this.notifqueue.setSynchronous('myNotif');</pre>

as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.

The workaround is to set a "dummy" time:

<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre>

whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', clienttranslate('hello'), [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

Note: the following types are RESERVED by framework, do not use:

gameStateChange gameStateChangePrivateArg gameStateMultipleActiveUpdate newActivePlayer playerstatus yourturnack clockalert tableInfosChanged playerEliminated tableDecision archivewaitingdelay end_archivewaitingdelay replaywaitingdelay end_replaywaitingdelay replayinitialwaitingdelay end_replayinitialwaitingdelay aiPlayerWaitingDelay replay_has_ended updateSpectatorList wouldlikethink updateReflexionTime undoRestorePoint resetInterfaceWithAllDatas zombieModeFail zombieModeFailWarning aiError skipTurnOfPlayer zombieBack allPlayersAreZombie gameResultNeutralized playerConcedeGame showTutorial showCursor showCursorClick skipTurnOfPlayerWarning banFromTable resultsAvailable switchToTurnbased newPrivateState infomsg

== Tooltips ==
=== Adding static tooltips ===
'''addTooltip( nodeId:string, helpStringTranslated: string, actionStringTranslated:string, delay?:number):void'''

Add a simple text tooltip to the DOM node.

Specify 'helpStringTranslated' to display some information about "what is this game element?".
Specify 'actionStringTranslated' to display some information about "what happens when I click on this element?".

You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.

When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.

Parameter "delay" is optional. It is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique, see dynamic tooltips below.

'''addTooltipHtml( nodeId: string, html: string, delay?:number ):void'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''addTooltipToClass(cssClass: string, helpStringTranslated: string, actionStringTranslated: string, delay?:number ):void;'''

Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

'''addTooltipHtmlToClass(cssClass: string, html: string, delay?:number ):void)'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

=== Removing static tooltips ===

'''removeTooltip( nodeId: string ):void'''

Remove a tooltip from the DOM node with given id.

=== Advanced tooltips ===

'''force tooltip to open'''

If you want to force tooltip to open in reaction to some other action, i.e. click you can do this

this.tooltips[id].open(id)

where id is the id of the tooltip node where tooltip was installed.

'''dynamic tooltips'''

See [[BGA_Studio_Cookbook#Dynamic_tooltips]]

'''tooltips on mobile'''

Tooltips is very unreliable on mobile, it is recommended to implement some other method to obtaining same information,
such as simple click handler in dedicated "Help" mode or provide dedicated clickable areas such as corner of card.

== Warning messages ==

Sometimes, there is something important that is happening in the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfills one of the end of the game conditions, so this is the last turn.

'''showMessage(msg: string, type: string): void'''

showMessage shows a message in a big rectangular area on the top of the screen of the current player, and it dissapears after few seconds (also it will be in the log in some cases).

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", "only_to_log" or custom string. If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background and it will be added to log. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.
If set to custom string, it will be transparent, to use custom type define "head_xxx" in css, where xxx is the type. For example if you want yellow warning, use "warning" as type and add this to css:
.head_warning {
background-color: #e6c66e;
}

Important: the normal way to inform players about the progression of the game is the game log. The "showMessage" is intrusive and should not be used often.

<pre>
notif_messageinfo: function(notif) {
if (!g_archive_mode) {
var message = this.format_string_recursive(notif.log, notif.args);
this.showMessage(_('Announcement:') + " " + message, 'info');
}
},
</pre>

Show message could be used on the client side to prevent user wrong moves before it is send to server.
Example from 'battleship':
<pre>
onGrid: function(event) {
if (checkIfPlayerTriesToFireOnThemselves(event)) {
this.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

'''showMoveUnauthorized(): void'''

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.showMoveUnauthorized();
return;
}
...
},
</pre>

== Dialogs ==

=== Confirmation dialog ===

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player does not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

'''confirmationDialog(message:string, yesHandler:(param:any)=>void, noHandler?:(param:any)=>void, param?: any): void'''

* message - message will be shown to user, use _() to translate
* yesHandler - non-optional handler to be called on yes
* noHandler - optional handler to called on no
* param - if specified, it will be passed to both handlers
NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers

How to display a confirmation dialog:
<pre>
this.confirmationDialog(_("Are you sure you want to bake the pie?"), () => {
this.bakeThePie();
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>

=== Multiple choice dialog ===

You can use this dialog to give user a choice with small amount of options

'''multipleChoiceDialog(message: string, choices: string[], callback: (choice: number)=>void): void'''
* message - message will be shown to user, use _() to translate
* choices - array of choices
* callback - non-optional handler to be called on choice made, the choice parameter is the INDEX of the choice from the array of choices

NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers
NOTE: there is no cancel handler, so make sure you gave user a choice to get out of it

Example:
<pre>
const keys = ["0", "1", "5", "10"];
this.multipleChoiceDialog(_("How many bugs to fix?"), keys, (choice) => {
if (choice==0) return; // cancel operation, do not call server action
var bugchoice = keys[choice]; // choice will be 0,1,2,3 here
this.ajaxcallwrapper("fixBugs", { number: bugchoice });
});
return; // must return here
</pre>

=== Generic Dialogs ===

As a general rule, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect($('my_ok_button'), 'onclick', this, (event) => {
event.preventDefault();
this.myDlg.destroy();
});

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback((event) => { ... });

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
));
</pre>

The "table" argument is a 2 dimensional PHP array that describes the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = [
[ "one", "two", "three" ], // This is my first line
[ "four", "five", "six" ], // This is my second line
[ "seven", "height", "nine" ] // This is my third line
];
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = [
[ "one", "two", [ "str" => clienttranslate("a string with an ${argument}"), "args" => [ 'argument' => 'argument_value' ] ] ],
[ "four", "five", "six" ],
[ "seven", "height", "nine" ]
];
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = [ '' ];
foreach( $players as $player_id => $player ) {
$cell = [ 'str' => '${player_name}',
'args' => [ 'player_name' => $player['player_name'] ],
'type' => 'header'
];
$firstRow[] = $cell;
}
$table[] = $firstRow;
...
</pre>

You can also use three extra attributes in the parameter array for the notification:
* '''header''': the content for this parameter displays before the table (also, the html will be parsed and player names will be colored according to the current game colors).
* '''footer''': the content for this parameter displays after the table (no parsing for coloring the player names)
* '''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

<pre>
$this->notifyAllPlayers( "tableWindow", '', [
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => ['str' => clienttranslate('Table header with parameter ${number}'),
'args' => [ 'number' => 3 ],
],
"footer" => '<div class="myfoot"></div>',
"closing" => clienttranslate( "Closing button label" )
] );
</pre>

Note: currently id is not used - so you cannot access resulting div by id on js side
Note: any traslatable stirng have to be wrapped by clienttranslate() on top level OR it has to be recursive template.

DO NOT DO THIS:
<pre>
"footer" => '<div>'.clienttranslate( "The end" ).'</div>', // this will not work for translations!!!
</pre>

=== Scoring animated display ===

Sometimes, you may want to display a score value over an element to make the scoring easier to follow for the players (Terra Mystica final scoring for example).
You can do it with:

'''displayScoring(anchor_id:string, color:string, score:number|string, duration?:number, offset_x?:number, offset_y?: number): void'''

'''anchor_id''': ID of the html element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+' or '-'

'''duration''': animation duration in milliseconds (optional, default is 1000)

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation.
Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.
<pre>
setupNotifications: function() {
dojo.subscribe( 'displayScoring', this, "notif_displayScoring" );
...
}
...

notif_displayScoring: function(notif) {
const duration = notif.args.duration?notif.args.duration:1000;
this.notifqueue.setSynchronous('displayScoring', duration );
this.displayScoring( notif.args.target, notif.args.color, notif.args.score, duration);
},
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with showBubble:

'''showBubble(anchor_id: string, text: string, delay?: number, duration?: number, custom_class?: string): void'''

* anchor_id - where to attach the bubble
* text - what to put in bubble, can be html
* delay - delay in milliseconds (optional, default 0)
* duration - duration of animation in milliseconds (optional, default 3000)
* custom_class - extra class to add to bubble (optional), if you need to override the default bubble style

<pre>
this.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.format_string_recursive(notif.args.text, notif.args.args);
this.showBubble(notif.args.target, html, notif.args.delay ?? 0, notif.args.duration ?? 1000);
},
</pre>

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Translations ==

See [[Translations]]

== Players panels ==

=== Update players score ===

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the game setup() function. However this score must be updated as the game progresses using notifications.

Note: this.scoreCtrl[player_id] is object of class [[Counter]], you can use other counter API.

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

Set a player score to a specific value with animation:

<pre>
this.scoreCtrl[ player_id ].toValue( new_score );
</pre>

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div>0\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Player's panel disabling/enabling ===

'''disablePlayerPanel(player_id: number):void'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''enablePlayerPanel(player_id:number):void'''

Enable a player panel that has been disabled before.

'''enableAllPlayerPanels():void'''

Enable all player panels that has been disabled before.

=== Player order ===

'''updatePlayerOrdering():void'''

This function makes sure that player order in player's panel matches this.gamedatas.playerorder and its normally called by framework.
You can call it yoursel if you change this.gamedatas.playerorder from notification.
Also you can override this function to change defaults OR insert a non-player panel [[BGA_Studio_Cookbook#Inserting_non-player_panel]].

=== Counters ===
Note: there is bga component called "ebg/counter" this API is not using it, these methods
below declared right in core game. If you need animation for counters use ebg/counter

To use this API just create a counter dom element like this (class does not really matter)
<pre>
<div class="counter" id="bread"></div>
<div class="counter" id="coin"></div>
</pre>
The "bread" will the counter name.

The php code should send all "counters" data from getAllDatas() method like this

game.php
<pre>
protected function getAllDatas() {
// (the key must match counter_name)
$result['counters']=[
'bread' => [
'counter_name' => 'bread',
'counter_value' => 3
],
'coin' => [
'counter_name' => 'coin',
'counter_value' => 5
]
];
return $result;
}
</pre>

'''setCounter(counter_name:stirng, new_value: string | number): void

updates the global this.gamedatas.counters and value of node $(counter_name)
<pre>
notif_counter: function(notif) {
this.setCounter(notif.args.counter_name, notif.args.counter_value);
},
</pre>

'''incCounter(counter_name:string, delta: number): void
<pre>
notif_counter : function(notif) {
this.incCounter(notif.args.counter_name, notif.args.inc);
},
</pre>

'''updateCounters(counters: object): void'''

Useful for updating game counters in the player panel (such as resources).
'counters' arg is map of counters (the key must match counter_name)
{
'bread': {
'counter_name' : 'bread',
'counter_value' => 3
},
'coin': {
'counter_name' : 'coin',
'counter_value' => 5
}
}
All counters MUST be referenced in this.gamedatas.counters (means they should be send from php) and will be updated.
DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

Usually you call this from notification

<pre>
notif_counter : function(notif) {
this.updateCounters(notif.args.counters);
},
</pre>

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

== BGA Buttons ==

=== Basic Button ===
'''addActionButton( id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?:string): void'''

You can use this method to add an action button in the main action status bar (or other places).

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function). Note: this can also be any html, such as "<div class='brick'></div>", see example below on how to make image action buttons.
* method: the name of your method that must be triggered when the player clicks on this button (can be name of the method on game class or handler).
* destination (optional): id of parent on where to add button, ONLY use in rare cases if location is not action bar. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please DO NOT abuse blinking button. If you need button to blink after some time passed add class 'blinking' to the button later.
* color: could be '''blue''' (default), '''red''','''gray''' or '''none'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this:

<pre>
onUpdateActionButtons: function( stateName, args ) {
if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
this.addActionButton( 'pass_button', _('Pass'), ()=>this.ajaxcallwrapper('pass') );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'button_confirm', _('Confirm?'), 'onConfirm', null, true, 'red');
</pre>

If you want to call the handled with arguments, you can use arrow functions, like this:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), () => this.onConfirm(this.selectedCardId), null, false, 'red');
</pre>

=== Image Button ===

You can use the same method, but add extra class to a button to disable the padding and style it, i.e.
<pre>
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray');
dojo.addClass('button_brick','bgaimagebutton');
</pre>

where

<pre>
.bgaimagebutton {
padding: 0px 12px;
min-height: 28px;
border: none;
}
</pre>

If you use this a lot, you can define a helper function, i.e.
<pre>
/**
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player
* need to make a choice of resources or tokens.
*/
addImageActionButton: function(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.addActionButton(id, div, handler, null, false, bcolor);
// remove border, for images it better without
dojo.style(id, "border", "none");
// but add shadow style (box-shadow, see css)
dojo.addClass(id, "shadow bgaimagebutton");
// you can also add additional styles, such as background
if (tooltip) {
dojo.attr(id, "title", tooltip);
}
return $(id);
},
</pre>

=== Disabling Button ===

You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>
this.addActionButton('play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton');
if (condition) {
dojo.addClass('play_button_id', 'disabled');
}
</pre>

=== Custom Buttons ===

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue">My blue button</a>

<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big">My big red button</a>
</pre>

'''Note''': To see it in action, check out ''Coloretto''.

=== Button outside of action bar ===

Use addActionButton() method with destination argument set
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', 'player_board', true, 'red');
</pre>

in example above the button will be place on object with id 'player_board'

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''dontPreloadImage(image_file_name: string)'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}

this.ensureSpecificGameImageLoading( to_preload );

</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

'''ensureSpecificGameImageLoading(list: string[])'''

This is oppostive of dontPreloadImage - its ensure specific images is loaded. Note: only makes sense if preload list is empty, otherwise everything is loaded anyway

'''load specific images'''
All images that will be preloaded stored in g_img_preload. If you want to override it directly - there is no API, but you can do this in GAME constructor

g_img_preload = ['tokens.png', 'trains.png', 'loc_plan.png', 'eng.png', 'eng-back.png'];

You can also set it to empty array and call ensureSpecificGameImageLoading() on specific images

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file with the names <code><gamename>_<yoursoundname>[.ogg][.mp3]</code>.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>'); // do not add 'this.' - its a global function
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

== Title bar and states ==

=== Client states ===

Client states is a way to simulate the state transition but without actually going
to server. It is usefull when you need to ask user multiple questions before you
send things to server

'''setClientState(newState: string, args: object)'''

Example:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});

For more information see [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Client_States]]

'''restoreServerGameState()'''
If you are in client state it will restore the current server state (cheap undo)

'''this.on_client_state'''
Boolean indicating that we are in client state

=== Title bar ===
If you simply want to show something in title bar you can do it directly
$('pagemaintitletext').innerHTML = text;

This however will not work with parameters and will not draw You in color,
if you want to do proper args rendering use method below

;'''removeActionButtons()'''
Removes all buttons from title bar

;'''updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state arguments. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before calling this function it allows to update the turn description without changing state. This will handle arguments substitutions properly.

Note: this functional also will calls this.onUpdateActionButtons, if you want different buttons then state defaults, use method in example to replace them, if it becomes too clumsy use client states (see above)

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, function( result ) {} );
} ) );
</pre>

In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => {
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, (result) => {} );
} );
</pre>

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; g_replayFrom
: Global contains reply number in live game, it is set to undefined (i.e. not set) when it is not a reply mode, so consequentially the good check is '''typeof g_replayFrom != 'undefined'''' which returns true if the game is in replay mode during the game (the game is ongoing but the user clicked "reply from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode after the game (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like this.slideToObject() automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

; g_tutorialwritten
: Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.
{
author: "91577332",
id: "576",
mode: "view"
status: "alpha"
version_override: null
viewer_id: "84554161"
}

'''getBgaEnvironment(): string'''
: Returns "studio" for studio and "prod" for production environment (i.e. where games current runs). Only useful for debbugging hooks.
Note: alpha server is also "prod"

[[Category:Studio]]

Tips photosynthesis

2023-04-10T14:48:30Z

Fletcheese: Overhaul with more detailed strategy

=== General Strategy ===
The key build pattern is to separate each of your trees by an "L" shape/pseudo-knight's move (one space away in 2 adjacent directions) such that they will never block each others light. Naturally everyone will be trying to do this which inevitably leads to contested tree spaces.

Always think about what your plan is on the next turn. How much sun will you get? If you're playing with heavy shadow, which of your trees will you be able to grow? To accurately answer both of these questions you need to consider the turn order and make educated guesses about where your opponent(s) will grow. This is something you build an intuition for over time, but generally imagine you were them. Where would you want to grow? Check how much sun they have and what trees they have in stock to determine what they're capable of. This has a major impact on where you want to grow so that you are not blocked and/or you can block them.

It's worth emphasizing how important the turn order is as well. If you're going first in a round, you get first pick of spaces to plant seeds and grow your trees without being shadowed by opponents' growth and the opportunity to cast shadows on where they want to grow (heavy shadow). But going last can be good too. Imagine you have 2 different trees that you could grow. Either could be shadowed or in the sun on the next turn depending on which trees your opponents choose to grow. If you go last, you now have full info to grow the correct tree to gain sun.<blockquote>Note: most of this advice is written with 3-player, 3-round heavy shadow games in mind as that's currently (April 2023) the competitive format. In 2-player games the board is much less contested and players are more free to expand. Without heavy shadow there's generally much less thinking required.</blockquote>

=== Early Game ===
On your first turn, upgrade a small tree to a medium tree. This leads to additional sun income but more importantly lets you plant seeds 2 spaces away (L shape). It is often better to stake your claim over a spot by planting a seed than it is to upgrade your tree for more sun. Your additional trees in prime locations will lead to more sun in the long-term. Don't get greedy with maxing early sun; take the prime real estate while it's available.

It may seem like going for the center in 3+ player games is crucial, but there are often situations where you can never grow your seed (assuming heavy shadow) as it's easy to be surrounded on all sides.

=== Mid Game ===
Your goal should be to get all your level 2 and 3 trees on the board. Until you have done this you should ''never'' be scoring your trees. This is a waste of sun both in that you could have spent it on growing your engine ''and'' you've thrown away the 3 income that tree produces. Once you have spent all your level 3 trees and there's nowhere left to build 2's then you have no choice but to start collecting. Even then you should be checking your sun limit of 20. If the next turn's sunlight does not put you over 20, ''do not collect''. In some cases even if it puts you 1 or 2 over, waiting to collect may be better. Think carefully before planting any seeds toward the end of round 2. If they do not (a) net you 5 sun (the cost to plant a seed and level 1 tree) or (b) have enough time and sun to be grown to level 3 and collected, then you should probably not build it. In very rare cases planting a seed just to block an opponent's potential tree ''may'' be beneficial but probably not.

=== Late Game ===
The last round of the game is all about carefully growing and collecting your remaining trees. Leave up the trees that block your opponent's sun and collect the trees that block your own sun ideally on the turn right before this would occur. In heavy shadow you also need to make sure you can both grow ''and collect'' your trees since both actions are potentially blocked by opponent's taller trees. The key threshold each turn is 12 sun. This is how much you need to collect a tree, re-buy that tree, and plant it (4+5+3). Aim to do this as many turns as possible in the final round and you should at least be a contender for victory.

Tips livingforest

2023-04-07T21:34:57Z

Fletcheese:

WIP

Unlike creature cards, you may only buy one tree per action. You can get two trees in a turn by landing on the 'buy a tree' action on the spiral. With careful planning, you can chain together 4 actions in a turn.

Everyone starts with 0 Gregarious (White) and 5 Solitary (Black) Guardian Animals.
Count the number of symbols in your draw deck and discard pile to know what you will be drawing.
For example, drawing 3 solitary symbols in your first 3 cards means the rest of your draw pile only contains 2 solitary symbols (for your next turn). This cheatsheet created by a BGG user is incredibly helpful for tracking your remaining cards and what they do:

https://boardgamegeek.com/filepage/233342/starting-deck-symbols

You should very rarely be drawing after hitting 2 Solitary animals unless you are very far behind or do not have a viable turn without more draws. If you are starting your turn with a low deck, it's better to wait Fragments (discards) until after you reshuffle - though notably this is only really possible with 2 or less Solitaries remaining barring a Gregarious.

Pay attention to the turn order (first player token).
Attracting Guardian Animal allows the first player of the next turn to extinguish the Fire.

Remember that you may buy identical Protective Trees, especially if you are not aiming for Tree victory.
This can be important for denying your opponents or stacking Sacred Flowers.

Don't underestimate the value of high movement. Stealing other players' tokens is a big point swing and it lets you cheat 2 of the same action without getting the big tree. At the same time, consider holding your space if it's very valuable to an opponent so that they can't land on it. This often applies to tree planting spaces.

Tips gizmos

2023-02-02T15:14:31Z

Fletcheese: Added detail

At its core Gizmos is a resource management engine building game thus the goal is to maximize your obtainment and value of each resource - chiefly Energy (and indirectly engine power) in the early game and then points in the late game. So naturally you should be focusing on the Gizmos that help you get more Energy and then more points.

== Early Game ==

You start limited to taking one action per turn (technically two with the starting file trigger). Your goal is to gain extra actions as quickly as possible. Buying upgrades is generally a very poor idea at this point. Buying a converter can be good, but for the most part you should be looking for Build into Pick triggers > Pick into Draw triggers > File into Pick triggers. Once you have one or more of these you should look for other Gizmos that align with the color. If you already have a Build Red into Pick Gizmo, buying a Build Red into VP Gizmo is fantastic. If you already have a Pick Blue into Draw trigger, buying a Blue Converter is a great idea. That being said, dipping into other colors is not a bad idea if that's the only option available to you. It's good to be flexible so that you're not only looking for a single color of Gizmo/Energy.

Your first action should almost always be filing a Gizmo. If there are no Build or Pick Triggers in row I or II, then research Level I to look for one.

=== The File Strategy ===

It's worth mentioning that some people believe there to be two strategies in Gizmos: one focused on building a lot and another focused on filing a lot. A well played build strategy will beat a file focused strategy more than 90% of the time because building a lot of Gizmos ends the game so much faster than filing. Every file action you take is one less build that you could have taken. The only chance the file strategy has is to build 4 Level III Gizmos but that rarely comes together. Putting your opponents on a clock is very important.

== Mid Game / General Strategy ==

If you have a good build/pick engine going, the value of buying Upgrades, Build into VP, and Converters goes up.

The most skill-testing part of Gizmos is determining when you should take a risk by Researching versus accepting a potentially suboptimal Gizmo from the row. This is something you simply have to build an intuition for over time, but it's worth mentioning a general principle present in all games that involve mitigating randomness: how risky you are playing should be inversely proportional to how much you are winning. Are you winning? Don't take unnecessary risks - just keep winning. Are you losing? Take some big risks to get back in the game - you'll just lose if you don't. Obviously you're usually somewhere in-between but the principle is an important one.

Keep in mind that Level 3 multi-color Gizmos trigger ALL of your Build cards. Building random VP Gizmos even if they do not align with your usual build colors can be good for this reason. But also remember that each game includes a random 16 Level III cards out of the total pool of 36. So it is entirely possible, albeit unlikely, that none of the multi-color Gizmos made it into the Game. There's no way to know until you've researched the whole deck.

== Late Game ==

Reevaluate where you are at point-wise relative to your opponents. Do you need to research Level III hoping to find a big finisher? Or can you just build that face up Level II and coast to a victory? Most of the time the player that builds the 16th Gizmo is also the winner. Double check who first player is so you know who will get another turn and who does not. Try to be the player that sets the pace of the game.

Tips gizmos

2023-01-20T01:47:57Z

Fletcheese: Initial creation

Build an engine that lets you repeatedly buy Gizmos while getting multiple new energies on each purchase.

TODO: elaborate

Tips raceforthegalaxy

2022-10-06T18:28:19Z

Fletcheese: /* == */

Base Game Only, 2 Player only variant.
Race for the Galaxy is a resource management game. The game is won through Victory Points (VP). The 2 possible ways to get VP are:
1. Playing developments & worlds.
2. Consuming goods to gain the additional VP chips.

So the following strategies are based around one or both of these methods.

== Gameflow ==

Broadly speaking, most common strategies go though 3 different phases.

=== 0. Starting Cards: ===
Some starting cards are strictly stronger than others, but you always want to consider synergy with your hand. If you have a military windfall world in hand, keep the starting card with military. Improved Explore, discounts, and card draw are ideal. Barring that a windfall world into $ consume is a very effective start to open up options. If you have neither, starting with a +1,+6 Explore is often the best first turn to find some gas for your engine.

=== 1. Start of the game: ===
Money (cards in hand) and resource generation (improved Explore/discounts/card draw) is more important than VP at this stage.
Gain cards in hand by trading goods, normally from cheap windfall worlds, or exploring.
You may also see some small trading improvement cards which aid this strategy like 'Export Duties' or 'Spice World'

=== 2. Middle game: ===
Develop a card drawing and/or goods producing engine by playing card cost saving and gaining cards.
Examples include 'Drop Ships', 'Replicant Robots', 'Diverse Economy', 'Consumer Markets'.
Not to be overlooked are lots of cards which aid free stuff in the produce phase.

=== 3. End game: ===
The game ends after a player reaches 12 developments & worlds or 24 VP chips (in 2-player games, the pool of VP chips is 12 per player) have been gained. These two ways of ending the game also broadly categorize the strategies for winning the game.
You either aim to out develop/settle your opponent with superior card drawing/discount engine, or aim to build a produce and consumeX2 engine that nets roughly 6 more VP chips per turn than your opponent. Expansion will struggle to keep up with 6 points per turn, but each strategy can diversify into the other to take advantage of the opponent's phases (see Drafting / Leeching).

Recognize the turn the game will likely end, and build 6? point developments that gain lots of points in the final count. Build other high scoring worlds like alien worlds and military worlds.
Whatever you decide it should be to maximize your potential of hand and cards on the table, and looking to see how your position best plays against your opponents to secure victory.
Occasionally you may tell that the only way to victory could be to +5/0 explore to dig for that one final 6 point dev card that will earn you 14 points. Better to go down fighting than to simply concede.

== General Strategy ==

=== Drafting / Leeching / Playing the opponent: ===
Whatever you want to call it, the strategy of your opponent should be considered at all times. This is not just a multiplayer solitaire game.
So at the 'choose actions' initial part of the round, consider what benefits you the most, but also consider what benefits your opponent the least.
For example, if your opponent has very few cards in hand, their develop and settle options may be limited - especially if they have no develop/settle engine powers or military.
Alternatively, if their tableau has no produce powers, you might safely produce without gifting your opponent free goods and VP. It's even better if you have developments/worlds with production powers in hand, which guarantees that if they settle a production development/world, you get to develop/settle one too and remain ahead. Conversely anticipate when your opponent will recognize this about your hand and choose Explore to hopefully get you playable options.

Stay flexible. Take and keep cheap, easy to play filler cards to leech develops and settles.
Occasionally you get the 'zugzwang' feeling, where both players would normally choose produce or settle (or any other action type) but neither do because insufficient advantage would be gained from calling it. An example of this would be two players with equal produce/consume engines - neither wishes to call produce when they could use another phase to try to outflank the opponent, so both players pivot to expansion until one player finds advantage in producing again.

So the likelihood and the beauty of the game is that there is no one strategy to beat all others. You must be willing to be flexible at all times to maximize your position's dominance over your opponent's.

=== Pacing ===
Depending on the strategy both you and your opponent are playing, one of you is likely to benefit more from extending the game. Correctly identifying which player that is can be crucial. If you have some powerful 6? cards in hand, you may want to take less Develop/Settle actions as this expedites the end game. If you are off to an earlier start (better discounts / draw engine) you may want to take as many Develop/Settle actions as you possibly can to give your opponent less time to find their engine. If you can correctly anticipate your opponents action, then you can double up on the other which further speeds up the game.

=== Some small extra tips: ===
Yes, some games may only last 6 or 7 rounds and you've just been beaten by a very rapid cheap blue or brown 2x consume and produce tactic.
Leaving 0 or few cards in the hand after a round can leave you exposed. If you do this then you need to have a plan, like a alien yellow windfall world ready to be traded or something.
It's a race; always question your position and the end of the game, try to finish on a high, 6 point development cards are often played in the final round to steal the win.
A non military strategy can still deploy a 7 point rebel world with the help of the 'Contact Specialist'.
Don't blame the card draw, 95% of the time a credible alternative is available. It sucks to lose, play better next time!

Tips wingspan

2022-10-06T16:47:36Z

Fletcheese: More formatting

== Introduction ==

At its core Wingspan is an engine building resource management game. Your most finite resources is actions as you are limited to 26 (8+7+6+5) of these each game. So generally speaking you want to get the most out of every action. Play that bird before you take an action in its row so that you get an extra resource. There are of course exceptions to this e.g. if you need to move up in the rankings for an end of round goal.

== Early Game ==

When the game starts take the time to analyze each of these goals as they will heavily shape what to go for in this game. Lots of egg goals? Investing more into the grasslands may be a good idea. Lots of bird goals? Investing more into the Forest may be better. These are both oversimplifications as generally speaking you will build birds in every habitat and take every action over the course of most games. There are many other important considerations:

 
• Many nest-specific goals means the wild nest birds are stronger 
• Consider which nest goals exist and lean more on keeping and playing birds with that nest 
• Varying location based goals (eggs or birds in one of the 3 habitats) means the flighty birds (when on the right change habitat) are stronger 
• With all of the above in mind, specific pink birds become stronger too as opponents are forced into taking these actions or forgo end of round goals 
• Weight the later goals more heavily since these are worth more points - there's nothing wrong with skipping the first goal or two if it means positioning yourself to win the last one or two

 
You should think of the bonus cards as additional private end of game goals. Consider whether one of your bonus cards aligns with later end of round goals as that increases its value. Then move to your birds. Cross reference the end of round goals and above info with your hand and the available birds. Ideally you want to plan out your first few turns. Some general principles:

 
• Brown and pink action birds are ideal in the early game when there is more time to trigger their ability. More specifically you want powers that generate additional resources - cards > food > eggs. With that... 
•• Cards: this is the most important resource. Having a good card draw/cycle engine lets you find the birds you actually want to play often while scoring tuck points 
•• Food: you need food to play your cards, but you don't know what food you need until you find good cards and you can discard cards for food. Over the course of a game you should be drawing (and pitching) a lot more cards than food. Caching food is basically always worse than gaining it until the last turn or two depending on what birds and how much food you have 
•• Eggs: eggs are inherently less valuable than the other resources until the end of the game when eggs score points whereas cards and food do not. I say inherently because at every step you get 1 more egg than the other resources. So early in the game, you almost always want to spend an egg to draw (if you can) whereas later you need to think about it a bit more 
• The best starting birds either draw you food or cards. If you get both, your early game should run very smoothly 
•• You should obviously consider the cost of each bird when making this decision. That 3-cost food producer might be good early, but consider how that will impact your ability to play other birds. 
• Note if you're going first as you are guaranteed your pick of the shown birds which may be better to start with than any in your hand - there's nothing wrong with drawing a powerful bird on your first turn 
• Generally you should be keeping 1-3 birds. Keeping 5 should literally never be done and keeping 4 only makes sense if your hand is insane and/or you have a 1-cost forest bird going into 2 food production 
• Be wary of any actions that benefit opponents equally to you. These are probably bad in almost all cases

== Mid-Game ==

You should have a small resource engine hopefully consisting of birds that play toward at least one goal. Here are some principles focused more on the midgame:

 
• Routinely check your opponents boards and consider which remaining goals you have a realistic chance at winning. Compare how hard you have to invest into the goal, how likely you are to win it, and what you could be doing instead which might yield a greater long-term return e.g. maybe a later goal if players are less invested into it 
•• You should check their resource count and engine power as this factors in to how much they can develop into goals. If you're not that far behind then you may see that their resources cannot (or are very unlikely) to outpace you 
• Also check for pink birds. In some cases you should actually skip an action (e.g. predator) to prevent an opponent from gaining a more valuable resource (food is generally worth more than one point). But this is just a consideration - you can't skip playing birds in a habitat altogether but maybe you can wait to do it on the same turn as another opponent 
• It is good to play bonus card birds in the mid game. This will give you time to play toward the goal while having less impact on your early engine 
• If you have a good card draw engine, prioritize and collect additional play birds. Planning around big bird chains in the last round can often turn the tide of a game

== End Game ==

As the 3rd round comes to an end and the final round approaches you should be able to plan out the rest of your turns. Make a final decision on which goals you can reasonably commit to and play accordingly. It's okay to not always get the highest tier goal. Maybe playing out your non-goal birds in hand yields more points. Keep in mind that every round you spend gathering food to play your birds is a lost opportunity for other ways to gain points so maybe you should be stocking your remaining birds with eggs instead. You should be able to calculate which route has the highest expected score. Good luck!

Tips wingspan

2022-10-06T02:47:03Z

Fletcheese: Formatting

== Introduction ==

At its core Wingspan is an engine building resource management game. Your most finite resources is actions as you are limited to 26 (8+7+6+5) of these each game. So generally speaking you want to get the most out of every action. Play that bird before you take an action in its row so that you get an extra resource. There are of course exceptions to this e.g. if you need to move up in the rankings for an end of round goal.

== Early Game ==

When the game starts take the time to analyze each of these goals as they will heavily shape what to go for in this game. Lots of egg goals? Investing more into the grasslands may be a good idea. Lots of bird goals? Investing more into the Forest may be better. These are both oversimplifications as generally speaking you will build birds in every habitat and take every action over the course of most games. There are many other important considerations:

* Many nest-specific goals means the wild nest birds are stronger
* Consider which nest goals exist and lean more on keeping and playing birds with that nest
* Varying location based goals (eggs or birds in one of the 3 habitats) means the flighty birds (when on the right change habitat) are stronger
* With all of the above in mind, specific pink birds become stronger too as opponents are forced into taking these actions or forgo end of round goals
* Weight the later goals more heavily since these are worth more points - there's nothing wrong with skipping the first goal or two if it means positioning yourself to win the last one or two

You should think of the bonus cards as additional private end of game goals. Consider whether one of your bonus cards aligns with later end of round goals as that increases its value. Then move to your birds. Cross reference the end of round goals and above info with your hand and the available birds. Ideally you want to plan out your first few turns. Some general principles:

* Brown and pink action birds are ideal in the early game when there is more time to trigger their ability. More specifically you want powers that generate additional resources - cards > food > eggs. With that...
** Cards: this is the most important resource. Having a good card draw/cycle engine lets you find the birds you actually want to play often while scoring tuck points
** Food: you need food to play your cards, but you don't know what food you need until you find good cards and you can discard cards for food. Over the course of a game you should be drawing (and pitching) a lot more cards than food. Caching food is basically always worse than gaining it until the last turn or two depending on what birds and how much food you have
** Eggs: eggs are inherently less valuable than the other resources until the end of the game when eggs score points whereas cards and food do not. I say inherently because at every step you get 1 more egg than the other resources. So early in the game, you almost always want to spend an egg to draw (if you can) whereas later you need to think about it a bit more
* The best starting birds either draw you food or cards. If you get both, your early game should run very smoothly
** You should obviously consider the cost of each bird when making this decision. That 3-cost food producer might be good early, but consider how that will impact your ability to play other birds.
* Note if you're going first as you are guaranteed your pick of the shown birds which may be better to start with than any in your hand - there's nothing wrong with drawing a powerful bird on your first turn
* Generally you should be keeping 1-3 birds. Keeping 5 should literally never be done and keeping 4 only makes sense if your hand is insane and/or you have a 1-cost forest bird going into 2 food production
* Be wary of any actions that benefit opponents equally to you. These are probably bad in almost all cases

== Mid-Game ==

You should have a small resource engine hopefully consisting of birds that play toward at least one goal. Here are some principles focused more on the midgame:

* Routinely check your opponents boards and consider which remaining goals you have a realistic chance at winning. Compare how hard you have to invest into the goal, how likely you are to win it, and what you could be doing instead which might yield a greater long-term return e.g. maybe a later goal if players are less invested into it
** You should check their resource count and engine power as this factors in to how much they can develop into goals. If you're not that far behind then you may see that their resources cannot (or are very unlikely) to outpace you
* Also check for pink birds. In some cases you should actually skip an action (e.g. predator) to prevent an opponent from gaining a more valuable resource (food is generally worth more than one point). But this is just a consideration - you can't skip playing birds in a habitat altogether but maybe you can wait to do it on the same turn as another opponent
* It is good to play bonus card birds in the mid game. This will give you time to play toward the goal while having less impact on your early engine
* If you have a good card draw engine, prioritize and collect additional play birds. Planning around big bird chains in the last round can often turn the tide of a game

== End Game ==

As the 3rd round comes to an end and the final round approaches you should be able to plan out the rest of your turns. Make a final decision on which goals you can reasonably commit to and play accordingly. It's okay to not always get the highest tier goal. Maybe playing out your non-goal birds in hand yields more points. Or maybe you should stock your remaining birds with eggs. You should be able to calculate which route has the highest expected score. Good luck!

Tips wingspan

2022-10-06T02:44:58Z

Fletcheese: Initial creation with general strategy

== Wingspan Strategy ==

=== Introduction ===

At its core Wingspan is an engine building resource management game. Your most finite resources is actions as you are limited to 26 (8+7+6+5) of these each game. So generally speaking you want to get the most out of every action. Play that bird before you take an action in its row so that you get an extra resource. There are of course exceptions to this e.g. if you need to move up in the rankings for an end of round goal.

=== Early Game ===

When the game starts take the time to analyze each of these goals as they will heavily shape what to go for in this game. Lots of egg goals? Investing more into the grasslands may be a good idea. Lots of bird goals? Investing more into the Forest may be better. These are both oversimplifications as generally speaking you will build birds in every habitat and take every action over the course of most games. There are many other important considerations:

* Many nest-specific goals means the wild nest birds are stronger
* Consider which nest goals exist and lean more on keeping and playing birds with that nest
* Varying location based goals (eggs or birds in one of the 3 habitats) means the flighty birds (when on the right change habitat) are stronger
* With all of the above in mind, specific pink birds become stronger too as opponents are forced into taking these actions or forgo end of round goals
* Weight the later goals more heavily since these are worth more points - there's nothing wrong with skipping the first goal or two if it means positioning yourself to win the last one or two

You should think of the bonus cards as additional private end of game goals. Consider whether one of your bonus cards aligns with later end of round goals as that increases its value. Then move to your birds. Cross reference the end of round goals and above info with your hand and the available birds. Ideally you want to plan out your first few turns. Some general principles:

* Brown and pink action birds are ideal in the early game when there is more time to trigger their ability. More specifically you want powers that generate additional resources - cards > food > eggs. With that...
** Cards: this is the most important resource. Having a good card draw/cycle engine lets you find the birds you actually want to play often while scoring tuck points
** Food: you need food to play your cards, but you don't know what food you need until you find good cards and you can discard cards for food. Over the course of a game you should be drawing (and pitching) a lot more cards than food. Caching food is basically always worse than gaining it until the last turn or two depending on what birds and how much food you have
** Eggs: eggs are inherently less valuable than the other resources until the end of the game when eggs score points whereas cards and food do not. I say inherently because at every step you get 1 more egg than the other resources. So early in the game, you almost always want to spend an egg to draw (if you can) whereas later you need to think about it a bit more
* The best starting birds either draw you food or cards. If you get both, your early game should run very smoothly
** You should obviously consider the cost of each bird when making this decision. That 3-cost food producer might be good early, but consider how that will impact your ability to play other birds.
* Note if you're going first as you are guaranteed your pick of the shown birds which may be better to start with than any in your hand - there's nothing wrong with drawing a powerful bird on your first turn
* Generally you should be keeping 1-3 birds. Keeping 5 should literally never be done and keeping 4 only makes sense if your hand is insane and/or you have a 1-cost forest bird going into 2 food production
* Be wary of any actions that benefit opponents equally to you. These are probably bad in almost all cases

=== Mid-Game ===

You should have a small resource engine hopefully consisting of birds that play toward at least one goal. Here are some principles focused more on the midgame:

* Routinely check your opponents boards and consider which remaining goals you have a realistic chance at winning. Compare how hard you have to invest into the goal, how likely you are to win it, and what you could be doing instead which might yield a greater long-term return e.g. maybe a later goal if players are less invested into it
** You should check their resource count and engine power as this factors in to how much they can develop into goals. If you're not that far behind then you may see that their resources cannot (or are very unlikely) to outpace you
* Also check for pink birds. In some cases you should actually skip an action (e.g. predator) to prevent an opponent from gaining a more valuable resource (food is generally worth more than one point). But this is just a consideration - you can't skip playing birds in a habitat altogether but maybe you can wait to do it on the same turn as another opponent
* It is good to play bonus card birds in the mid game. This will give you time to play toward the goal while having less impact on your early engine
* If you have a good card draw engine, prioritize and collect additional play birds. Planning around big bird chains in the last round can often turn the tide of a game

=== End Game ===

As the 3rd round comes to an end and the final round approaches you should be able to plan out the rest of your turns. Make a final decision on which goals you can reasonably commit to and play accordingly. It's okay to not always get the highest tier goal. Maybe playing out your non-goal birds in hand yields more points. Or maybe you should stock your remaining birds with eggs. You should be able to calculate which route has the highest expected score. Good luck!

Gamehelplittlefactory

2022-09-29T20:03:35Z

Fletcheese: Minor corrections

== Object of the Game ==

Be the first to score ten (10+) or more '''Influence Points''' (VPs) by producing buildings and also using your buildings to produce more VPs.

== First Turn ==

On the first turn you may trade up to all of your coins for basic goods (wood,
grain, clay, stone, and/or cotton) as long as they are available. The first
player starts with three (3), second four (4), third (5) etc.

== Game-play ==

On your turn you must choose to either '''Produce''' or '''Trade'''
''You have a set hand limit of seven (7) goods.''

* '''Produce''' a single basic good (wood, wheat, clay, stone, or cotton)

* '''Produce''' a single trade good by revealing or expending one or more other goods (as shown below and in the '''Conversion Chart''' in the lower right of the game board)

* '''Trade''' a number of goods for other goods / buildings of equal (or lesser) cost

* ''Additionally, each building you own may perform its action once per turn - before or after you produce or trade ''

Expended Basic Goods returned to their columns for immediate reuse.

Expended Trade Goods go into the discard pile to the right of their deck.

When a column of Trade Goods is depleted, replacement cards are drawn until there are again five distinct cards, shuffling the discard pile as needed.

After your turn, it proceeds to the next player.

This repeats until the winning condition are met. A player has ten (10+) or more victory points.

=== Trading ===

Each good has a value in the upper left, which is its trade value (which is always equal to it purchase price, in the lower center-right). This value (combined with any other cards) may be used to purchase any other available card(s). Either the number of cards you discard or gain must be 1.

=== Producing ===

A good may be produced if it is in one of the five columns on the left side of the board by revealing or expending the appropriate good(s).

The piles to the right of the decks show cards that have been previously expended. These cards may be examined at any time, but may not produced.

Note that basic goods do not have a cost, so you may always produce one basic good (among those available on the bottom row). This is inefficient but sometimes necessary.

If you have multiple choices of what to produce, you can only select one per turn. However buildings allow you to perform additional conversions.

=== Buildings ===

Buildings are worth 1-3 '''Influence Points''' (VPs). Most buildings have an additional ability (a limited extra trade/consume phase), which is either one of the trades on the '''Conversion Chart''' or a trade of one or more specific goods for a given number of additional Influence Points.
If the conditions on the top of the card are met you will have the option to play the card once during your turn, either before or after you Trade or Produce.

== The Goods ==

=== Basic Goods ===
First Level (Beige)

All Basic Goods have trade value 1. The numbers after each good are the quantity available with 4/3/2 players.
;Wood (5/4/3)
:Expend two (x2) to produce Paling
:Expend to produce Coal
:Expend with Grain to produce Sheep
:Expend with Clew to produce Fishing Rod

;Wheat (3/3/2)
:Expend to produce Flour
:Expend with Wood to produce Sheep
:Expend with Clay to produce Cow

;Clay (3/3/2)
:Expend with Grain to produce Cow
:Expend to produce Clay Brick
:Expend with Stone Brick to produce Wall

;Stone (3/2/2)
:Expend to produce Cut Stone
:Expend to produce Fish
:Expend with Coal to produce Beam

;Cotton (2/1/1)
:Expend to produce Clew

=== Second Level Trade Goods (Blue) ===

;Paling (wooden boards) (Value 5, Quantity 2)
:Expend to produce Barrel
:Expend to build Fishmonger
:Expend to build Spinning Mill
:Expend to build Cloth Mill
:Expend to build Fish Pond
:Expend to build Cattle Ranch
:Expend with Clay Brick and Cut Stone to build Mansion
:Expend with Beam and Wall to build Castle
;Coal (Value 3, Quantity 3)
:Expend with Stone to produce Beam
:Expend with Flour to produce Bread
:Expend to build Butcher Shop
:Expend to build Clay Brick Factory
:Expend with Clay Brick to build Brewery
;Flour (Value 3, Quantity 2)
:Expend with Coal to produce Bread
:Expend to build Masonry
;Sheep (Value 5, Quantity 2)
:Reveal to produce Clew
:Expend to produce Steak
;Cow (Value 5, Quantity 2)
:Reveal to produce Milk
:Expend to produce Steak
;Clay Brick (Value 3, Quantity 3)
:Expend to build Bakery
:Expend to build Foundry
:Expend to build Water Mill
:Expend to build Sheep Ranch
:Expend to build Milk Shop
:Expend to build Quarry
:Expend with Coal to build Brewery
:Expend with Stone Brick to build Bread Store
:Expend with Paling and Stone Brick to build Mansion
;Cut Stone (Value 3, Quantity 2)
:Expend with Clay to produce Wall
:Expend to build Sawmill
:Expend to build Barrel Factory
:Expend to build Leather Factory
:Expend to build Charcoal Hut
:Expend to build Dairy
:Expend with Clay Brick to build Bread Store
:Expend with Paling and Clay Brick to build Mansion
;Fish (Value 5, Quantity 1)
:Expend to build Specialty Shop
;Clew (yarn) (Value 3, Quantity 2)
:Expend with Wood to produce Fishing Rod
:Expend to produce Cloth

=== Third Level Trade Goods (Purple) ===

All third level trade goods are unique (have quantity 1)

;Barrel (Value 8)
;Beam (Value 8)
:Expend with Paling and Wall to build Castle
:Expend to build Deli
:Expend to build Shoe Store
;Bread (Value 11)
;Steak (Value 8)
;Leather (sometimes called Fabric) (Value 8)
;Milk (Value 4)
;Wall (Value 8)
:Expend to build Tailor
:Expend to build Restaurant
:Expend to build Cheese Store
:Expend with Paling and Beam to build Castle
;Fishing Rod (Value 8)
:Reveal to produce Fish
;Cloth (Value 6)
:Expend to build Hardware Store

== The Buildings ==
Once you have a building a process will be "automated" for you, provided that you have the necessary input good(s) and that the output good is available.
The building may activated only once during your turn.
A building can be produced by expending the good(s) listed at the bottom right in lieu of trading for its "cost".

=== Worth 1VP ===

;Butcher Shop (Expend Coal or trade in 6)
:Allows you to expend Sheep to produce Steak
:Allows you to expend Cow to produce Steak
;Brick Factory (Expend Coal or trade in 6)
:Allows you to expend Clay to produce Clay Brick
;Bakery (Expend Clay Brick or trade in 6)
:Allows you to expend Coal and Flour to produce Bread
;Foundry (Expend Clay Brick or trade in 6)
:Allows you to expend Coal and Cut Stone to produce Beam
;Water Mill (Expend Clay Brick or trade in 6)
:Allows you to expend Grain to produce Flour
;Sheep Ranch (Expend Clay Brick or trade in 6)
:Allows you to expend Wheat and Wood to produce Sheep
;Barrel Factory (Expend Cut Stone or trade in 6)
:Allows you to expend Paling to produce Barrel
;Leather Factory (Expend Cut Stone or trade in 6)
:Allows you to expend Cow to produce Leather
;Milk Shop (Expend Clay Brick or trade in 6)
:Allows you to expend Milk to gain 1VP
;Charcoal Hut (Expend Cut Stone or trade in 6)
:Allows you to expend Wood to produce Coal
;Quarry (Expend Clay Brick or trade in 6)
:Allows you to expend Stone to produce Cut Stone.
;Sawmill (Expend Cut Stone or trade in 6)
:Allows you to expend 2x Wood to produce Paling
;Dairy (Expend Cut Stone or trade in 6)
:Allows you to reveal Cow to produce Milk
;Masonry (Expend Flour or trade in 6)
:Allows you to expend Cut Stone and Clay to produce Wall

;Fishmonger (Expend Paling or trade in 8)
:Allows you to expend Fish to gain 1VP
;Specialty Shop (Expend Fish or trade in 8)
:Allows you to trade a level 3 good for other goods ('''not''' buildings)
;Spinning Mill (Expend Paling or trade in 8)
:Allows you to reveal Sheep or expend Cotton to produce Clew
;Textile Mill (Expend Paling or trade in 8)
:Allows you to expend Clew to produce Cloth
;Fish Pond (Expend Paling or trade in 8)
:Allows you to reveal Fishing Rod or expend Stone to produce Fish
;Cattle Range (Expend Paling or trade in 8)
:Allows you to expend Clay and Wheat to produce Cow

;Hardware Store (Expend Cloth or trade in 10)
:Allows you to expend Leather to gain 2VP
:Allows you to expend Beam to gain 2VP

=== Worth 2VP ===

;Brewery (Expend Clay Brick and Coal or trade in 11)
:Allows you to expend Barrel and Wheat to gain 2VP
;Bread Store (Expend Clay Brick and Cut Stone or trade in 11)
:Allows you to expend Bread to gain 2VP
;Deli (Expend Beam or trade in 12)
:Allows you to expend Steak to gain 2VP
;Shoe Store (Expend Beam or trade in 12)
:Allows you to expend Leather and Clew to gain 3VP
;Tailor (Expend Wall or trade in 12)
:Allows you to expend Cloth and Clew to gain 2VP
;Restaurant (Expend Wall or trade in 12)
:Allows you to expend Steak and Bread to gain 4VP
;Cheese Store (Expend Wall or trade in 12)
:Allows you to expend Barrel and Milk to gain 3VP

=== Worth 3VP ===

;Mansion (Expend Paling, Clay Brick, and Cut Stone or trade in 18)
:Has no effect

=== Worth 5VP ===

;Castle (Expend Paling, Bean, and Wall or trade in 30)
:Has no effect

== Anatomy of Card ==
* Bottom center - the cost of the card
** Each board represents one method of obtaining the card
** If an icon includes the card outline, it is merely revealed, otherwise it is expended
** If there are two icons, both must be paid
** The right-most icon is the purchase price, which is paid by expending goods (or gold, on the first turn of the game)
* Bottom right (small) - total copies of card in the deck
* Upper left ''(Goods Only)'' -- small icon and trade-in value of card
* Top ''(Buildings Only)'' - "Automated" Action which may be performed once a turn, if the inputs are owned and the output is available

Gamehelpgizmos

2022-09-29T02:23:09Z

Fletcheese: Initial population using rules as guidance

== Overview ==

Gizmos is an engine building resource management game. You will start with simple turns consisting of a single action while building your engine up to the point where you can trigger many actions per turn.

== The Player Turn ==

On your turn, you must perform 1 of the following actions:

* File: File 1 Gizmo from the Display Area.
* Pick: Pick 1 Energy of your choice from the Energy Row.
* Build: Build 1 Gizmo from the Display Area or from your Archive.
* Research: Draw Gizmo cards from 1 of the facedown Level Decks and choose 1 to File or Build

=== File ===

Select 1 faceup Gizmo card from any row and then choose File. After Filing a Gizmo, it is immediately replaced with the top card of the corresponding deck. After you draw this new Gizmo, your File Action is over.

Your Archive has a limit to how many Gizmos it can hold, as indicated in your Player Dashboard’s Upgrades Area. Each player starts the game with a File Limit of 1, but some Upgrade Gizmos will increase that number. Your Archive can never hold more Gizmos than your File Limit, so if you are at your limit, you cannot take a File Action.

=== Pick ===

Choose 1 Energy from the 6 available in the Energy Row to add it to your Energy Storage Ring. Your Energy Storage Ring has a limited amount of Energy it can hold, as indicated in your Player Dashboard’s Upgrades Area. Each player starts the game with a Storage Limit of 5, but some Upgrade Gizmos will increase that number. Your Ring can never hold more Energy than your Energy Storage Limit, so if you are at your limit, you cannot take any more Energy, not even to replace existing ones.

:: '''IMPORTANT''': Some abilities let you '''Draw''' a random Energy. This is ''not'' a Pick Action and thus will not trigger any other actions.

=== Build ===

Choose 1 faceup Gizmo card from the Display Area OR from your Archive. Spend Energy from your Energy Storage Ring matching the Gizmo’s Energy Type and Cost. After building a Gizmo from a row it is immediately replaced with a new Gizmo from the top of the corresponding deck. After replenishing, your Build action is over.

The Gizmo goes below your Player Dashboard in the area corresponding to its Gizmo Type stacked so you can see all of their effects.

==== Converters ====

When performing a Build Action, you may be able to use your active Converter Gizmos to convert the Energy you have into the Energy you need. You may do this by selecting your built Converter. More details on the types of Converters may be found in the linked List of Effects PDF.

=== Research ===

Choose any facedown Level Deck (1, 2, or 3) and draw a number of cards equal to your Research Amount. You may not draw from more than 1 Level Deck at a time. Each player starts the game with a Research Amount of 3, but some Upgrade Gizmos will increase that number. If there are fewer cards in the chosen Level Deck than your Research Amount, you will draw only the number of cards available. After you draw the cards, choose 1 of them and either Build it (if you have enough Energy) or File it (if you have space in your Archive). Or you can choose to do neither and Pass.

The remaining cards are then returned to the bottom of the corresponding Level Deck, in the order of your choosing.

:: '''Note''': The File or Build Action you perform during a Research Action also counts to trigger active Gizmos (see Triggering Gizmo Effects below).

=== Triggering Gizmo Effects ===

While taking 1 of the 4 available actions is the basis of the game, the real core of it (and the key to victory) is triggering your Gizmos’ effects in order to accomplish much more on your turn than you would otherwise. Every Gizmo you Build and place below your Player Dashboard has an Effect that is activated by a specific Trigger (learn all about these in the linked PDF of List of Effects). Whenever you perform an action, Gizmos that have triggered will be highlighted. After the triggering action is complete, you may activate the Effects of any triggered Gizmos, in any order you wish. Just keep in mind that each Gizmo may only be '''used''' once per turn even if its trigger conditions are met more than once.

:: '''Note:''' you '''may''' use the Effect of a Gizmo on the same turn it is built. However, it cannot be triggered by the same action that Built it.

== Chain Reactions ==

The secret of master inventors is building their Gizmos in a way that will cause chain reactions, with one Gizmo triggering another to generate the most benefits! The Effect of one Gizmo may be a different action than the one originally performed. So, when you then perform that secondary action, it may trigger other Gizmos, and so on. Whenever you perform an action, whether it’s your one action for that turn
or an action triggered by a Gizmo Effect, always check the Gizmos under that action to see if any of them are triggered.

There is no limit to the number of Gizmos that may be activated, but always remember that each Gizmo can only be used once per turn. The order in which each Gizmo’s effect is executed is up to the player, regardless of the order in which the actions that triggered those effects occurred. A Gizmo built at the beginning of a chain reaction may end up being activated later in that chain reaction, as long as it’s not triggered by the action that Built it. Sometimes finding the optimal order to execute actions and effects can yield greater results.

== End of the Game ==

The end of the game is triggered when a player builds their 4th Level 3 Gizmo or their 16th Gizmo total (including their Starting Gizmo). Once that happens, play continues until the player to the right of the First Player completes their turn. That is, until all players have had an equal number of turns in the game. If the player who triggered the end of the game is the player to the right of the First Player, then the game ends when they complete their turn.

Naturally the player with the most Victory Points wins! In case of a tie, the tied player with the most Gizmos in their Active Gizmo Area wins (this does not include Filed Gizmos). If it’s still tied, the tied player with the most Energy left in their Energy Storage Ring wins. If it’s still tied, the tied player furthest from the First Player, going clockwise, wins.

Tips littlefactory

2022-07-20T19:36:06Z

Fletcheese:

=== Disclaimer ===

Much of the following only applies to 2-player games as this is the competitive format. With more than 2 players things get a little crazier because only the level 1 resource numbers change, so all the decks cycle much more quickly. Generally speaking this means that resource production buildings are better and point production buildings are worse as there are more players who can grab and hold those resources. Kingmaker situations are common. 

=== Early Game ===
• Securing buildings that give level 2 resource production is crucial, but not at the cost of your entire economy 
• First player must trade for 3 level 1 resources based on what's currently shown - trading for a single level 2 makes it too easy for the opponent to block 
• Second player has the option to trade for and effectively block one of first player's level 2 build options - this can be a good idea if that resource builds into a powerful building like coal, stone, or brick production 
• Consider trading for all of one or more level 1 resource types to prevent the opponent from being able to buy certain cards - this is particularly effective for wheat or stone, but is applicable for clay or wood in some cases 

=== Midgame / General Strategy ===
• Pay attention to what resources your opponent is grabbing - buying cards out from under your opponent can be pivotal 
• The game is played in cycles of building up high value cards and then trading them down for buildings or more resources - it's important to not spend all of your resources on buildings i.e. try to keep at least one 3+ value card to trade your way back into production 
• If a player is low on resources, it is easier to hamstring them into no options but slow production - always keep this in mind for yourself and your opponent 
• Watch the discard piles and deck sizes. If you can, spend the resources you produce via buildings before the deck is reshuffled as rebuilding those resources is free value. Conversely, try to buy and hold resources your opponent builds freely so they do not get the extra value 
• When producing a resource always consider what the next card of the deck could be. In some cases waiting to use your building to produce at the start of your turn is better to give your opponent one less option. In other cases, producing it now is better because the opponent would otherwise buy it out from under you. 

=== Late Game ===
• Building up high resource value is great, but never forget that the only way to win is to reach 10 points. Plan out turns in advance to see if it's time to flip the switch and just buy buildings or if continuing to increase resource value makes sense 
• Pay especially close attention to cards that convert resources to points as a player can win in one turn from as low as 6, 5, or even 4 points in very rare cases - with proper planning it should be easy to block these sorts of plays

Tips littlefactory

2022-07-20T19:35:34Z

Fletcheese: /* Early Game */

=== Disclaimer ===

Much of the following only applies to 2-player games as this is the competitive format. With more than 2 players things get a little crazier because only the level 1 resource numbers change, so all the decks cycle much more quickly. Generally speaking this means that resource production buildings are better and point production buildings are worse as there are more players who can grab and hold those resources. Kingmaker situations are common. 

=== Early Game ===
• Securing buildings that give level 2 resource production is crucial, but not at the cost of your entire economy 
• First player must trade for 3 level 1 resources based on what's currently shown - trading for a single level 2 makes it too easy for the opponent to block 
• Second player has the option to trade for and effectively block one of first player's level 2 build options - this can be a good idea if that resource builds into a powerful building like coal, stone, or brick production 
• Consider trading for all of one or more level 1 resource types to prevent the opponent from being able to buy certain cards - this is particularly effective for wheat or stone, but is applicable for clay or wood in some cases 
• When producing a resource always consider what the next card of the deck could be. In some cases waiting to use your building to produce at the start of your turn is better to give your opponent one less option. In other cases, producing it now is better because the opponent would otherwise buy it out from under you. 

=== Midgame / General Strategy ===
• Pay attention to what resources your opponent is grabbing - buying cards out from under your opponent can be pivotal 
• The game is played in cycles of building up high value cards and then trading them down for buildings or more resources - it's important to not spend all of your resources on buildings i.e. try to keep at least one 3+ value card to trade your way back into production 
• If a player is low on resources, it is easier to hamstring them into no options but slow production - always keep this in mind for yourself and your opponent 
• Watch the discard piles and deck sizes. If you can, spend the resources you produce via buildings before the deck is reshuffled as rebuilding those resources is free value. Conversely, try to buy and hold resources your opponent builds freely so they do not get the extra value 

=== Late Game ===
• Building up high resource value is great, but never forget that the only way to win is to reach 10 points. Plan out turns in advance to see if it's time to flip the switch and just buy buildings or if continuing to increase resource value makes sense 
• Pay especially close attention to cards that convert resources to points as a player can win in one turn from as low as 6, 5, or even 4 points in very rare cases - with proper planning it should be easy to block these sorts of plays

Tips railroadink

2022-07-20T17:26:14Z

Fletcheese: More lake notes

== General Strategy / Base Game ==

• Try and pick a starting point, then head in one direction with roads, and in the other direction with railroads, to maximize points for longest highway/railroad. While most of your points will come from connecting exits, having a route or even a bridge/special route run through the center is a good idea for additional points. 

• Remember you can let roads and railroads end on the side of the board, even when there is no exit. These do not count as a penalty. 

• Be smart about bridge use - this does not count as a connection between your road and railroad, but it does double dip in terms of points for longest road and railroad if placed well. When you do not have a good place, try to use it as a straight road/railroad along the edge as this mitigates the point loss to -1 instead of -2. 

• Don't forget to use your first special route by the end of the 5th round, as you only get 3 and can only use one per round. Ideally it should be one of the two railroad, two road junctions and be played early in the game to ensure your longest road and railroad are part of a single network. The best places for it are one of the center exits, one up from each exit in a corner, or in the actual center. Special routes should either be planned around explicitly or used in place of 3-way connectors that never come. Unless desperate in the last couple rounds, you should never throw a converter in the middle of your road/railroad. Converters should be placed at "in-betweener" exits to ensure your longest road/railroad can continue connecting exits uninterrupted. Use 3-way pieces in tandem with the converters to maintain one network. 

• On the last turn, prioritize using extra rolls to close off penalties rather than lengthen rail/roads or fill center tiles because number of penalties is the first tiebreaker after score

• A well-played game generally scores in the 60s: 36-45 from exits, 20-30 total between longest road and railroad, 3-9 for center, and negative 0-10 for broken ends. There is a lot of variation based on routes offered. High scoring rolls can get into the 70s or even low 80s. 

== Expansions ==

=== River ===

• Careful use of the river bridges is crucial 

• There's a constant struggle to determine whether it's worth the risk of hoping to hit the right river pieces to extend or if you should connect the edge now and not take the risk. Take calculated risks based on what your opponents have done. 

=== Lakes ===

• Lakes make it much easier to connect all exits due to piers. Keep in mind for every route you build that you will need to find a way to connect it to your lake via a pier, but in ~90% of games you should score all 45 points for exits if you played well 

• It is crucial that you have a single lake at the end of the game as this should amount to 15-20 points. If there are a lot of early pier rolls, focus on building your lake on a corner/half of the board and your longest road/railroad networks on the other side. But make sure you don't neglect going for a long road/railroad as these should also amount to 15-25 points collectively 

• In a game with less piers, focusing your lake in mostly the center of the board is safer 

• Unlike in the base game, building your longest road and railroad as separate networks is okay because they can be connected via piers on your lake. 

• Auto-filling tiles with water is crucial because (a) it lets you sprawl your lake wider for more connectivity and (b) it's free points toward lake size. Aim to fill 5+ tiles with water. Plan your lake with early positioning of 2 and 3-sided water tiles with other 1-sided waters to "cascade" water-fill in the last few rounds. 

• If well-planned, you should not rely on rolling 2/3 sided tiles to connect your lake. It's okay to have some penalties placing late piers that can't connect - this will simply offset one of your auto-filled tiles. Don't forget that open water sides do not count as a penalty. 

• Keep in mind that your lake does not have to be one solid mass of water - it can have islands. Placing two 3-side water tiles with their land-side touching surrounded by other water to later cascade auto-fill is a great strategy

=== Meteor ===

• Meteor is the least impactful expansion. There are a few key differences to keep in mind, but the overall game plan largely matches the base game 

• Key point #1: base your route connection (where road meets railroad) as far as possible from the meteor to minimize the possibility of interruptionM 

• Key point #2: later in the game build toward the early meteor hits - especially ones in the center. If two meteor strikes line up diagonally, then putting a 3-sided road/rail, bridge, or even special route adjacent to both of them is worth 4 points 

• Key point #3: you should almost never use a special route to prevent a meteor landing. Keep in mind that you can always place on top of meteor strikes. I.e. if a meteor lands on your road/railroad and it's not a special route, then you can just cover it up with that same piece once it rolls again or worst case use the special route you would have covered up preventing it. 

• Other than that focus on the usual things. Maintain continuous road and railroad segments as long as possible. There are 6 instead of 7 rounds so building through the center is likely a tad worse than in the base game. 

=== Lava ===

• Building a volcano in the corner with a road/rail volcano piece on each side is a fantastic option: +5 points for a closed volcano using only 3 pieces while also contributing toward connected routes. However you should almost always join them with a special route rather than a bridge because hoping to join up your road/railroads later is very risky.

Tips littlefactory

2022-07-19T22:19:45Z

Fletcheese:

=== Disclaimer ===

Much of the following only applies to 2-player games as this is the competitive format. With more than 2 players things get a little crazier because only the level 1 resource numbers change, so all the decks cycle much more quickly. Generally speaking this means that resource production buildings are better and point production buildings are worse as there are more players who can grab and hold those resources. Kingmaker situations are common. 

=== Early Game ===
• Securing buildings that give level 2 resource production is crucial, but not at the cost of your entire economy 
• First player must trade for 3 level 1 resources based on what's currently shown - trading for a single level 2 makes it too easy for the opponent to block 
• Second player has the option to trade for and effectively block one of first player's level 2 build options - this can be a good idea if that resource builds into a powerful building like coal, stone, or brick production 
• Consider trading for all of one or more level 1 resource types to prevent the opponent from being able to buy certain cards - this is particularly effective for wheat or stone, but is applicable for clay or wood in some cases 

=== Midgame / General Strategy ===
• Pay attention to what resources your opponent is grabbing - buying cards out from under your opponent can be pivotal 
• The game is played in cycles of building up high value cards and then trading them down for buildings or more resources - it's important to not spend all of your resources on buildings i.e. try to keep at least one 3+ value card to trade your way back into production 
• If a player is low on resources, it is easier to hamstring them into no options but slow production - always keep this in mind for yourself and your opponent 
• Watch the discard piles and deck sizes. If you can, spend the resources you produce via buildings before the deck is reshuffled as rebuilding those resources is free value. Conversely, try to buy and hold resources your opponent builds freely so they do not get the extra value 

=== Late Game ===
• Building up high resource value is great, but never forget that the only way to win is to reach 10 points. Plan out turns in advance to see if it's time to flip the switch and just buy buildings or if continuing to increase resource value makes sense 
• Pay especially close attention to cards that convert resources to points as a player can win in one turn from as low as 6, 5, or even 4 points in very rare cases - with proper planning it should be easy to block these sorts of plays

Tips railroadink

2022-07-12T17:37:12Z

Fletcheese: /* Expansions */

== General Strategy / Base Game ==

• Try and pick a starting point, then head in one direction with roads, and in the other direction with railroads, to maximize points for longest highway/railroad. While most of your points will come from connecting exits, having a route or even a bridge/special route run through the center is a good idea for additional points. 

• Remember you can let roads and railroads end on the side of the board, even when there is no exit. These do not count as a penalty. 

• Be smart about bridge use - this does not count as a connection between your road and railroad, but it does double dip in terms of points for longest road and railroad if placed well. When you do not have a good place, try to use it as a straight road/railroad along the edge as this mitigates the point loss to -1 instead of -2. 

• Don't forget to use your first special route by the end of the 5th round, as you only get 3 and can only use one per round. Ideally it should be one of the two railroad, two road junctions and be played early in the game to ensure your longest road and railroad are part of a single network. The best places for it are one of the center exits, one up from each exit in a corner, or in the actual center. Special routes should either be planned around explicitly or used in place of 3-way connectors that never come. Unless desperate in the last couple rounds, you should never throw a converter in the middle of your road/railroad. Converters should be placed at "in-betweener" exits to ensure your longest road/railroad can continue connecting exits uninterrupted. Use 3-way pieces in tandem with the converters to maintain one network. 

• On the last turn, prioritize using extra rolls to close off penalties rather than lengthen rail/roads or fill center tiles because number of penalties is the first tiebreaker after score

• A well-played game generally scores in the 60s: 36-45 from exits, 20-30 total between longest road and railroad, 3-9 for center, and negative 0-10 for broken ends. There is a lot of variation based on routes offered. High scoring rolls can get into the 70s or even low 80s. 

== Expansions ==

=== River ===

• Careful use of the river bridges is crucial 

• There's a constant struggle to determine whether it's worth the risk of hoping to hit the right river pieces to extend or if you should connect the edge now and not take the risk. Take calculated risks based on what your opponents have done 

=== Lakes ===

• Lakes make it much easier to connect all exits due to piers. Keep in mind for every route you build that you will need to find a way to connect it to your lake via a pier, but in ~90% of games you should score all 45 points for exits if you played well 

• It is crucial that you have a single lake at the end of the game as this should amount to 15-20 points. If there are a lot of early pier rolls, focus on building your lake on a corner/half of the board and your longest road/railroad networks on the other side. But make sure you don't neglect going for a long road/railroad as these should also amount to 15-25 points collectively 

• In a game with less piers, focusing your lake in mostly the center of the board is safer 

• Unlike in the base game, building your longest road and railroad as separate networks is okay because they can be connected via piers on your lake. 

• Auto-filling tiles with water is crucial because (a) it lets you sprawl your lake wider for more connectivity and (b) it's free points toward lake size. Aim to fill 5+ tiles with water. Plan your lake with early positioning of 2 and 3-sided water tiles with other 1-sided waters to "cascade" water-fill in the last few rounds. 

• If well-planned, you should not rely on rolling 2/3 sided tiles to connect your lake. It's okay to have some penalties placing late piers that can't connect - this will simply offset one of your auto-filled tiles. Don't forget that open water sides do not count as a penalty

=== Meteor ===

• Meteor is the least impactful expansion. There are a few key differences to keep in mind, but the overall game plan largely matches the base game 

• Key point #1: base your route connection (where road meets railroad) as far as possible from the meteor to minimize the possibility of interruptionM 

• Key point #2: later in the game build toward the early meteor hits - especially ones in the center. If two meteor strikes line up diagonally, then putting a 3-sided road/rail, bridge, or even special route adjacent to both of them is worth 4 points 

• Key point #3: you should almost never use a special route to prevent a meteor landing. Keep in mind that you can always place on top of meteor strikes. I.e. if a meteor lands on your road/railroad and it's not a special route, then you can just cover it up with that same piece once it rolls again or worst case use the special route you would have covered up preventing it. 

• Other than that focus on the usual things. Maintain continuous road and railroad segments as long as possible. There are 6 instead of 7 rounds so building through the center is likely a tad worse than in the base game. 

=== Lava ===

• Building a volcano in the corner with a road/rail volcano piece on each side is a fantastic option: +5 points for a closed volcano using only 3 pieces while also contributing toward connected routes. However you should almost always join them with a special route rather than a bridge because hoping to join up your road/railroads later is very risky

Tips railroadink

2022-06-30T16:24:13Z

Fletcheese: Formatting and started expansions section with lakes

Tips littlefactory

2022-06-10T17:19:05Z

Fletcheese: More detail, better formatting

=== Disclaimer ===

Much of the following only applies to 2-player games as this is the competitive format. With more than 2 players things get a little crazier because only the level 1 resource numbers change, so all the decks cycle much more quickly. Generally speaking this means that resource production buildings are better and point production buildings are worse as there are more players who can grab and hold those resources. Kingmaker situations are common.

=== Early Game ===
• Securing buildings that give level 2 resource production is crucial, but not at the cost of your entire economy 
• First player must trade for 3 level 1 resources based on what's currently shown - trading for a single level 2 makes it too easy for the opponent to block 
• Second player has the option to trade for and effectively block one of first player's level 2 build options - this can be a good idea if that resource builds into a powerful building like coal, stone, or brick production 
• Consider trading for of one or more level 1 resource types to force your opponent off of certain level 2s - this is particularly effective for wheat or stone, but is applicable for clay or wood in some cases 

=== Midgame / General Strategy ===
• Pay attention to what resources your opponent is grabbing - buying cards out from under your opponent can be pivotal 
• The game is played in cycles of building up high value cards and then trading them down for buildings or more resources - it's important to not spend all of your resources on buildings i.e. try to keep at least one 3+ value card to trade your way back into production 
• If a player is low on resources, it is easier to hamstring them into no options but slow production - always keep this in mind for yourself and your opponent 
• Watch the discard piles and deck sizes. If you can, spend the resources you produce via buildings before the deck is reshuffled as rebuilding those resources is free value. Conversely, try to buy and hold resources your opponent builds freely so they do not get the extra value

=== Late Game ===
• Building up high resource value is great, but never forget that the only way to win is to reach 10 points. Plan out turns in advance to see if it's time to flip the switch and just buy buildings or if continuing to increase resource value makes sense 
• Pay especially close attention to cards that convert resources to points as a player can win in one turn from as low as 6, 5, or even 4 points in very rare cases - with proper planning it should be easy to block these sorts of plays

Tips railroadink

2022-05-10T23:12:15Z

Fletcheese:

Try and pick a starting point, then head in one direction with roads, and in the other direction with railroads, to maximize points for longest highway/railroad. While most of your points will come from connecting exits, having one route run through the center is a good idea for additional points.

Remember you can let roads and railroads end on the side of the board, even when there is no exit. These do not count as a penalty.

Be smart about bridge use - this does not count as a connection between your road and railroad, but it does double dip in terms of points for longest road and railroad if placed well. When you do not have a good place, try to use it as a straight road/railroad along the edge as this mitigates the point loss to -1 instead of -2.

Don't forget to use your first special route by the end of the 5th round, as you only get 3 and can only use one per round. Ideally it should be one of the two railroad, two road junctions and be played early in the game to ensure your longest road and railroad are part of a single network. The best places for it are one of the center exits, one up from each exit in a corner, or in the actual center. Special routes should either be planned around explicitly or used in place of 3-way connectors that never come. Unless desperate in the last couple rounds, you should never throw a converter in the middle of your road/railroad. Converters should be placed at "in-betweener" exits to ensure your longest road/railroad can continue connecting exits uninterrupted. Use 3-way pieces in tandem with the converters to maintain one network.

A well-played game generally scores in the 60s: 36-45 from exits, 20-30 total between longest road and railroad, 3-9 for center, and negative 0-10 for broken ends. There is a lot of variation based on routes offered. High scoring rolls can get into the 70s or even low 80s.

Tips railroadink

2022-05-10T22:59:33Z

Fletcheese:

Try and pick a starting point, then head in one direction with roads, and in the other direction with railroads, to maximize points for longest highway/railroad. While most of your points will come from connecting exits, having one route run through the center is a good idea for additional points.

Remember you can let roads and railroads end on the side of the board, even when there is no exit. These do not count as a penalty.

Don't forget to use your first special route by the end of the 5th round, as you only get 3 and can only use one per round. Ideally it should be one of the two railroad, two road junctions and be played early in the game to ensure your longest road and railroad are part of a single network. The best places for it are one of the center exits, one up from each exit in a corner, or in the actual center. Special routes should either be planned around explicitly or used in place of 3-way connectors that never come. Unless desperate in the last couple rounds, you should never throw a converter in the middle of your road/railroad. Converters should be placed at "in-betweener" exits to ensure your longest road/railroad can continue connecting exit uninterrupted.

A well-played game generally scores in the 60s: 36-45 from exits, 20-30 total between longest road and railroad, 3-9 for center, and negative 3-7 for broken ends.

Tips littlefactory

2022-05-10T22:49:26Z

Fletcheese: Little Factory Strategy Tips

As a general rule of thumb, try to perform the action that increases your current net resource value by as much as possible. If you cannot increase your current net value, what trades can you make now to enable increasing your net value on coming turns? Work toward buildings that give you additional actions that you can frequently use. The buildings that turn wood into coal, clay into bricks, and stone into stone bricks are all hugely important for ramping into more buildings whereas buildings that cost tier 2 resources may only be usable once or twice the whole game. The scarcity of resources is actually very relevant. Keep count of what other players have been buying so you know what is likely to appear and so that you know which resources/buildings will still be available come your next turn.

Tips abyss

2022-05-10T19:51:41Z

Fletcheese: Abyss Strategy Tips

Abyss is a resource management game and success comes down to properly managing these resources which include:
<ul>
<li>Cards in hand</li>
<ul>
<li>More higher numbered cards of different colors = more lords you can buy</li>
<li>Card color flexibility is especially important when the court refreshes - you want to maximize your chances of taking advantage of the new lord pool</li>
<li>Explored 4 and 5 cost cards should almost always be purchased while 2 and 1 almost never. 3s are a toss-up depending on how many pearls each player has and how useful it is building toward the current lords in court</li>
<li>When spending cards, try to use either all high or all low number cards. Using one high number card with low numbered cards means a missed opportunity to affiliate extra points</li>
<li>Saving high numbered cards to auto-affiliate at the end of the game is perfectly viable</li>
</ul>
<li>Cards in council</li>
<ul>
<li>The council is perhaps the most novel aspect of Abyss and by extension the hardest to build intuition on</li>
<li>When cards are already in council exploring becomes a worse option as you risk a council stack becoming a more appealing option for your opponent's next turn</li>
<li>Choosing to take council cards rather than explore has many important implications:
<ul>
<li>Your opponent does not have the opportunity to buy a card - you can lock down a lord purchase by getting the final cards from council</li>
<li>Barring lord powers, you can only gain pearls by exploring. This can lead to a give and take where players alternate who is exploring</li>
<li>Generally speaking it is better to not be the one exploring because it gives the opponent first dibs at every card</li>
</ul>
</li>
</ul>
<li>Pearls
<ul>
<li>Pearls are not worth any points so as the game goes on they should be used more and more liberally</li>
<li>When your opponent has no pearls, exploring becomes much more appealing</li>
<li>Do not underestimate the value in spending pearls for buying lords. Purchasing a mono-color lord with pearls and a 4 or 5 card is very appealing as you can then affiliate that card</li>
<li>Spending a pearl to add a lord to court is very rarely a good decision but can come up</li>
</ul>
</li>
<li>Lords</li>
<ul>
<li>Active (key) lord powers can drastically warp the progression of a game. An exhaustive list is outside the scope of this guide</li>
<li>Some lord powers with others in interesting ways. Learning all the interactions can only come from playing games</li>
<li>Do not forget that getting a third key disables all of your keyed lords</li>
</ul>
<li>Points</li>
<ul>
<li>Like many similar games, the only resource that matters at the end is points</li>
<li>Points come from:
<ul>
<li>Lords
<ul>
<li>Key lords are generally better early, point lords are better late. Though it's important to consider that not all lords are created equal</li>
</ul></li>
<li>Locations
<ul>
<li>Depending on early key lord hits, it may be beneficial to delay your first location as much as possible. This has the added benefit of making a location choice working with as much information as possible</li>
<li>Generally speaking if none of the already revealed locations are worth more than about 10 points, you should reveal 4 locations. The added options for you far outweigh those for your opponent as you're often looking for the same locations anyway</li>
</ul></li>
<li>Affiliated Allies
<ul>
<li>You should be looking to score around 20 points off affiliated allies. Plan your card and lord purchases well to affiliate high value allies</li>
</ul></li>
<li>Monster Tokens
<ul>
<li>Do not underestimate Monster Tokens. In general whenever the monster track is at 2, you should fight it and take 2 tokens. Expected point value 6 is much better than a card</li>
</ul>
</li>
</ul>
</li>
</ul>
</ul>