Board Game Arena - User contributions [en]

Gamehelpmetromaniab

2015-10-30T15:21:43Z

Pikiou: Special rule for 2 players from v2 of the rulebook won't be implemented

== DESCRIPTION & OBJECTIVE ==

Each player represents a subway-building company,
and will dig two subway lines across the city.
The goal is to connect important destinations - residential
areas, commercial areas, and entertainment areas - and to
provide them with subway stations.
Take advantage of other players lines (for example, stations
are built wherever two lines meet ; you can win points at the
end by sharing the quickest trip), and try also to deroute or
even block off your opponents at the right time, to keep them
from well completing their lines!
At the end of the game, the city government will run seven
"test trips" between designated destinations, placed by the
players themselves during the game.
For each test trip, the fastest connection between the two
points will be rewarded with Public Utility Points, and the
player whose subways have the most points wins!

== GAME COMPONENTS & SET UP ==

'''Game Board'''
To set up the board, take the four border pieces and put
them together. Take the six triangular "city" pieces, and
arrange them randomly within the border.

'''Counters'''
Each player takes a set of counters of a particular color.
Each has a score marker (showing a subway train),
which is placed on the gameboard on the "0" space
of the scoring track.
Each player also has counters for two subway lines:
one with a solid color, and another with a "striped" color.
Each line should have a Start marker (white arrow),
an End marker (black arrow), and eighteen triangular
Tunnel counters.
There are also twelve Destination markers. Each is marked
with a letter (A-F), and is paired with another Destination
marker. These will be the destinations that will be "tested"
after the building phase is complete. The summary of these
tests is in the upright corner of the board.
Finally, there are thirty "station" markers, which are set by the
side of the board, and are not controlled by any player.
The map is made up of smaller triangles, which are either
blank, have a destination symbol, or a lake/park. Along the
edge of the city are white arrows indicating where a subway
line starts, and black arrows indicating where they exit the city

== THE COURSE OF THE GAME ==

'''Installation'''
Take the destination markers and shuffle them letter-sidedown.
With 4 players, each player takes one Residential, one
Commercial, and one Entertainment Destination at random.
That player then secretly looks at his markers. If two have
the same letter, he puts one back and draws a new one until
all three have different letters. When all the players have
their three Destination markers, they flip them letter-side-up
in front of them, visible for others.
With 3 players, each player takes one more Destination marker.
With 2 players, each player gets 6 Destination markers: one
player gets the Destinations A,B,C,D,E,F shown on the left of
the gameboard test Summary, the other player uses the ones
on the right.

'''Player turn'''
The most "urbane" player begins.
Play goes clockwise starting with the first player. On one's
turn, the player MUST do one and only one of the following:
- Dig 3 tunnels (to continue one or both of his lines) or
- Build an intermediate station (on one of his lines)

'''Starting a line'''
Each player has two subway lines.
On his first turn, a player must, of course, begin a subway
line - but only one!
A subway line must start from an empty space with a white
arrow along the edge of the city. To start a line, place its first
tunnel, topped with its "start" marker, in any of these spaces.
Then continue normally the line in the city by digging the
remaining tunnels.
When you will begin your second subway line at any subsequent
turn, it must start on one of the "opposite" edges from
where your first line began.

'''Digging tunnels'''
Subway lines are built in the city by placing Tunnels in the
triangular spaces. Only one tunnel may be placed in a space,
and must conform to the following:
- A line must always be built from its terminus; and never "branch off"
- A line may not be continued with an acute angle. EXCEPTION: when a line terminates at a station, it may be built out from that station at any angle, even acute.
- A line may never make a loop or double back on itself
If you choose to dig tunnels on your turn, you MUST place
3 tunnels (unless it is only possible to place fewer).
If you have two lines, you may distribute your 3 tunnels
between them as you wish.

'''Special areas'''
The start or end spaces (with an arrow) along the edges of
the city can only be used to start or end a line.
Tunnel counters may never be placed on the park or the lake.
When a player places a tunnel counter on top of a destination
area, the player must place immediatly one of his
Destination markers on that tunnel piece (of the appropriate
type, of course), letter-side up.
If a player does not have the appropriate marker, the player
may not place that tunnel piece on the destination.
Furthermore, each player may only place one destination
marker per turn, and two destinations of the same letter
cannot touch, either on an angle or on the side.

'''Stations'''
Most of the stations are created while digging tunnels.
A station is immediately placed when:
- The line being dug joins another line. In this case, a station is placed where the two lines meet up.
- The line, which was running alongside another line, splits off from it. In this case, a station is placed where the line splits off.
- When a line, running alongside another line, changes side, NO STATION is placed.
The player scores 1 point for each destination area on the
board that touches the station.
He continues to dig tunnels after placing a station, if he still
has some left to build. (i.e., building a station like this does
not stop your tunneling.)

'''Intermediate stations'''
In lieu of digging tunnels, a player may use all his turn to
place one station anywhere on one of his lines, between two
preexisting stations. A starting or ending marker counts as a
station for this purpose.
Points are scored as for stations placed while digging tunnels.

'''Ending lines'''
A line ends on a space with a black arrow. The player digs
his last tunnel on that space, topped with an "End Line"
counter.
A line may not end on the same edge as it started, nor on an
adjoining edge to that "start edge," unless all the end spaces
on the allowed sides are already taken.
When a line ends, that player may immediately place an
intermediate station anywhere on the line. However, once a
line is completed (with this bonus station), the player may
never place an intermediate station on that line again

'''End of the building phase'''
Players continue building until one of the following occurs:
- A player has completed both of his lines
- A player places the last station available
- Five lines are either completed, or blocked and unable to be completed
Note : a line is blocked if it can no longer be extended, typically
because all the spaces at its end are already occupied,
forbidden, or has run out of tunnels.
Then all other players have one last turn to play.
After, scoring begins.

== THE SCORING PHASE ==

'''Lines scoring'''
First, scores are adjusted as follows:
- Players who completed both of their lines lose no points.
- Players who completed only one line lose half their points (rounded down)
- Players who completed none of their lines lose all their points.
Adjust the scoring markers accordingly.

'''Test trip scoring'''
Each test trip runs between destination markers of the same
letter: A to A, then B to B, and so on. You can see the summary
of these trips in the upright corner of the board.
For each trip, determine the shortest route:
- a trip takes 1 minute to go from one station to another (no matter how many tunnel pieces are in between)
- and 3 minutes to change from one line to another.
A trip may have more than one fastest route.
Each player who has a line making up part of the fastest
route gets 3 points, plus a bonus of 3 points if he placed
one of the destination markers (i.e., if the marker is
on a tunnel piece of the player's color).
A player may only get points once for each test, even if the
player is involved in more than one route.
Players who are not involved in the fastest route never get
any point.

'''Impossible trips'''
Sometimes, a test run may be impossible.
If that is the case, a city investigation takes place to determine
the guilty party or parties:
- If the destination marker was never placed on the board, the guilty party is the player who didn't place the marker.
- If the marker was placed but nobody put a station touching it, the guilty party is the player who placed the destination.
- If the markers were both placed, but no route exists between the two, both players who placed the markers are guilty.
The guilty party or parties loose 6 points

'''Final test'''
The last test run is between the park and the lake. Determine
the fastest route, as always. Each player involved in the fastest
route gets 5 points.
Important note : if your score goes beyond 20 points, move
your marker normally, but place one of your tunnels near the
20 to show that. If your score goes below 0 point, place one
of your tunnels near the 0.

== THE WINNER ==

At the end of the game, the player with the most points is
crowned King of the Subway - i.e., WINS.
If there is a tie, the winner is the player who finished the
most lines; if there is again a tie, the winner is the player who
placed the most tunnels.
If there is still a tie, litigation is the only possible solution.

== SPECIAL RULES ==

Two players
End of game: 3 lines finished and/or blocked ends the building
phase. The other conditions still unchanged.
Test trip scoring: the second version of the rules on this topic is not implemented on BGA.

Three players
End of game: 4 lines finished and/or blocked ends the building
phase. The other conditions still unchanged.
Test trip scoring: same as with four players.

== VARIANTS ==

Unfair Municipality (3-4 players)
Each player keeps his destination markers letter-side-down
in front of him. The markers are only revealed when they are
placed on a destination area in the city.

No Corruption (3-4 players)
Ah, everything is straight and clear… Because each player
takes pre-etablished destination markers and keeps them in
front of him, letter-face-up, of course!

4 players
Player 1: A Residential, B Commercial, C Entertainment
Player 2: D Residential, A Commercial, E Entertainment
Player 3: F Residential, E Commercial, B Entertainment
Player 4: C Residential, D Commercial, F Entertainment

3 players :
Player 1: A & D Residential, B Commercial, C Entertainment
Player 2: C Residential, A & E Commercial, F Entertainment
Player 3: F Residential, D Commercial, B & E Entertainment

Metromania Official Rulebook, Spiel or Face

Your game state machine: states.inc.php

2014-08-22T04:23:22Z

Pikiou: /* args */ warning about the "args" method being called before the "action" method

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

Important: to understand the game state machine, the best is to read this presentation first:

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

== Overall structure ==

The machine states is described by a PHP associative array.

Example:

<pre>
$machinestates = array(

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

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

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

== Syntax ==

=== id ===

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

IDs must be positive integers.

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

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

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

Note²: You can't of course use the same ID twice.

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

=== name ===

(mandatory)

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

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

PHP example:
<pre>

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

</pre>

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

switch( stateName )
case 'myGameState':

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

break;
</pre>

=== type ===

(mandatory)

You can use 3 types of game states:
* activeplayer (1 player is active and must play)
* multipleactiveplayer (1..N players can be active and must play)
* game (no player is active. This is a transitional state to do something automatic specified by game rules)

=== description ===

(mandatory)

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

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

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

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

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

Example of custom field:
<pre>

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

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

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

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

=== descriptionmyturn ===

(mandatory for "activeplayer" and "multipleactiveplayer" game states type)

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

In general, we have this situation:

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

Note: you can use ${you} in description my turn in order the description can display "You" instead of the name of the player.

=== action ===

(mandatory for "game" game state type)

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

Example:
<pre>
In states.inc.php:
28 => array(
"name" => "startPlayerTurn",
"description" => '',
"type" => "game",
"action" => "stStartPlayerTurn",

In mygame.game.php:
function stStartPlayerTurn()
{
// ... do something at the beginning of this game state
</pre>

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

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

=== transitions ===

(mandatory)

With "transition" you specify in which game state you can jump from a given game state.

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

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

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

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

Note: if you have only 1 transition, you may give it an empty name.

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

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

=== possibleactions ===

(mandatory for "activeplayer" and "multipleactiveplayer" game states)

"possibleactions" defines the actions possible by the players at this game state.

By defining "possibleactions", you make sure players can't do actions that they are not allowed to do at this game states.

Example:

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

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

....

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

....

</pre>

=== args ===

(optional)

From time to time, it happens that you need some information on the client side (ie : for your game interface) only for a specific game state.

Example 1 : for Reversi, the list of possible moves during playerTurn state.
Example 2 : in Caylus, the number of remaining king's favor to choose in the state where the player is choosing a favor.
Example 3 : in Can't stop, the list of possible die combination to be displayed to the active player in order he can choose among them.

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

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

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

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

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

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

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

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

Note: you can also use values returned by your "args" method to have some custom values in your "description"/"descriptionmyturn" (see above).

Note: as a BGA convention, PHP methods called with "args" are prefixed by "arg" (ex: argPlayerTurn).

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

==== Private infos in args ====

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

This is although possible to specify that some data should be sent to some specific players only:

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

<pre>
function argPlayerTurn()
{
return array(
'_private' => array( // Using "_private" keyword, all data inside this array will be made private

'active' => array( // Using "active" keyword inside "_private", you select active player(s)
'somePrivateData' => self::getSomePrivateData() // will be send only to active player(s)
)
),

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

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

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

<pre>
function argPlayerTurn()
{
return array(
'_private' => array( // Using "_private" keyword, all data inside this array will be made private

<specific_player_id> => array( // you select one specific player with its id
'somePrivateData' => self::getSomePrivateData() // will be send only to <specific_player_id>
)
),

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

IMPORTANT: in certain situation (ex: multipleactiveplayer game state) these "private data" features can have a big performance impact. Please do not use if not needed.

=== updateGameProgression ===

(optional)

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

At least one of your game state (any of them) must specify updateGameProgression=>true.

Your game state machine: states.inc.php

2014-06-18T23:04:42Z

Pikiou: /* id */ potential crash on active games when ID is changed

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

Important: to understand the game state machine, the best is to read this presentation first:

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

== Overall structure ==

The machine states is described by a PHP associative array.

Example:

<pre>
$machinestates = array(

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

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

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

== Syntax ==

=== id ===

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

IDs must be positive integers.

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

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

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

Note²: You can't of course use the same ID twice.

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

=== name ===

(mandatory)

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

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

PHP example:
<pre>

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

</pre>

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

switch( stateName )
case 'myGameState':

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

break;
</pre>

=== type ===

(mandatory)

You can use 3 types of game states:
* activeplayer (1 player is active and must play)
* multipleactiveplayer (1..N players can be active and must play)
* game (no player is active. This is a transitional state to do something automatic specified by game rules)

=== description ===

(mandatory)

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

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

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

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

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

Example of custom field:
<pre>

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

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

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

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

=== descriptionmyturn ===

(mandatory for "activeplayer" and "multipleactiveplayer" game states type)

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

In general, we have this situation:

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

Note: you can use ${you} in description my turn in order the description can display "You" instead of the name of the player.

=== action ===

(mandatory for "game" game state type)

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

Example:
<pre>
In states.inc.php:
28 => array(
"name" => "startPlayerTurn",
"description" => '',
"type" => "game",
"action" => "stStartPlayerTurn",

In mygame.game.php:
function stStartPlayerTurn()
{
// ... do something at the beginning of this game state
</pre>

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

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

=== transitions ===

(mandatory)

With "transition" you specify in which game state you can jump from a given game state.

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

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

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

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

Note: if you have only 1 transition, you may give it an empty name.

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

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

=== possibleactions ===

(mandatory for "activeplayer" and "multipleactiveplayer" game states)

"possibleactions" defines the actions possible by the players at this game state.

By defining "possibleactions", you make sure players can't do actions that they are not allowed to do at this game states.

Example:

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

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

....

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

....

</pre>

=== args ===

(optional)

From time to time, it happens that you need some information on the client side (ie : for your game interface) only for a specific game state.

Example 1 : for Reversi, the list of possible moves during playerTurn state.
Example 2 : in Caylus, the number of remaining king's favor to choose in the state where the player is choosing a favor.
Example 3 : in Can't stop, the list of possible die combination to be displayed to the active player in order he can choose among them.

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

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

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

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

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

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

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

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

Note: you can also use values returned by your "args" method to have some custom values in your "description"/"descriptionmyturn" (see above).

Note: as a BGA convention, PHP methods called with "args" are prefixed by "arg" (ex: argPlayerTurn).

==== Private infos in args ====

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

This is although possible to specify that some data should be sent to some specific players only:

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

<pre>
function argPlayerTurn()
{
return array(
'_private' => array( // Using "_private" keyword, all data inside this array will be made private

'active' => array( // Using "active" keyword inside "_private", you select active player(s)
'somePrivateData' => self::getSomePrivateData() // will be send only to active player(s)
)
),

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

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

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

<pre>
function argPlayerTurn()
{
return array(
'_private' => array( // Using "_private" keyword, all data inside this array will be made private

<specific_player_id> => array( // you select one specific player with its id
'somePrivateData' => self::getSomePrivateData() // will be send only to <specific_player_id>
)
),

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

IMPORTANT: in certain situation (ex: multipleactiveplayer game state) these "private data" features can have a big performance impact. Please do not use if not needed.

=== updateGameProgression ===

(optional)

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

At least one of your game state (any of them) must specify updateGameProgression=>true.

Stock

2014-04-30T03:45:33Z

Pikiou: /* Complete stock component reference */

"Stock" is a javascript component that you can use on your game interface to display a set of elements of the same size that need to be arranged in one or several lines.

Stock is very flexible and is the most used component in BGA games.

Stock is used for example:
* To display set of cards, typically hands (ex: in Hearts, Seasons, The Boss, Race for the Galaxy, ...).
* To display items in player panels (ex: Takenoko, Amyitis, ...)
* ... in many other situations. For example, black dice and cubes on cards in Troyes are displayed with stock components.

Using stock:
* Your items are arranged nicely and sorted by type.
* When adding (or removing) items to the set. All items slide smoothly to their new position in the set to host the new one.
* Select/unselect items is a built-in functionnality.
* You don't have to care about inserting/removing HTML piece of code: the entire life of the stock is managed by the component.

== Using stock: a simple example ==

Let's have a look on how the stock is used in game "Hearts" to display a hand of standard cards.

At first, don't forget to add "ebg/stock" as a dependency:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE
],
</pre>

The stock is initialized in Javascript "setup" method like this:
<pre>
// Player hand
this.playerHand = new ebg.stock();
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

Explanations:
* We create a new stock object for the player hand.
* As parameters of the "create" method, we provide the width/height of an item (=a card), and the container div "myhand" - which is a simple void "div" element defines in our HTML template (.tpl).

Then, we must tell the stock what are the items it is going to display during its life: the 52 cards of a standard card game. Of course, we did not create 52 different images, but create a "CSS sprite" image named "cards.jpg" with all the cards arranged in 4 rows and 13 columns.

Here's how we tell stock what are the items type to display:
<pre>
// Explain there are 13 images per row in the CSS sprite image
this.playerHand.image_items_per_row = 13;

// Create cards types:
for( var color=1;color<=4;color++ )
{
for( var value=2;value<=14;value++ )
{
// Build card type id
var card_type_id = this.getCardUniqueId( color, value );
this.playerHand.addItemType( card_type_id, card_type_id, g_gamethemeurl+'img/cards.jpg', card_type_id );
}
}
</pre>

Explanations:
* At first, we tell the stock component that our CSS sprite contains 13 items per row. This way, it can find the correct image for each card type id.
* Then for the 4x13 cards, we call "addItemType" method that create the type. The arguments are the type id, the weight of the card (for sorting purpose), the URL of our CSS sprite, and the position of our card image in the CSS sprite.

Note: in this specific example we need to generate a unique ID for each type of card based on its color and value. This is the only purpose of "getCardUniqueId".

From now, if we need to add - for example - the 5 of Heart to player's hand, we can do this.
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ) );

In reality, cards have some IDs, which are useful to manipulate them. This is the reason we are using "addToStockWithId" instead:
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ), my_card_id );

If afterwards we want to remove this card from the stock:
this.playerHand.removeFromStockById( my_card_id );

== Complete stock component reference ==

'''create( page, container_div, item_width, item_height ):'''

With create, you create a new stock component.
Parameters:
* page: the container page. Usually: "this".
* container_div: the container "div" element (a void div element in your template, with an id).
* a stock item width and height, in pixels.

(See "Hearts" example above).

'''count():'''

Return the total number of items in the stock right now.

'''addItemType( type, weight, image, image_position ):'''

Define a new type of item to the stock.

This is mandatory to define a new item type before adding it to the stock. Example: if you want to have a stock control that can contains cubes of 3 different colors, you must add 3 item types (one for each color).

Parameters:
* type: ID of the type to add. You can choose any positive integer. All item types must have distinct IDs.
* weight: weight of items of this type. Weight value is used to sort items of the stock during the display. Note that you can specify the same weight for all items (in this case they are not sorted and their order might change randomly at any time).
* image: URL of item image. Most of the time, you will use a CSS sprite for stock item, so you have to specify CSS sprite image here.

Be careful: you must specify the image url as this:
<pre>
g_gamethemeurl+'img/yourimage.png'
</pre>
* image_position: if "image" specify the URL of a CSS sprite, you must specify the position of the item image in this CSS sprite. For example, if you have a CSS sprite with 3 cubes with a size of 20x20 pixels each (so your CSS image has for example a size of 20x60 or 60x20), you specify "0" for the first cube image, 1 for the second, 2 for the third.
Important: there are more than one line of items in your CSS sprite, you must specify how many items per line you have in your CSS sprite like this:
<pre>
// Specify that there is 10 image items per row in images used in "myStockObject" control.
this.myStockObject.image_items_per_row = 10;
</pre>

'''addToStock( type, from )'''

Add an item to the stock, with the specified type.

To make your life easy, in most of the case we suggest you to use "addToStockWithId" in order to give an ID to the item added. "addToStock" is perfect when you are using a stock controls with items that are generic game material that does not need to be addressed individually (ex: a bunch of money tokens).

Parameters:
* type: ID of the item type to use (as specified in "addItemType")
* from: OPTIONNAL: if you specify a HTML item here, the item will appear on this item and will be slided to its position on the stock item.

Example:
<pre>
// Add a money token to the "player money" stock.
// The money token will appear on "player_id" player panel and will move to its position.
this.playerMoney.addToStock( MONEY_TOKEN, 'overall_player_board_'+player_id );
</pre>

Important: for a given stock control, you must use either addToStock or addToStockWithId, but NEVER BOTH OF THEM.

'''addToStockWithId( type, id, from )'''

This is exactly the same method than "addToStock", except that you associate an ID to the newly created item.

This is especially useful:
* When you need to know which item(s) has been selected by the user (see "getSelectedItems").
* When you need to remove a specific item from the stock with "removeFromStockById"

Important: for a given stock control, you must use either addToStock or addToStockWithId, but NEVER BOTH OF THEM.

'''removeFromStock( type, to )'''

Remove an item of the specific type from the stock.

"to" is an optional parameter. If "to" contains the ID of an HTML element, the item removed from the stock is slided to this HTML element before it disappear.

'''removeFromStockById( id, to )'''

Remove an item with a specific ID from the stock.

"to" is an optional parameter. If "to" contains the ID of an HTML element, the item removed from the stock is slided to this HTML element before it disappear.

'''removeAll()'''

Remove all items from the stock.

'''getPresentTypeList()'''

Return an array with all the types of items present in the stock right now.

Example:
<pre>
this.myStockControl.removeAll();
this.myStockControl.addToStock( 65 );
this.myStockControl.addToStock( 34 );
this.myStockControl.addToStock( 89 );
this.myStockControl.addToStock( 65 );

// The following returns: { 34:1, 65:1, 89:1 }
var item_types = this.myStockControl.getPresentTypeList();
</pre>

'''resetItemsPosition()'''

If you moved an item from the stock control manually (ex: after a drag'n'drop) and want to reset their position to their original ones, you can call this method.

'''item_margin'''

By default, there is a margin of 5px between the items of a stock. You can change the member variable "item_margin" to change this.

Example:
<pre>
this.myStockControl.item_margin=5;
</pre>

'''changeItemsWeight( newWeights )'''

With this method you can change dynamically the weight of the item types in a stock control.

Items are immediately re-sorted with the new weight.

Example: with a stock control that contains classic cards, you can order them by value or by color. Using changeItemsWeight you can switch from one sort method to another when a player request this.

newWeights is an associative array: item type id => new weight.

Example:
<pre>
// Item type 1 gets a new weight of 10, 2 a new weight of 20, 3 a new weight of 30.
this.myStockControl.changeItemsWeight( { 1: 10, 2: 20, 3: 30 } );
</pre>

'''setSelectionMode( mode )'''

For each stock control, you can specify a selection mode:
* 0: no item can be selected by the player.
* 1: a maximum of one item can be selected by the player at the same time.
* 2: several items can be selected by the player at the same time.

'''setSelectionAppearance( type )'''

For each stock control, you can specify a selection highlighting type:
* 'border': there will be a red border around selected items (this is the default). The attribute 'apparenceBorderWidth' can be used to manage the width of the border (in pixels).
* 'disappear': the selected item will fade out and disappear. This is useful when the selection has the effect of destroying the item.
* 'class': there will be an extra 'stockitem_selecte' css class added to the element when it is selected (and removed when unselected). You can override this class in the css file for your game.

By default this class definition is:
<pre>
.stockitem_selected {
border: 2px solid red ! important;
}
</pre>

If you want to override it for example to change the border color add this in your <game>.css file:
<pre>
.stockitem_selected {
border: 2px solid orange ! important;
}
</pre>

NB: the 'class' highlighting type has not yet been deployed on the studio - 24/02/2014. This warning will be removed after the next upgrade.

'''isSelected( id )'''

Return true/false wether the specified item id has been selected or not.

'''selectItem( id )'''

Select the specified item.

'''unselectItem( id )'''

Unselect the specified item.

'''unselectAll()'''

Unselect all items of the stock.

'''onChangeSelection'''

This callback method is called when the player select/unselect an item of the stock.

You can connect this to one of your method like this:
<pre>
dojo.connect( this.myStockControl, 'onChangeSelection', this, 'onMyMethodToCall' );

(...)

onMyMethodToCall: function( control_name )
{
// This method is called when myStockControl selected items changed
var items = this.myStockControl.getSelectedItems();

// (do something)
},
</pre>

Note: The "control_name" argument is the ID (the "DOM" id) of the "div" container of your stock control. Using "control_name", you can use the same callback method for different Stock control and see which one trigger the method.

'''getSelectedItems()'''

Return the list of selected items, as an array with the following format:
<pre>
[
{ type:1, id: 1001 },
{ type:1, id: 1002 },
{ type:3, id: 1003 }
...
]
</pre>

'''getUnselectedItems()'''

Same as the previous one, but return unselected item instead of seleted ones.

'''getAllItems()'''

Get all items (same format than getSelectedItems and getUnselectedItems).

'''setOverlap( horizontal_percent, vertical_percent )'''

Make items on the stock control "overlap" on each other, to save space.

By default, horizontal_overlap and vertical_overlap are 0.

When horizontal_overlap=20, it means that a stock item must overlap on 20% of the width of the previous item. horizontal_overlap can't be over 100.

vertical_overlap works differently: one items on two are shifted up.

See "Jaipur" game to see an example to use of this function.

'''onItemCreate'''

Using onItemCreate, you can trigger a method each time a new item is added to the Stock, in order you can customize it.

Complete example:
<pre>
// During "setup" phase, we associate our method "setupNewCard" with the creation of a new stock item:
this.myStockItem.onItemCreate = dojo.hitch( this, 'setupNewCard' );

(...)

// And here is our "setupNewCard":
setupNewCard: function( card_div, card_type_id, card_id )
{
// Add a special tooltip on the card:
this.addTooltip( card_div.id, _("Some nice tooltip for this item"), '' );

// Note that "card_type_id" contains the type of the item, so you can do special actions depending on the item type

// Add some custom HTML content INSIDE the Stock item:
dojo.place( this.format_block( 'jstpl_my_card_content', {
....
} ), card_div.id );
}

</pre>

== Tips when adding/removing items to/from Stock components ==

The usual way is the following:

'''Situation A''':

When you add a card to a stock item, and this card is '''not''' coming from another stock: use "addToStockWithId" with a "from" argument set to the element of your interface where card should come from.

'''Situation B''':

When you add a card to a stock item, and this card is coming from another stock:
* on the destination Stock, use "addToStockWithId" with a "from" equals to the HTML id of the corresponding item in the source Stock. For example, If the source stock id is "myHand", then the HTML id of card 48 is "myHand_item_48".
* then, remove the source item with "removeFromStockById".
(note that it's important to do things in this order, because source item must still exists when you use it as the origin of the slide).

'''Situation C''':

When you move a card from a stock item to something that is not a stock item:
* insert the card as a classic HTML template (dojo.place / this.format_block).
* place it on the Stock item with "this.placeOnObject", using Stock item HTML id (see above).
* slide it to its new position with "this.slideToObject"
* remove the card from the Stock item with "removeFromStockById".

Using the methods above, your cards should slide to, from and between your Stock controls smoothly

Stock

2014-02-19T21:10:34Z

Pikiou: /* Complete stock component reference */

"Stock" is a javascript component that you can use on your game interface to display a set of elements of the same size that need to be arranged in one or several lines.

Stock is very flexible and is the most used component in BGA games.

Stock is used for example:
* To display set of cards, typically hands (ex: in Hearts, Seasons, The Boss, Race for the Galaxy, ...).
* To display items in player panels (ex: Takenoko, Amyitis, ...)
* ... in many other situations. For example, black dice and cubes on cards in Troyes are displayed with stock components.

Using stock:
* Your items are arranged nicely and sorted by type.
* When adding (or removing) items to the set. All items slide smoothly to their new position in the set to host the new one.
* Select/unselect items is a built-in functionnality.
* You don't have to care about inserting/removing HTML piece of code: the entire life of the stock is managed by the component.

== Using stock: a simple example ==

Let's have a look on how the stock is used in game "Hearts" to display a hand of standard cards.

At first, don't forget to add "ebg/stock" as a dependency:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE
],
</pre>

The stock is initialized in Javascript "setup" method like this:
<pre>
// Player hand
this.playerHand = new ebg.stock();
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

Explanations:
* We create a new stock object for the player hand.
* As parameters of the "create" method, we provide the width/height of an item (=a card), and the container div "myhand" - which is a simple void "div" element defines in our HTML template (.tpl).

Then, we must tell the stock what are the items it is going to display during its life: the 52 cards of a standard card game. Of course, we did not create 52 different images, but create a "CSS sprite" image named "cards.jpg" with all the cards arranged in 4 rows and 13 columns.

Here's how we tell stock what are the items type to display:
<pre>
// Explain there are 13 images per row in the CSS sprite image
this.playerHand.image_items_per_row = 13;

// Create cards types:
for( var color=1;color<=4;color++ )
{
for( var value=2;value<=14;value++ )
{
// Build card type id
var card_type_id = this.getCardUniqueId( color, value );
this.playerHand.addItemType( card_type_id, card_type_id, g_gamethemeurl+'img/cards.jpg', card_type_id );
}
}
</pre>

Explanations:
* At first, we tell the stock component that our CSS sprite contains 13 items per row. This way, it can find the correct image for each card type id.
* Then for the 4x13 cards, we call "addItemType" method that create the type. The arguments are the type id, the weight of the card (for sorting purpose), the URL of our CSS sprite, and the position of our card image in the CSS sprite.

Note: in this specific example we need to generate a unique ID for each type of card based on its color and value. This is the only purpose of "getCardUniqueId".

From now, if we need to add - for example - the 5 of Heart to player's hand, we can do this.
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ) );

In reality, cards have some IDs, which are useful to manipulate them. This is the reason we are using "addToStockWithId" instead:
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ), my_card_id );

If afterwards we want to remove this card from the stock:
this.playerHand.removeFromStockById( my_card_id );

== Complete stock component reference ==

'''create( page, container_div, item_width, item_height ):'''

With create, you create a new stock component.
Parameters:
* page: the container page. Usually: "this".
* container_div: the container "<div>" element (a void <div> element in your template, with an id).
* a stock item width and height, in pixels.

(See "Hearts" example above).

'''count():'''

Return the total number of items in the stock right now.

'''addItemType( type, weight, image, image_position ):'''

Define a new type of item to the stock.

This is mandatory to define a new item type before adding it to the stock. Example: if you want to have a stock control that can contains cubes of 3 different colors, you must add 3 item types (one for each color).

Parameters:
* type: ID of the type to add. You can choose any positive integer. All item types must have distinct IDs.
* weight: weight of items of this type. Weight value is used to sort items of the stock during the display. Note that you can specify the same weight for all items (in this case they are not sorted and their order might change randomly at any time).
* image: URL of item image. Most of the time, you will use a CSS sprite for stock item, so you have to specify CSS sprite image here.

Be careful: you must specify the image url as this:
<pre>
g_gamethemeurl+'img/yourimage.png'
</pre>
* image_position: if "image" specify the URL of a CSS sprite, you must specify the position of the item image in this CSS sprite. For example, if you have a CSS sprite with 3 cubes with a size of 20x20 pixels each (so your CSS image has for example a size of 20x60 or 60x20), you specify "0" for the first cube image, 1 for the second, 2 for the third.
Important: there are more than one line of items in your CSS sprite, you must specify how many items per line you have in your CSS sprite like this:
<pre>
// Specify that there is 10 image items per row in images used in "myStockObject" control.
this.myStockObject.image_items_per_row = 10;
</pre>

'''addToStock( type, from )'''

Add an item to the stock, with the specified type.

To make your life easy, in most of the case we suggest you to use "addToStockWithId" in order to give an ID to the item added. "addToStock" is perfect when you are using a stock controls with items that are generic game material that does not need to be addressed individually (ex: a bunch of money tokens).

Parameters:
* type: ID of the item type to use (as specified in "addItemType")
* from: OPTIONNAL: if you specify a HTML item here, the item will appear on this item and will be slided to its position on the stock item.

Example:
<pre>
// Add a money token to the "player money" stock.
// The money token will appear on "player_id" player panel and will move to its position.
this.playerMoney.addToStock( MONEY_TOKEN, 'overall_player_board_'+player_id );
</pre>

Important: for a given stock control, you must use either addToStock or addToStockWithId, but NEVER BOTH OF THEM.

'''addToStockWithId( type, id, from )'''

This is exactly the same method than "addToStock", except that you associate an ID to the newly created item.

This is especially useful:
* When you need to know which item(s) has been selected by the user (see "getSelectedItems").
* When you need to remove a specific item from the stock with "removeFromStockById"

Important: for a given stock control, you must use either addToStock or addToStockWithId, but NEVER BOTH OF THEM.

'''removeFromStock( type, to )'''

Remove an item of the specific type from the stock.

"to" is an optional parameter. If "to" contains the ID of an HTML element, the item removed from the stock is slided to this HTML element before it disappear.

'''removeFromStockById( id, to )'''

Remove an item with a specific ID from the stock.

"to" is an optional parameter. If "to" contains the ID of an HTML element, the item removed from the stock is slided to this HTML element before it disappear.

'''removeAll()'''

Remove all items from the stock.

'''getPresentTypeList()'''

Return an array with all the types of items present in the stock right now.

Example:
<pre>
this.myStockControl.removeAll();
this.myStockControl.addToStock( 65 );
this.myStockControl.addToStock( 34 );
this.myStockControl.addToStock( 89 );
this.myStockControl.addToStock( 65 );

// The following returns: { 34:1, 65:1, 89:1 }
var item_types = this.myStockControl.getPresentTypeList();
</pre>

'''resetItemsPosition()'''

If you moved an item from the stock control manually (ex: after a drag'n'drop) and want to reset their position to their original ones, you can call this method.

'''item_margin'''

By default, there is a margin of 5px between the items of a stock. You can change the member variable "item_margin" to change this.

Example:
<pre>
this.myStockControl.item_margin=5;
</pre>

'''changeItemsWeight( newWeights )'''

With this method you can change dynamically the weight of the item types in a stock control.

Items are immediately re-sorted with the new weight.

Example: with a stock control that contains classic cards, you can order them by value or by color. Using changeItemsWeight you can switch from one sort method to another when a player request this.

newWeights is an associative array: item type id => new weight.

Example:
<pre>
// Item type 1 gets a new weight of 10, 2 a new weight of 20, 3 a new weight of 30.
this.myStockControl.changeItemsWeight( { 1: 10, 2: 20, 3: 30 } );
</pre>

'''setSelectionMode( mode )'''

For each stock control, you can specify a selection mode:
* 0: no item can be selected by the player.
* 1: a maximum of one item can be selected by the player at the same time.
* 2: several items can be selected by the player at the same time.

'''isSelected( id )'''

Return true/false wether the specified item id has been selected or not.

'''selectItem( id )'''

Select the specified item.

'''unselectItem( id )'''

Unselect the specified item.

'''unselectAll()'''

Unselect all items of the stock.

'''onChangeSelection'''

This callback method is called when the player select/unselect an item of the stock.

You can connect this to one of your method like this:
<pre>
dojo.connect( this.myStockControl, 'onChangeSelection', this, 'onMyMethodToCall' );

(...)

onMyMethodToCall: function( control_name )
{
// This method is called when myStockControl selected items changed
var items = this.myStockControl.getSelectedItems();

// (do something)
},
</pre>

Note: The "control_name" argument is the ID (the "DOM" id) of the <div> container of your stock control. Using "control_name", you can use the same callback method for different Stock control and see which one trigger the method.

'''getSelectedItems()'''

Return the list of selected items, as an array with the following format:
<pre>
[
{ type:1, id: 1001 },
{ type:1, id: 1002 },
{ type:3, id: 1003 }
...
]
</pre>

'''getUnselectedItems()'''

Same as the previous one, but return unselected item instead of seleted ones.

'''getAllItems()'''

Get all items (same format than getSelectedItems and getUnselectedItems).

'''setOverlap( horizontal_percent, vertical_percent )'''

Make items on the stock control "overlap" on each other, to save space.

By default, horizontal_overlap and vertical_overlap are 0.

When horizontal_overlap=20, it means that a stock item must overlap on 20% of the width of the previous item. horizontal_overlap can't be over 100.

vertical_overlap works differently: one items on two are shifted up.

See "Jaipur" game to see an example to use of this function.

'''onItemCreate'''

Using onItemCreate, you can trigger a method each time a new item is added to the Stock, in order you can customize it.

Complete example:
<pre>
// During "setup" phase, we associate our method "setupNewCard" with the creation of a new stock item:
this.myStockItem.onItemCreate = dojo.hitch( this, 'setupNewCard' );

(...)

// And here is our "setupNewCard":
setupNewCard: function( card_div, card_type_id, card_id )
{
// Add a special tooltip on the card:
this.addTooltip( card_div.id, _("Some nice tooltip for this item"), '' );

// Note that "card_type_id" contains the type of the item, so you can do special actions depending on the item type

// Add some custom HTML content INSIDE the Stock item:
dojo.place( this.format_block( 'jstpl_my_card_content', {
....
} ), card_div.id );
}

</pre>

== Tips when adding/removing items to/from Stock components ==

The usual way is the following:

'''Situation A''':

When you add a card to a stock item, and this card is '''not''' coming from another stock: use "addToStockWithId" with a "from" argument set to the element of your interface where card should come from.

'''Situation B''':

When you add a card to a stock item, and this card is coming from another stock:
* on the destination Stock, use "addToStockWithId" with a "from" equals to the HTML id of the corresponding item in the source Stock. For example, If the source stock id is "myHand", then the HTML id of card 48 is "myHand_item_48".
* then, remove the source item with "removeFromStockById".
(note that it's important to do things in this order, because source item must still exists when you use it as the origin of the slide).

'''Situation C''':

When you move a card from a stock item to something that is not a stock item:
* insert the card as a classic HTML template (dojo.place / this.format_block).
* place it on the Stock item with "this.placeOnObject", using Stock item HTML id (see above).
* slide it to its new position with "this.slideToObject"
* remove the card from the Stock item with "removeFromStockById".

Using the methods above, your cards should slided to, from and between your Stock controls smoothly

Gamehelptournay

2014-02-04T15:31:51Z

Pikiou: No rules were added, so I took the opportunity to thank Nosnhoj Kräm ^^

Thanks to Nosnhoj Kräm (Eeeville) for his Tournay card descriptions used in the BGA adaptation!

Gamehelpgearnpiston

2013-04-19T13:20:28Z

Pikiou: Introduction sentence

It is 1888, and everywhere you turn, people are talking about the horseless carriage. The players build an automobile prototype by patenting new parts, scavenging in the junk yard, and looking for opportunities to trip up their fellow automotive pioneers, all the while seeking to impress investors that are looking to get into car production. Gear & Piston is a simple, yet engaging 30-60 minute game for 2-6 players, and is [http://www.kickstarter.com/projects/ludicreations/gear-and-piston-board-game now on Kickstarter].
===QUICK RULES REFERENCE===
====ROUND SEQUENCE AND PHASES====
*I. Plan actions.
*II. Resolve actions.
*III. Refresh Patent Office and Junk Yard.
====LOCATION ACTIONS====
*Back Alley: Choose 1 action from the following. The Action Token placed in the Back Alley cannot be used during the next planning phase.
**Black Market (draw 3 New Parts and keep 1),
**Espionage (steal a part from another player),
**or Union Muscle (move Action Token ahead or behind in a location).
*Patent Office: Take 1 New Part, either from the parts next to the game or from the New Parts stack.
*Junk Yard: Take up to 2 Junk Parts, either from the parts next to the game or from the New Parts stack.
*Workshop: Actions that may be used are Build, Dismantle, and Upgrade.
====REQUIREMENTS OF A COMPLETE AUTOMOBILE====
* Each automobile requires a Motor, Fuel supply for each Motor, Steering, Gear and two Axles.
* Each type of part (electric, gasoline, steam) requires a Motor and Supply of same type.
* Each part on the top row requires a part on the bottom row and vice versa.
* Each Axle supports only the five parts surrounding it.
====GAME END====
*There are not enough tiles to refill a location from the refill Stack.
OR
*One of the players has a complete automobile with at least twelve parts on it.
====SCORING====
* VP according to Investors
* +1 VP for each part in one largest continuous area
* -1 VP for each point of Volatility

Gamehelpgearnpiston

2013-04-19T13:18:14Z

Pikiou: Smaller titles

===QUICK RULES REFERENCE===
====ROUND SEQUENCE AND PHASES====
*I. Plan actions.
*II. Resolve actions.
*III. Refresh Patent Office and Junk Yard.
====LOCATION ACTIONS====
*Back Alley: Choose 1 action from the following. The Action Token placed in the Back Alley cannot be used during the next planning phase.
**Black Market (draw 3 New Parts and keep 1),
**Espionage (steal a part from another player),
**or Union Muscle (move Action Token ahead or behind in a location).
*Patent Office: Take 1 New Part, either from the parts next to the game or from the New Parts stack.
*Junk Yard: Take up to 2 Junk Parts, either from the parts next to the game or from the New Parts stack.
*Workshop: Actions that may be used are Build, Dismantle, and Upgrade.
====REQUIREMENTS OF A COMPLETE AUTOMOBILE====
* Each automobile requires a Motor, Fuel supply for each Motor, Steering, Gear and two Axles.
* Each type of part (electric, gasoline, steam) requires a Motor and Supply of same type.
* Each part on the top row requires a part on the bottom row and vice versa.
* Each Axle supports only the five parts surrounding it.
====GAME END====
*There are not enough tiles to refill a location from the refill Stack.
OR
*One of the players has a complete automobile with at least twelve parts on it.
====SCORING====
* VP according to Investors
* +1 VP for each part in one largest continuous area
* -1 VP for each point of Volatility

Gamehelpgearnpiston

2013-04-19T13:01:05Z

Pikiou: Created page with "=QUICK RULES REFERENCE= ==ROUND SEQUENCE AND PHASES== *I. Plan actions. *II. Resolve actions. *III. Refresh Patent Office and Junk Yard. ==LOCATION ACTIONS== *Back Alley: Choo..."

=QUICK RULES REFERENCE=
==ROUND SEQUENCE AND PHASES==
*I. Plan actions.
*II. Resolve actions.
*III. Refresh Patent Office and Junk Yard.
==LOCATION ACTIONS==
*Back Alley: Choose 1 action from the following. The Action Token placed in the Back Alley cannot be used during the next planning phase.
**Black Market (draw 3 New Parts and keep 1),
**Espionage (steal a part from another player),
**or Union Muscle (move Action Token ahead or behind in a location).
*Patent Office: Take 1 New Part, either from the parts next to the game or from the New Parts stack.
*Junk Yard: Take up to 2 Junk Parts, either from the parts next to the game or from the New Parts stack.
*Workshop: Actions that may be used are Build, Dismantle, and Upgrade.
==REQUIREMENTS OF A COMPLETE AUTOMOBILE==
* Each automobile requires a Motor, Fuel supply for each Motor, Steering, Gear and two Axles.
* Each type of part (electric, gasoline, steam) requires a Motor and Supply of same type.
* Each part on the top row requires a part on the bottom row and vice versa.
* Each Axle supports only the five parts surrounding it.
==GAME END==
*There are not enough tiles to refill a location from the refill Stack.
OR
*One of the players has a complete automobile with at least twelve parts on it.
==SCORING==
* VP according to Investors
* +1 VP for each part in one largest continuous area
* -1 VP for each point of Volatility

Your game state machine: states.inc.php

2013-04-05T02:46:37Z

Pikiou: /* args */ returned value from the arg function must be an associative array

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

Important: to understand the game state machine, the best is to read this presentation first:

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

== Overall structure ==

The machine states is described by a PHP associative array.

Example:

<pre>
$machinestates = array(

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

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

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

== Syntax ==

=== id ===

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

IDs must be positive integers.

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

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

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

Note²: You can't of course use the same ID twice.

=== name ===

(mandatory)

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

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

PHP example:
<pre>

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

</pre>

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

switch( stateName )
case 'myGameState':

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

break;
</pre>

=== type ===

(mandatory)

You can use 3 types of game states:
* activeplayer (1 player is active and must play)
* multipleactiveplayer (1..N players can be active and must play)
* game (no player is active. This is a transitional state to do something automatic specified by game rules)

=== description ===

(mandatory)

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

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

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

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

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

Example of custom field:
<pre>

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

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

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

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

=== descriptionmyturn ===

(mandatory for "activeplayer" and "multipleactiveplayer" game states type)

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

In general, we have this situation:

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

Note: you can use ${you} in description my turn in order the description can display "You" instead of the name of the player.

=== action ===

(mandatory for "game" game state type)

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

Example:
<pre>
In states.inc.php:
28 => array(
"name" => "startPlayerTurn",
"description" => '',
"type" => "game",
"action" => "stStartPlayerTurn",

In mygame.game.php:
function stStartPlayerTurn()
{
// ... do something at the beginning of this game state
</pre>

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

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

=== transitions ===

(mandatory)

With "transition" you specify in which game state you can jump from a given game state.

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

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

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

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

Note: if you have only 1 transition, you may give it an empty name.

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

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

=== possibleactions ===

(mandatory for "activeplayer" and "multipleactiveplayer" game states)

"possibleactions" defines the actions possible by the players at this game state.

By defining "possibleactions", you make sure players can't do actions that they are not allowed to do at this game states.

Example:

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

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

....

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

....

</pre>

=== args ===

(optional)

From time to time, it happens that you need some information on the client side (ie : for your game interface) only for a specific game state.

Example 1 : for Reversi, the list of possible moves during playerTurn state.
Example 2 : in Caylus, the number of remaining king's favor to choose in the state where the player is choosing a favor.
Example 3 : in Can't stop, the list of possible die combination to be displayed to the active player in order he can choose among them.

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

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

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

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

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

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

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

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

Note: you can also used values returned by your "args" method to have some custom values in your "description"/"descriptionmyturn" (see above).

Note: as a BGA convention, PHP methods called with "args" are prefixed by "arg" (ex: argPlayerTurn).

=== updateGameProgression ===

(optional)

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

At least one of your game state (any of them) must specify updateGameProgression=>true.

Stock

2013-01-26T04:58:23Z

Pikiou: /* Complete stock component reference */

"Stock" is a javascript component that you can use on your game interface to display a set of elements of the same size that need to be arranged in one or several lines.

Stock is very flexible and is the most used component in BGA games.

Stock is used for example:
* To display set of cards, typically hands (ex: in Hearts, Seasons, The Boss, Race for the Galaxy, ...).
* To display items in player panels (ex: Takenoko, Amyitis, ...)
* ... in many other situations. For example, black dice and cubes on cards in Troyes are displayed with stock components.

Using stock:
* Your items are arranged nicely and sorted by type.
* When adding (or removing) items to the set. All items slide smoothly to their new position in the set to host the new one.
* Select/unselect items is a built-in functionnality.
* You don't have to care about inserting/removing HTML piece of code: the entire life of the stock is managed by the component.

== Using stock: a simple example ==

Let's have a look on how the stock is used in game "Hearts" to display a hand of standard cards.

The stock is initialized in Javascript "setup" method like this:
<pre>
// Player hand
this.playerHand = new ebg.stock();
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

Explanations:
* We create a new stock object for the player hand.
* As parameters of the "create" method, we provide the width/height of an item (=a card), and the container div "myhand" - which is a simple void "div" element defines in our HTML template (.tpl).

Then, we must tell the stock what are the items it is going to display during its life: the 52 cards of a standard card game. Of course, we did not create 52 different images, but create a "CSS sprite" image named "cards.jpg" with all the cards arranged in 4 rows and 13 columns.

Here's how we tell stock what are the items type to display:
<pre>
// Explain there are 13 images per row in the CSS sprite image
this.playerHand.image_items_per_row = 13;

// Create cards types:
for( var color=1;color<=4;color++ )
{
for( var value=2;value<=14;value++ )
{
// Build card type id
var card_type_id = this.getCardUniqueId( color, value );
this.playerHand.addItemType( card_type_id, card_type_id, g_themeurl+'img/hearts/cards.jpg', card_type_id );
}
}
</pre>

Explanations:
* At first, we tell the stock component that our CSS sprite contains 13 items per row. This way, it can find the correct image for each card type id.
* Then for the 4x13 cards, we call "addItemType" method that create the type. The arguments are the type id, the weight of the card (for sorting purpose), the URL of our CSS sprite, and the position of our card image in the CSS sprite.

Note: in this specific example we need to generate a unique ID for each type of card based on its color and value. This is the only purpose of "getCardUniqueId".

From now, if we need to add - for example - the 5 of Heart to player's hand, we can do this.
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ) );

In reality, cards have some IDs, which are useful to manipulate them. This is the reason we are using "addToStockWithId" instead:
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ), my_card_id );

If afterwards we want to remove this card from the stock:
this.playerHand.removeFromStockById( my_card_id );

== Complete stock component reference ==

'''create( page, container_div, item_width, item_height ):'''

With create, you create a new stock component.
Parameters:
* page: the container page. Usually: "this".
* container_div: the container "<div>" element (a void <div> element in your template, with an id).
* a stock item width and height, in pixels.

(See "Hearts" example above).

'''count():'''

Return the total number of items in the stock right now.

'''addItemType( type, weight, image, image_position ):'''

Define a new type of item to the stock.

This is mandatory to define a new item type before adding it to the stock. Example: if you want to have a stock control that can contains cubes of 3 different colors, you must add 3 item types (one for each color).

Parameters:
_ type: ID of the type to add. You can choose any positive integer. All item types must have distinct IDs.
_ weight: weight of items of this type. Weight value is used to sort items of the stock during the display. Note that you can specify the same weight for all items (in this case they are not sorted).
_ image: URL of item image. Most of the time, you will use a CSS sprite for stock item, so you have to specify CSS sprite image here.
Be careful: you must specify the image url as this:
<pre>
g_themeurl+'img/your_game_name/yourimage.png'
</pre>
_ image_position: if "image" specify the URL of a CSS sprite, you must specify the position of the item image in this CSS sprite. For example, if you have a CSS sprite with 3 cubes with a size of 20x20 pixels each (so your CSS image has for example a size of 20x60 or 60x20), you specify "0" for the first cube image, 1 for the second, 2 for the third.
Important: there are more than one line of items in your CSS sprite, you must specify how many items per line you have in your CSS sprite like this:
<pre>
// Specify that there is 10 image items per row in images used in "myStockObject" control.
this.myStockObject.image_items_per_row = 10;
</pre>

'''addToStock( type, from )'''

Add an item to the stock, with the specified type.

To make your life easy, in most of the case we suggest you to use "addToStockWithId" in order to give an ID to the item added. "addToStock" is perfect when you are using a stock controls with items that are generic game material that does not need to be addressed individually (ex: a bunch of money tokens).

Parameters:
* type: ID of the item type to use (as specified in "addItemType")
* from: OPTIONNAL: if you specify a HTML item here, the item will appear on this item and will be slided to its position on the stock item.

Example:
<pre>
// Add a money token to the "player money" stock.
// The money token will appear on "player_id" player panel and will move to its position.
this.playerMoney.addToStock( MONEY_TOKEN, 'overall_player_board_'+player_id );
</pre>

Important: for a given stock control, you must use either addToStock or addToStockWithId, but NEVER BOTH OF THEM.

'''addToStockWithId( type, id, from )'''

This is exactly the same method than "addToStock", except that you associate an ID to the newly created item.

This is especially useful:
* When you need to know which item(s) has been selected by the user (see "getSelectedItems").
* When you need to remove a specific item from the stock with "removeFromStockById"

Important: for a given stock control, you must use either addToStock or addToStockWithId, but NEVER BOTH OF THEM.

'''removeFromStock( type, to )'''

Remove an item of the specific type from the stock.

"to" is an optional parameter. If "to" contains the ID of an HTML element, the item removed from the stock is slided to this HTML element before it disappear.

'''removeFromStockById( id, to )'''

Remove an item with a specific ID from the stock.

"to" is an optional parameter. If "to" contains the ID of an HTML element, the item removed from the stock is slided to this HTML element before it disappear.

'''removeAll()'''

Remove all items from the stock.

'''getPresentTypeList()'''

Return an array with all the types of items present in the stock right now.

Example:
<pre>
this.myStockControl.removeAll();
this.myStockControl.addToStock( 65 );
this.myStockControl.addToStock( 34 );
this.myStockControl.addToStock( 89 );
this.myStockControl.addToStock( 65 );

// The following returns: { 34:1, 65:1, 89:1 }
var item_types = this.myStockControl.getPresentTypeList();
</pre>

'''resetItemsPosition()'''

If you moved an item from the stock control manually (ex: after a drag'n'drop) and want to reset their position to their original ones, you can call this method.

'''changeItemsWeight( newWeights )'''

With this method you can change dynamically the weight of the item types in a stock control.

Items are immediately re-sorted with the new weight.

Example: with a stock control that contains classic cards, you can order them by value or by color. Using changeItemsWeight you can switch from one sort method to another when a player request this.

newWeights is an associative array: item type id => new weight.

Example:
<pre>
// Item type 1 gets a new weight of 10, 2 a new weight of 20, 3 a new weight of 30.
this.myStockControl.changeItemsWeight( { 1: 10, 2: 20, 3: 30 } );
</pre>

'''setSelectionMode( mode )'''

For each stock control, you can specify a selection mode:
* 0: no item can be selected by the player.
* 1: a maximum of one item can be selected by the player at the same time.
* 2: several items can be selected by the player at the same time.

'''isSelected( id )'''

Return true/false wether the specified item id has been selected or not.

'''selectItem( id )'''

Select the specified item.

'''unselectItem( id )'''

Unselect the specified item.

'''unselectAll()'''

Unselect all items of the stock.

'''onChangeSelection'''

This callback method is called when the player select/unselect an item of the stock.

You can connect this to one of your method like this:
<pre>
dojo.connect( this.myStockControl, 'onChangeSelection', this, 'onMyMethodToCall' );

(...)

onMyMethodToCall: function( control_name )
{
// This method is called when myStockControl selected items changed
var items = this.myStockControl.getSelectedItems();

// (do something)
},
</pre>

'''getSelectedItems()'''

Return the list of selected items, as an array with the following format:
<pre>
[
{ type:1, id: 1001 },
{ type:1, id: 1002 },
{ type:3, id: 1003 }
...
]
</pre>

'''getUnselectedItems()'''

Same as the previous one, but return unselected item instead of seleted ones.

'''getAllItems()'''

Get all items (same format than getSelectedItems and getUnselectedItems).

'''setOverlap( horizontal_percent, vertical_percent )'''

Make items on the stock control "overlap" on each other, to save space.

By default, horizontal_overlap and vertical_overlap are 0.

When horizontal_overlap=20, it means that a stock item must overlap on 20% of the width of the previous item. horizontal_overlap can't be over 100.

vertical_overlap works differently: one items on two are shifted up.

See "Jaipur" game to see an example to use of this function.