Board Game Arena - Kullanıcı katkıları [tr]

Gamehelptashkalar

2015-12-07T09:58:36Z

Quinarbre:

== Game forms ==

On Board Game Arena, Tash-Kalar may be played by 2 to 4 players), and in 2 distinct forms :

- '''The High Form''': Players score points for tasks and for legendary pieces currently on the board, only available for 2 players.

- '''Deathmatch''': No tasks. Players score points for destroying enemy pieces, for summoning legendary beings, and when their opponents invoke a flare. Deathmatch can be played by 2 to 4 players.

The actual board game also features team play in both forms.

== Setup ==

Each player draws 6 cards : 3 beings from his or her own deck, 2 legends, and 1 flare.

In '''High Form''', 3 tasks are revealed that may be claimed, along with a fourth "next task".

In '''Deathmatch''', the player who plays second puts one common piece of each color on the game board, on marked squares.

== Game play ==

Players take turns in clockwise order, beginning with the starting player.
Each turn, you have 2 actions. Exception: The starting player has only 1 action on his or
her first turn.

Possible actions:

- '''Place 1 common piece''' of your color on any empty square. If you have none left to place, you begin this action by picking up 1 of your common or heroic pieces, then place it as a common piece.

- '''Summon a being'''. (See below.)

- '''Discard 1 being''' that you drew from your deck. If you do, you may also return one
or more of your other cards to the bottoms of their decks.

Actions can be done in any order. You can do more than one “place” or “summon” action
per turn (but no more than one “discard” action). You have to use all your actions.
You can invoke a flare (see below) before or after any action.
Invoking a flare does not cost you an action.

Finish your turn by drawing cards so that you end up with 3 beings from your deck, 2
legends, and 1 flare.
If you draw the last card in your deck, you may end up with fewer than 3.

'''High Form''': At the end of the turn, you may claim exactly 1 of the current tasks, if you meet its
criteria.

'''Deathmatch''': At the end of your turn, score points for destroyed enemy pieces: 2 points for legendary,
1 point for heroic, 1 point for each pair of common pieces.

In Deathmatch Melee (3-4 players) you keep a separate count of colored points against each of your opponents. Your final score is the '''lowest''' of all your colored scores.

You get no points for destroying your own pieces. You get no points for an un-
paired common piece, but you can pair two common pieces in different colors.
Also score 1 point (in the color of your choice) each time you summon a legend. (Upgrading a heroic piece does not
count as “summoning a legend”.)

== Summoning a being ==

To summon a being, use 1 action and do the following:

- '''Play the card''' from your hand and choose a square on the board where your pieces match the pattern on the card.
The pattern can be rotated (by 90, 180, or 270 degrees). Mirror images and flips
also count as a match.
The pieces used to summon the being can be the same rank as those depicted
in the pattern or higher rank.
Empty squares are not important to the pattern.

- '''Place a piece of the indicated rank''' (upper left corner of the card) on the square
indicated by the white-framed square in the pattern.
This square may be empty, unless the pattern says it must be occupied by one
of your pieces.
If the square is occupied by a piece of the same rank or lower, destroy that piece
when you put the new piece on the square.
If the square is occupied by a piece of higher rank, you cannot summon the
being.
If all your pieces of that type are already on the board, you may
still be able to summon the being by picking up a piece that is not required for the pattern and use it as
the new piece.

- Once the new piece is on the board, '''resolve the effect''' printed on the card.

- After resolving the effect, discard the card.

== Invoking a flare ==

You can invoke a flare on your turn before or after any action.
To invoke a flare, you must meet at least one of the criteria:

- You meet the upper criterion if one of your opponents has '''that many more upgraded
pieces''' (heroic and legendary) on the board than you.

- You meet the lower criterion if one of your opponents has '''that many more pieces (total)'''
on the board than you.

If you meet the upper criterion, you resolve the upper effect. If you meet the lower
criterion, you resolve the lower effect. If you meet both, you resolve the upper effect
first, then the lower.
If you meet the criteria against several opponents, you choose against whom you compare.
Once the card has been resolved, discard it.

== Resolving effects of beings and flares ==

No other action can be taken and no flare can be invoked until the entire effect of the
card is resolved.
Some parts of an effect may be optional:

- May indicates that a certain part of an effect is optional.

- Up to always includes 0.

Any parts that are not specified as optional are mandatory.
If an effect cannot be performed fully, do the parts that can be done.
When a card uses its own name, it is referring to the piece on the board that represents
the summoned being.

'''Keywords''':

- Upgraded piece: a heroic or legendary piece.

- Non-legendary piece: a common or heroic piece.

- Piece: If a piece is not specified as belonging to you or an opponent, then the
effect includes any player's piece.

- Marked space: a colored space in the pattern. If the text does not refer to marked
spaces, the colored spaces in the pattern are just illustrational.

- Adjacent square: one of eight squares sharing an edge (orthogonally adjacent)
or a corner (diagonally adjacent) with a given square. If the given square is not
specified, assume it is the square currently occupied by the newly summoned
piece.

- Distance: the shortest number of moves required to get from one square to
another. For example, adjacent squares are at distance 1.

- Move: A move is always onto an adjacent square. A move onto an occupied square
destroys the piece that was there.

- Standard move: This type of move can be only onto an empty square or a square
occupied by a piece of lower rank.

- Combat move: This type of move can be only onto an empty square or a square
occupied by a piece of equal or lower rank.

- Standard leap and combat leap: A leap is the same as a move, except the square
doesn’t have to be adjacent. If not specified, a leap can be onto any square on the
board.

- Place: Like the “place” action. However, if there is no piece of the specified color
and rank available, the piece cannot be placed.

- Upgrade: Legendary pieces cannot be upgraded. To upgrade a common piece, flip
it over. To upgrade a heroic piece, remove it and replace it with a legendary piece.
If none is available, the heroic piece cannot be upgraded.

- Downgrade: Common pieces cannot be downgraded. To downgrade a heroic piece,
flip it over. To downgrade a legendary piece, replace it with a heroic piece. If none
is available, the legendary piece cannot be downgraded.

- Destroy: To destroy a piece, remove it from the board.

- Convert: To convert an enemy piece, replace it with one of your pieces of the same
rank (unless a different rank is specified).

When keeping track of '''how many enemy pieces you destroyed''', count pieces you
destroyed during summoning, pieces you destroyed with moves and leaps, pieces you
destroyed with a “destroy” effect, and pieces you converted. Neither upgrading nor
downgrading ever counts as destroying a piece.

== The end of the game ==

The end of the game is triggered when a player draws the last card from his or her deck.

In '''High Form''', the end of the game is also triggered if a player has 9 or more points at the end of any
player’s turn.
Count the points for tasks claimed (by the player or by the team) plus 1 point for
each legendary piece of that player’s color currently on the board. (It doesn’t
matter how the piece became legendary.)

In '''Deathmatch''', the end of the game is also triggered if a player reaches or surpasses 18 points.

Once the turn that triggers the end is done, play continues so that each player gets one
more turn, including the player whose turn triggered the end. Then the game ends.
The player with more points wins.
If there is a tie, the tiebreakers are, in this order: number of upgraded pieces on
the board and then total number of pieces on the board.
If there is still a tie, it remains unbroken.

----

These rules are extracted from CGE's full rules for Tash-Kalar.

Gamehelpcoltexpress

2015-09-12T13:35:41Z

Quinarbre:

== Object of the game and sequence of play ==
To win, you must become the richest Bandit in the
Old West. To reach this goal, you will try to get more
Loot than your opponents...without being hit by too
many bullets! The best shooter will receive the title of
Gunslinger, worth $1000.

There are five Rounds in a game. Each Round has
two phases:
* Phase 1 : Schemin'! The players play their Action cards into a common deck in the center of the table.
* Phase 2 : Stealin'! The Action cards played during Phase 1 are performed.

The game ends after five Rounds.
Each player then adds up the value of the Loot tokens
they have stolen.
The Gunslinger prize is awarded to the player(s) who
shot the most bullets. It is worth $1000.

The richest player wins the game. In case of a tie, the
winner is the tied player who has received the fewest
Bullet cards from other players and Events during
the game.

=== Starting a Round ===
At the beginning of a Round, each player shuffles
their personal deck (made of the 10 Action cards of their colour)
and draws six cards. These cards form that player's Hand.

The Round card shows the number of turns (the
number of Card icons) there will be during this phase.
It also shows how the turns will go :
* Standard turn - The Action cards must be played face-up during the current turn.
* Tunnel - The Action cards must be played face-down during the current turn.
* Speeding-Up - During the current turn, each player plays twice (taking 6 cards or playing two cards in a row or taking 3 cards and playing a card).
* Switching - The current turn is played counter-clockwise, starting with the First Player.

Some Round cards make Events happen. These Events always take place at the end of the Round, after Phase 2: Stealin'! See the tooltip of the Round card for more details.

=== Phase 1: Schemin'! ===
Starting with the First Player, each player plays their
turn, followed by the next player in clockwise order.
On his turn, a player has to:
* either play an Action card face-up (unless otherwise specified) from his Hand to the common deck;
* or take 3 additional cards from his deck and add them to his Hand.
The Schemin'! phase ends when the number of turns
indicated on the Round card has been completed.
Any unplayed cards remaining in a player's Hand are
placed back on the top of his personal deck.

=== Phase 2: Stealin'! ===
The deck of Action cards that
had been created during the Schemin'! phase is turned over, without changing the order of the cards.
The Bandits' Actions are performed, one by one,
starting with the top card (i.e., in the order they have
been played).
Once performed, the Action card is given back to the
player to whom it belongs. That player puts it back on
his personal deck.
Any Action programmed during the
Schemin'! phase is now obligatory. During
the Stealin'! phase, each player must use
his action, if it is still possible.

=== Ending the Round ===
Each player shuffles all his cards (10 Action cards
and any Bullet cards he has been hit with in previous
Rounds). Then he places his deck to the right of his
Character card.
The player on the First Player's left becomes the new
First Player and a new Round now begins.

== The Action Cards ==

=== Move ===
Move your Bandit:
# from one Car to the next adjacent Car, forwards or backwards, if he is inside the Train; or
# A distance ranging from one to three Cars (your choice), forwards or backwards, if he is on the roof.
The Locomotive is considered to be a Car. You can be
in it or on it.
If you have plotted this Action, your
Bandit cannot stay where he is: you
must move him.

=== Floor Change ===
Switch the position of your Bandit from
# The interior to the roof of the Car on which he's standing ;
# or move his from the roof of the Car he's in to its interior.

=== The Marshal ===
Move the Marshal inside the train a distance of one
Car in the direction of your choice. (See "The
Marshal", to find out what happens if the
Marshal meets a Bandit).

=== Fire ===
Choose one of your opponents to be your target and
give him one of your Bullet cards. The targeted player
places the Bullet card he has received on his deck.
You cannot target a Bandit who is on the same spot
as you.
# When you are inside the train, you can shoot a Bandit who is in the interior of an adjacent Car, either to the rear of your Car or ahead of it. Bandits who are more than one Car away cannot be shot.
# When you are on the roof, however, you can shoot a Bandit who is in your Line of Sight and on the roof of any Car other than your own, regardless of the distance. A Bandit is in Line of Sight if there is no other Bandit between you and him. Two Bandits on the roof of the same Car are considered as being side by side, and not located one behind the other: you choose which one gets hit.
If there is no target to be shot, keep your Bullet card:
the Fire action will have no effect.
If you successfully fire your 6 Bullet cards during the game, your
Fire actions will have no further effect.

=== Robbery ===
Take the Loot token of your choice from the Car where
you are currently located and place it face-down on
your Character card.
If your Bandit is on the roof of a Car, he cannot rob
inside it, and vice versa.
If there is no Loot where your Bandit is, then
the Robbery action has no effect.

=== Punch ===
Choose a target among the Bandits who are on the same
Car and same floor as you are.
The targeted Bandit loses a Loot token if he has one:
choose a Loot token from his Character card and place
it on the floor where your Bandit pawn is located. If
you choose a Purse token, you are not allowed to look
at its value.
Then, move the targeted Bandit to the same floor of an
adjacent Car (either forwards or backwards,
your choice in most of the Cars; backwards if
you are in the Engine and forwards if you are
in the Caboose).

== The Marshal ==
Caution! When a Bandit enters a Car where the Marshal
is, or when the Marshal enters a Car where Bandits
are, they must escape up to the roof of the Car (even
if they have just come down from there). A Bandit can
never stay inside the Car where the Marshal is located.
Additionally, each one of those Bandits immediately
receives a Neutral Bullet card which must be placed
on each player's personal deck.

== Expert Variant ==
* At the end of the Schemin'! Phase, you are allowed to keep in your Hand the cards you are interested in holding for next Round. Discard all Bullet cards. Discard all Action cards that you are not interested in.
* During the Stealin'! phase, place the performed Action cards you get back from the First Player on your discard deck. The Bullet cards you received that turn from your opponents, however, go on top of your draw deck, face-down.
* At the beginning of each Round, draw cards from your draw deck and fill your Hand up to six cards.
* Each time your draw deck is depleted and you have to draw cards, shuffle the discard deck to make a new draw deck. You can look through your discard at any time.

== Set-Up for two players ==
There are four Cars, and each player chooses a team of two Characters.
One Bandit pawn from each team is placed inside the two
Cars at the rear of the train.
Each Character of your team starts with a separate deck of six Bullet cards and a $250 Purse on each of them.
From among the Action cards of each Character, every duplicate is discarded as well as the Marshal card from one of your Characters.
You will have
11 cards remaining in your Hand: 2 Fire (1 for each
Character), 2 Punch (1 for each Character), 2 Move
(1 for each Character), 2 Floor Change (1 for each
Character), 2 Robbery (1 for each Character) and 1
Marshal. Shuffle all of them to make your draw deck.
Each player then plays with the mixed Action cards
of the two Bandits.

The game with two players is played with the Expert
Variant described earlier. The goal of the game is to
have the richest team at the end of the game. However,
no one wins the title of Gunslinger in the 2-player game.
When a Bandit is shot, the Bullet card is placed on
the top of the player's draw deck. It may very well
happen that a Bandit will inadvertently shoot his own
teammate!

----
(This summary is made of excerpts Ludonaute's rules for Colt Express.)

Gamehelpcoltexpress

2015-09-04T13:52:33Z

Quinarbre:

== Object of the game and sequence of play ==
To win, you must become the richest Bandit in the
Old West. To reach this goal, you will try to get more
Loot than your opponents...without being hit by too
many bullets! The best shooter will receive the title of
Gunslinger, worth $1000.

There are five Rounds in a game. Each Round has
two phases:
* Phase 1 : Schemin'! The players play their Action cards into a common deck in the center of the table.
* Phase 2 : Stealin'! The Action cards played during Phase 1 are performed.

The game ends after five Rounds.
Each player then adds up the value of the Loot tokens
they have stolen.
The Gunslinger prize is awarded to the player(s) who
shot the most bullets. It is worth $1000.

The richest player wins the game. In case of a tie, the
winner is the tied player who has received the fewest
Bullet cards from other players and Events during
the game.

=== Starting a Round ===
At the beginning of a Round, each player shuffles
their personal deck (made of the 10 Action cards of their colour)
and draws six cards. These cards form that player's Hand.

The Round card shows the number of turns (the
number of Card icons) there will be during this phase.
It also shows how the turns will go :
* Standard turn - The Action cards must be played face-up during the current turn.
* Tunnel - The Action cards must be played face-down during the current turn.
* Speeding-Up - During the current turn, each player plays twice (taking 6 cards or playing two cards in a row or taking 3 cards and playing a card).
* Switching - The current turn is played counter-clockwise, starting with the First Player.

Some Round cards make Events happen. These Events always take place at the end of the Round, after Phase 2: Stealin'! See the tooltip of the Round card for more details.

=== Phase 1: Schemin'! ===
Starting with the First Player, each player plays their
turn, followed by the next player in clockwise order.
On his turn, a player has to:
* either play an Action card face-up (unless otherwise specified) from his Hand to the common deck;
* or take 3 additional cards from his deck and add them to his Hand.
The Schemin'! phase ends when the number of turns
indicated on the Round card has been completed.
Any unplayed cards remaining in a player's Hand are
placed back on the top of his personal deck.

=== Phase 2: Stealin'! ===
The deck of Action cards that
had been created during the Schemin'! phase is turned over, without changing the order of the cards.
The Bandits' Actions are performed, one by one,
starting with the top card (i.e., in the order they have
been played).
Once performed, the Action card is given back to the
player to whom it belongs. That player puts it back on
his personal deck.
Any Action programmed during the
Schemin'! phase is now obligatory. During
the Stealin'! phase, each player must use
his action, if it is still possible.

=== Ending the Round ===
Each player shuffles all his cards (10 Action cards
and any Bullet cards he has been hit with in previous
Rounds). Then he places his deck to the right of his
Character card.
The player on the First Player's left becomes the new
First Player and a new Round now begins.

== The Action Cards ==

=== Move ===
Move your Bandit:
# from one Car to the next adjacent Car, forwards or backwards, if he is inside the Train; or
# A distance ranging from one to three Cars (your choice), forwards or backwards, if he is on the roof.
The Locomotive is considered to be a Car. You can be
in it or on it.
If you have plotted this Action, your
Bandit cannot stay where he is: you
must move him.

=== Floor Change ===
Switch the position of your Bandit from
# The interior to the roof of the Car on which he's standing ;
# or move his from the roof of the Car he's in to its interior.

=== Marshal ===
Move the Marshal inside the train a distance of one
Car in the direction of your choice. (See "The
Marshal", to find out what happens if the
Marshal meets a Bandit).

=== Fire ===
Choose one of your opponents to be your target and
give him one of your Bullet cards. The targeted player
places the Bullet card he has received on his deck.
You cannot target a Bandit who is on the same spot
as you.
# When you are inside the train, you can shoot a Bandit who is in the interior of an adjacent Car, either to the rear of your Car or ahead of it. Bandits who are more than one Car away cannot be shot.
# When you are on the roof, however, you can shoot a Bandit who is in your Line of Sight and on the roof of any Car other than your own, regardless of the distance. A Bandit is in Line of Sight if there is no other Bandit between you and him. Two Bandits on the roof of the same Car are considered as being side by side, and not located one behind the other: you choose which one gets hit.
If there is no target to be shot, keep your Bullet card:
the Fire action will have no effect.
If you successfully fire your 6 Bullet cards during the game, your
Fire actions will have no further effect.

=== Robbery ===
Take the Loot token of your choice from the Car where
you are currently located and place it face-down on
your Character card.
If your Bandit is on the roof of a Car, he cannot rob
inside it, and vice versa.
If there is no Loot where your Bandit is, then
the Robbery action has no effect.

=== Punch ===
Choose a target among the Bandits who are on the same
Car and same floor as you are.
The targeted Bandit loses a Loot token if he has one:
choose a Loot token from his Character card and place
it on the floor where your Bandit pawn is located. If
you choose a Purse token, you are not allowed to look
at its value.
Then, move the targeted Bandit to the same floor of an
adjacent Car (either forwards or backwards,
your choice in most of the Cars; backwards if
you are in the Engine and forwards if you are
in the Caboose).

== The Marshal ==
Caution! When a Bandit enters a Car where the Marshal
is, or when the Marshal enters a Car where Bandits
are, they must escape up to the roof of the Car (even
if they have just come down from there). A Bandit can
never stay inside the Car where the Marshal is located.
Additionally, each one of those Bandits immediately
receives a Neutral Bullet card which must be placed
on each player's personal deck.

== Expert Variant ==
* At the end of the Schemin'! Phase, you are allowed to keep in your Hand the cards you are interested in holding for next Round. Discard all Bullet cards. Discard all Action cards that you are not interested in.
* During the Stealin'! phase, place the performed Action cards you get back from the First Player on your discard deck. The Bullet cards you received that turn from your opponents, however, go on top of your draw deck, face-down.
* At the beginning of each Round, draw cards from your draw deck and fill your Hand up to six cards.
* Each time your draw deck is depleted and you have to draw cards, shuffle the discard deck to make a new draw deck. You can look through your discard at any time.

== Set-Up for two players ==
There are four Cars, and each player chooses a team of two Characters.
One Bandit pawn from each team is placed inside the two
Cars at the rear of the train.
Each Character of your team starts with a separate deck of six Bullet cards and a $250 Purse on each of them.
From among the Action cards of each Character, every duplicate is discarded as well as the Marshal card from one of your Characters.
You will have
11 cards remaining in your Hand: 2 Fire (1 for each
Character), 2 Punch (1 for each Character), 2 Move
(1 for each Character), 2 Floor Change (1 for each
Character), 2 Robbery (1 for each Character) and 1
Marshal. Shuffle all of them to make your draw deck.
Each player then plays with the mixed Action cards
of the two Bandits.

The game with two players is played with the Expert
Variant described earlier. The goal of the game is to
have the richest team at the end of the game. However,
no one wins the title of Gunslinger in the 2-player game.
When a Bandit is shot, the Bullet card is placed on
the top of the player's draw deck. It may very well
happen that a Bandit will inadvertently shoot his own
teammate!

----
(This summary is made of excerpts Ludonaute's rules for Colt Express.)

Gamehelpcoltexpress

2015-09-04T13:47:47Z

Quinarbre: Created page with "== Object of the game and sequence of play == To win, you must become the richest Bandit in the Old West. To reach this goal, you will try to get more Loot than your opponents..."

== Object of the game and sequence of play ==
To win, you must become the richest Bandit in the
Old West. To reach this goal, you will try to get more
Loot than your opponents...without being hit by too
many bullets! The best shooter will receive the title of
Gunslinger, worth $1000.

There are five Rounds in a game. Each Round has
two phases:
* Phase 1 : Schemin'! The players play their Action cards into a common deck in the center of the table.
* Phase 2 : Stealin'! The Action cards played during Phase 1 are performed.

The game ends after five Rounds.
Each player then adds up the value of the Loot tokens
they have stolen.
The Gunslinger prize is awarded to the player(s) who
shot the most bullets. It is worth $1000.
The richest player wins the game. In case of a tie, the
winner is the tied player who has received the fewest
Bullet cards from other players and Events during
the game.

=== Starting a Round ===
At the beginning of a Round, each player shuffles
their personal deck (made of the 10 Action cards of their colour)
and draws six cards. These cards form that player's Hand.
This Round card shows the number of turns (the
number of Card icons) there will be during this phase.
It also shows how the turns will go :
* Standard turn - The Action cards must be played face-up during the current turn.
* Tunnel - The Action cards must be played face-down during the current turn.
* Speeding-Up - During the current turn, each player plays twice (taking 6 cards or playing two cards in a row or taking 3 cards and playing a card).
* Switching - The current turn is played counter-clockwise, starting with the First Player.

Some Round cards make Events happen. These Events always take place at the end of the Round, after Phase 2: Stealin'! See the tooltip of the Round card for more details.

=== Phase 1: Schemin'! ===
Starting with the First Player, each player plays their
turn, followed by the next player in clockwise order.
On his turn, a player has to:
* either play an Action card face-up (unless otherwise specified) from his Hand to the common deck;
* or take 3 additional cards from his deck and add them to his Hand.
The Schemin'! phase ends when the number of turns
indicated on the Round card has been completed.
Any unplayed cards remaining in a player's Hand are
placed back on the top of his personal deck.

=== Phase 2: Stealin'! ===
The deck of Action cards that
had been created during the Schemin'! phase is turned over, without changing the order of the cards.
The Bandits' Actions are performed, one by one,
starting with the top card (i.e., in the order they have
been played).
Once performed, the Action card is given back to the
player to whom it belongs. That player puts it back on
his personal deck.
Any Action programmed during the
Schemin'! phase is now obligatory. During
the Stealin'! phase, each player must use
his action, if it is still possible.

=== Ending the Round ===
Each player shuffles all his cards (10 Action cards
and any Bullet cards he has been hit with in previous
Rounds). Then he places his deck to the right of his
Character card.
The player on the First Player's left becomes the new
First Player. He puts the remaining Round cards in
front of him. A new Round now begins.

== The Action Cards ==

=== Move ===
Move your Bandit:
# from one Car to the next adjacent Car, forwards or backwards, if he is inside the Train; or
# A distance ranging from one to three Cars (your choice), forwards or backwards, if he is on the roof.
The Locomotive is considered to be a Car. You can be
in it or on it.
If you have plotted this Action, your
Bandit cannot stay where he is: you
must move him.

=== Floor Change ===
Switch the position of your Bandit from
# The interior to the roof of the Car on which he's standing ;
# or move his from the roof of the Car he's in to its interior.

=== Marshal ===
Move the Marshal inside the train a distance of one
Car in the direction of your choice. (See "The
Marshal", to find out what happens if the
Marshal meets a Bandit).

=== Fire ===
Choose one of your opponents to be your target and
give him one of your Bullet cards. The targeted player
places the Bullet card he has received on his deck.
You cannot target a Bandit who is on the same spot
as you.
# When you are inside the train, you can shoot a Bandit who is in the interior of an adjacent Car, either to the rear of your Car or ahead of it. Bandits who are more than one Car away cannot be shot.
# When you are on the roof, however, you can shoot a Bandit who is in your Line of Sight and on the roof of any Car other than your own, regardless of the distance. A Bandit is in Line of Sight if there is no other Bandit between you and him. Two Bandits on the roof of the same Car are considered as being side by side, and not located one behind the other: you choose which one gets hit.
If there is no target to be shot, keep your Bullet card:
the Fire action will have no effect.
If you successfully fire your 6 Bullet cards during the game, your
Fire actions will have no further effect.

=== Robbery ===
Take the Loot token of your choice from the Car where
you are currently located and place it face-down on
your Character card.
If your Bandit is on the roof of a Car, he cannot rob
inside it, and vice versa.
If there is no Loot where your Bandit is, then
the Robbery action has no effect.

=== Punch ===
Choose a target among the Bandits who are on the same
Car and same floor as you are.
The targeted Bandit loses a Loot token if he has one:
choose a Loot token from his Character card and place
it on the floor where your Bandit pawn is located. If
you choose a Purse token, you are not allowed to look
at its value.
Then, move the targeted Bandit to the same floor of an
adjacent Car (either forwards or backwards,
your choice in most of the Cars; backwards if
you are in the Engine and forwards if you are
in the Caboose).

== The Marshal ==
Caution! When a Bandit enters a Car where the Marshal
is, or when the Marshal enters a Car where Bandits
are, they must escape up to the roof of the Car (even
if they have just come down from there). A Bandit can
never stay inside the Car where the Marshal is located.
Additionally, each one of those Bandits immediately
receives a Neutral Bullet card which must be placed
on each player's personal deck.

== Expert Variant ==
* At the end of the Schemin'! Phase, you are allowed to keep in your Hand the cards you are interested in holding for next Round. Discard all Bullet cards. Discard all Action cards that you are not interested in.
* During the Stealin'! phase, place the performed Action cards you get back from the First Player on your discard deck. The Bullet cards you received that turn from your opponents, however, go on top of your draw deck, face-down.
* At the beginning of each Round, draw cards from your draw deck and fill your Hand up to six cards.
* Each time your draw deck is depleted and you have to draw cards, shuffle the discard deck to make a new draw deck. You can look through your discard at any time.

== Set-Up for two players ==
There are four Cars, and each player chooses a team of two Characters.
One Bandit pawn from each team is placed inside the two
Cars at the rear of the train.
Each Character of your team starts with a separate deck of six Bullet cards and a $250 Purse on each of them.
From among the Action cards of each Character, every duplicate is discarded as well as the Marshal card from one of your Characters.
You will have
11 cards remaining in your Hand: 2 Fire (1 for each
Character), 2 Punch (1 for each Character), 2 Move
(1 for each Character), 2 Floor Change (1 for each
Character), 2 Robbery (1 for each Character) and 1
Marshal. Shuffle all of them to make your draw deck.
Each player then plays with the mixed Action cards
of the two Bandits.

The game with two players is played with the Expert
Variant described earlier. The goal of the game is to
have the richest team at the end of the game. However,
no one wins the title of Gunslinger in the 2-player game.
When a Bandit is shot, the Bullet card is placed on
the top of the player's draw deck. It may very well
happen that a Bandit will inadvertently shoot his own
teammate!

(This summary is made of excerpts Ludonaute's rules for Colt Express.)

Gamehelptashkalar

2014-12-25T17:45:26Z

Quinarbre:

== Game forms ==

On Board Game Arena, Tash-Kalar may be played only by 2 players, and in 2 distinct forms :

- '''The High Form''': Players score points for tasks and for legendary pieces currently on the board.

- '''Deathmatch Duel''': No tasks. Players score points for destroying enemy pieces, for summoning legendary beings, and when their opponent invokes a flare.

The actual board game also features Deathmatch Melee for 3 or 4 players, and team play.

== Setup ==

Each player draws 6 cards : 3 beings from his or her own deck, 2 legends, and 1 flare.

In '''High Form''', 3 tasks are revealed that may be claimed, along with a fourth "next task".

In '''Deathmatch''', the player who plays second puts one common piece of each color on the game board, on marked squares.

== Game play ==

Players take turns in clockwise order, beginning with the starting player.
Each turn, you have 2 actions. Exception: The starting player has only 1 action on his or
her first turn.

Possible actions:

- '''Place 1 common piece''' of your color on any empty square. If you have none left to place, you begin this action by picking up 1 of your common or heroic pieces, then place it as a common piece.

- '''Summon a being'''. (See below.)

- '''Discard 1 being''' that you drew from your deck. If you do, you may also return one
or more of your other cards to the bottoms of their decks.

Actions can be done in any order. You can do more than one “place” or “summon” action
per turn (but no more than one “discard” action). You have to use all your actions.
You can invoke a flare (see below) before or after any action.
Invoking a flare does not cost you an action.

Finish your turn by drawing cards so that you end up with 3 beings from your deck, 2
legends, and 1 flare.
If you draw the last card in your deck, you may end up with fewer than 3.

'''High Form''': At the end of the turn, you may claim exactly 1 of the current tasks, if you meet its
criteria.

'''Deathmatch''': At the end of your turn, score points for destroyed enemy pieces: 2 points for legendary,
1 point for heroic, 1 point for each pair of common pieces.
You get no points for destroying your own pieces. You get no points for an un-
paired common piece.
Also score 1 point each time you summon a legend. (Upgrading a heroic piece does not
count as “summoning a legend”.)

== Summoning a being ==

To summon a being, use 1 action and do the following:

- '''Play the card''' from your hand and choose a square on the board where your pieces match the pattern on the card.
The pattern can be rotated (by 90, 180, or 270 degrees). Mirror images and flips
also count as a match.
The pieces used to summon the being can be the same rank as those depicted
in the pattern or higher rank.
Empty squares are not important to the pattern.

- '''Place a piece of the indicated rank''' (upper left corner of the card) on the square
indicated by the white-framed square in the pattern.
This square may be empty, unless the pattern says it must be occupied by one
of your pieces.
If the square is occupied by a piece of the same rank or lower, destroy that piece
when you put the new piece on the square.
If the square is occupied by a piece of higher rank, you cannot summon the
being.
If all your pieces of that type are already on the board, you may
still be able to summon the being by picking up a piece that is not required for the pattern and use it as
the new piece.

- Once the new piece is on the board, '''resolve the effect''' printed on the card.

- After resolving the effect, discard the card.

== Invoking a flare ==

You can invoke a flare on your turn before or after any action.
To invoke a flare, you must meet at least one of the criteria:

- You meet the upper criterion if your opponent has '''that many more upgraded
pieces''' (heroic and legendary) on the board than you.

- You meet the lower criterion if your opponent has '''that many more pieces (total)'''
on the board than you.

If you meet the upper criterion, you resolve the upper effect. If you meet the lower
criterion, you resolve the lower effect. If you meet both, you resolve the upper effect
first, then the lower.
Once the card has been resolved, discard it.

== Resolving effects of beings and flares ==

No other action can be taken and no flare can be invoked until the entire effect of the
card is resolved.
Some parts of an effect may be optional:

- May indicates that a certain part of an effect is optional.

- Up to always includes 0.

Any parts that are not specified as optional are mandatory.
If an effect cannot be performed fully, do the parts that can be done.
When a card uses its own name, it is referring to the piece on the board that represents
the summoned being.

'''Keywords''':

- Upgraded piece: a heroic or legendary piece.

- Non-legendary piece: a common or heroic piece.

- Piece: If a piece is not specified as belonging to you or an opponent, then the
effect includes any player's piece.

- Marked space: a colored space in the pattern. If the text does not refer to marked
spaces, the colored spaces in the pattern are just illustrational.

- Adjacent square: one of eight squares sharing an edge (orthogonally adjacent)
or a corner (diagonally adjacent) with a given square. If the given square is not
specified, assume it is the square currently occupied by the newly summoned
piece.

- Distance: the shortest number of moves required to get from one square to
another. For example, adjacent squares are at distance 1.

- Move: A move is always onto an adjacent square. A move onto an occupied square
destroys the piece that was there.

- Standard move: This type of move can be only onto an empty square or a square
occupied by a piece of lower rank.

- Combat move: This type of move can be only onto an empty square or a square
occupied by a piece of lower rank.

- Standard leap and combat leap: A leap is the same as a move, except the square
doesn’t have to be adjacent. If not specified, a leap can be onto any square on the
board.

- Place: Like the “place” action. However, if there is no piece of the specified color
and rank available, the piece cannot be placed.

- Upgrade: Legendary pieces cannot be upgraded. To upgrade a common piece, flip
it over. To upgrade a heroic piece, remove it and replace it with a legendary piece.
If none is available, the heroic piece cannot be upgraded.

- Downgrade: Common pieces cannot be downgraded. To downgrade a heroic piece,
flip it over. To downgrade a legendary piece, replace it with a heroic piece. If none
is available, the legendary piece cannot be downgraded.

- Destroy: To destroy a piece, remove it from the board.

- Convert: To convert an enemy piece, replace it with one of your pieces of the same
rank (unless a different rank is specified).

When keeping track of '''how many enemy pieces you destroyed''', count pieces you
destroyed during summoning, pieces you destroyed with moves and leaps, pieces you
destroyed with a “destroy” effect, and pieces you converted. Neither upgrading nor
downgrading ever counts as destroying a piece.

== The end of the game ==

The end of the game is triggered when a player draws the last card from his or her deck.

In '''High Form''', the end of the game is also triggered if a player has 9 or more points at the end of any
player’s turn.
Count the points for tasks claimed (by the player or by the team) plus 1 point for
each legendary piece of that player’s color currently on the board. (It doesn’t
matter how the piece became legendary.)

In '''Deathmatch''', the end of the game is also triggered if a player reaches or surpasses 18 points.

Once the turn that triggers the end is done, play continues so that each player gets one
more turn, including the player whose turn triggered the end. Then the game ends.
The player with more points wins.
If there is a tie, the tiebreakers are, in this order: number of upgraded pieces on
the board and then total number of pieces on the board.
If there is still a tie, it remains unbroken.

----

These rules are extracted from CGE's full rules for Tash-Kalar.

Gamehelptashkalar

2014-12-25T17:43:54Z

Quinarbre: Created page with "== Game forms == On Board Game Arena, Tash-Kalar may be played only by 2 players, and in 2 distinct forms : - '''The High Form''': Players score points for tasks and for leg..."

Game interface logic: yourgamename.js

2014-04-30T23:36:24Z

Quinarbre: /* Tooltips */

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 change from the server and how it will show in the browser.

== File structure ==

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

Basically, here's this structure:
* constructor: here you can define variable global to your whole interface.
* setup: this method is called when the page is refreshed, in order you can setup the game interface.
* onEnteringState: the method is called when entering in a new game state. This way you can customize the view for this game state.
* onLeavingState: the method is called when leaving a game state.
* onUpdateActionButtons: called when entering in a new state, in order you can add action buttons in status bar.
* (utility methods): at this place you can define your utility methods
* (player's actions): at this place you can write your handlers for player's action on the interface (ex: click on an item).
* setupNotifications: in this method you associate notifications with notification handlers. This way, for each game notification, you trigger a javascript method to handle it and update the game interface.
* (notification handlers): at this place you can define your notifications handlers.

== General tips ==

; this.player_id
: Id of the player on whose browser the code is running.

; this.isSpectator
: Flag set to true if the user at the table is a spectator (not a player).
: Note: if you want to hide some element for spectators, you'd better use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

; this.gamedatas
: Contains your initial set of datas to init the game, created at game start or 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 (most of the time you don't).

; isCurrentPlayerActive()
: Returns true if the player on whose browser the code is running is currently active (it's his turn to play)

; this.getActivePlayerId()
: Return the ID of active player, or null if we are not in a "activeplayer" type state.

; this.getActivePlayers()
: Return an array with the IDs of players that are currently active (or an empty array if there is not).

== Dojo framework ==

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

The Dojo framework allows us to do complex things easier, and the BGA framework is using Dojo framework a lot.

To realize game although, you only need to use a few part of the Dojo framework. All the Dojo methods you need to use are describe on this page.

== Access and manipulate the DOM ==

'''$('some_html_element_id')'''

The $() function is used to get some HTML element using its "id" attribute.

Example 1: modify the content of a "span" element:
<pre>
In your HTML code:
<span id="a_value_in_the_game_interface">1234</span>

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

Note: $() is the standard method to access some HTML element with BGA Framework. You must not use "getElementById" function.

'''dojo.style'''

With dojo.style you can modify a CSS property of any HTML element of 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 sprite to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

Note: you must always use dojo.style to modify CSS properties of HTML elements.

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

'''dojo CSS classes manipulation'''

In many situation, a bunch of many small CSS property update can be replaced by a CSS class change (ie: you add a CSS class to your element instead of applying all modification 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 whithout error.
* You can test if you applied the stuff to an element with "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 change in one line of code.

// ... and when we need to check if a square is a possible move on 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>

Conclusion: we encourage you to use dojo.addClass, dojo.removeClass and dojo.hasClass to make your life easier :)

'''dojo.query'''

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 (ie: elements with class "token") on the board (ie: 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>

'''dojo.place'''

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

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<your html code>", "your_container_element_id" );

// Replace the container element with your new html
dojo.place( "<your html code>", "your_container_element_id", "replace" );

</pre>

Note: the third parameter of dojo.place can take various interesting value: "first", "after", ... [http://dojotoolkit.org/reference-guide/1.7/dojo/place.html See full doc on dojo.place].

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

'''addStyleToClass: function( cssClassName, cssProperty, propertyValue )'''

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

=== 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.

'''this.slideToObject( mobile_obj, target_obj, duration, delay )'''

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>

'''this.slideToObjectPos( mobile_obj, target_obj, target_x, target_y, duration, delay )'''

This method does exactly the same than "slideToObjectPos", 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 to the bottom:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject( mobile_obj_html, mobile_obj_parent, from, to, duration, delay )'''

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.
* mobile_obj_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' );
</pre>

'''this.slideToObjectAndDestroy: function( node, to, time, delay )'''

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.

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

'''this.fadeOutAndDestroy( node )'''

This function fade out the target HTML node, then destroy it.

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.

'''Rotating elements'''

You can check here [http://jimfulton.info/demos/dojo-animated-rotate.html an example of use] of Dojo to make an element rotate.

This example combines "Dojo.Animation" method and a CSS3 property that allow you to rotate the element.

IMPORTANT: to asses browser compatibility, you must select the CSS property to use just like in the example (see sourcecode below):

<pre>
var transform;
dojo.forEach(
['transform', 'WebkitTransform', 'msTransform',
'MozTransform', 'OTransform'],
function (name) {
if (typeof dojo.body().style[name] != 'undefined') {
transform = name;
}
});
// ... and then use "transform" as the name of your CSS property for rotation
</pre>

=== Moving elements ===

'''this.placeOnObject( mobile_obj, target_obj )'''

placeOnObject works exactly like "slideToObject", except that the 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>

'''this.placeOnObjectPos( mobile_obj, target_obj, target_x, target_y )'''

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

'''this.attachToNewParent( mobile_obj, target_obj )'''

With this method, you change the HTML parent of "mobile_obj" element. "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.

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

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: when you attach an HTML element with a new parent, you break all references to this HTML element (ex: dojo.connect).

== Players input ==

'''dojo.connect'''

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

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

Note: this is the only possible correct way to associate a player input event to your code, and you must not use anything else.

'''this.checkAction( "my_action_name" )'''

Usage: checkAction: function( action, nomessage )

Check if player can do the specified action by taking into account:
* current game state
* interface locking (a player can't do any action if an action is already in progress)

return true if action is authorized (ie: the action is listed as a "possibleaction" in current game state).

return false and display an error message if not (display no message if nomessage parameter is true). The displayed error message could be either "This move is not allowed at this moment" or "An action is already in progress".

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

'''this.ajaxcall( url, parameters, obj_callback, callback, callback_error )'''

This method must be used to send a player input to the game server.

* 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 parameter in order the interface can be locked during the server call.
* obj_callback: must be set to "this".
* callback: a function to trigger when the server returns and everything went fine.
* callback_error: (optional and rarely used) a function to trigger when the server returns an error.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true,
arg1: myarg1,
arg2: myarg2,
...
}, this, function( result ) {
// Do some stuff after a successful call
} );
</pre>

Restricted arguments names (please don't use them):
* "action"
* "module"
* "class"

'''this.confirmationDialog()'''

Display a confirmation dialog with a yes/no choice.

We advice you to NOT use this function unless the player action is really critical and could ruins the game, because it slows down the game and upset players.

Usage: this.confirmationDialog( "Question to displayed", callback_function_if_click_on_yes );

Example:
<pre>
this.confirmationDialog( _('Are you sure to use this bonus (points penalty at the end of the game) ?'),
dojo.hitch( this, function() {
this.ajaxcall( '/seasons/seasons/useBonus.html',
{ id:bonus_id, lock:true }, this, function( result ) {} );
} ) );
</pre>

; addEventToClass: function( cssClassName, eventName, functionName )
: Same as dojo.connect(), but for all the nodes set with the specified cssClassName

'''this.addActionButton( id, label, method, (opt)depreciated, (opt)bHighlight )'''

You can use this method to add an action button in the main action status bar.

Arguments:
* id: a ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function).
* method: the name of your method that must be triggered when the player clicks on this button.
* depreciated (optional): do not use this. Please not specify this argument or use "null".
* bHighlight: if set to "true", the button is going blink to catch player's attention. Please don't abuse of blinking button.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this (from Hears example):

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

if( this.isCurrentPlayerActive() )
{
switch( stateName )
{
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
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.

== Translations ==

See [[Translations]]

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

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>
// In setupNotifications method:
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 to all notifications arguments with "notif.args".

Example:
<pre>
// If you did this on PHP side:
self::notifyAllPlayers( "myNotification", '', array( "myArgument" => 3 ) );

// On Javascript side, you can access the "myArgument" like this:
notif_myNotification: function( notif )
{
alert( "myArgument = " + notif.args.myArgument );
}
</pre>

=== 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, they are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

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>

== Tooltips ==

'''this.addTooltip( nodeId, _( helpString ), _( actionString ), delay )'''

Add a simple text tooltip to the DOM node.

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

You must specify both helpString and actionString. Most of the time, you use only one and specify a void string ("") for the other one.

Usually, _() must be used for the text to be marked for translation.

"Delay" is an optional parameter. Usually, it is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browser (see Guidelines).

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

'''this.addTooltipHtml( nodeId, html, delay )'''

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

'''this.addTooltipToClass( cssClass, _( helpString ), _( actionString ), delay )'''

Add a simple text tooltip to all the DOM nodes set with this cssClass.

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

'''this.addTooltipHtmlToClass( cssClass, html, delay )'''

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 have IDs to get tooltips

'''this.removeTooltip( nodeId )'''

Remove a tooltip from the DOM node.

== Dialogs, warning messages, confirmation dialogs, ... ==

=== Warning messages ===

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

Ex: someone fulfill one of the end of the game condition, so this is the last turn.

'''this.showMessage( msg, type )'''

showMessage shows a message in a big rectangular area on the top of the screen of current player.

* "msg" is the string to display. It should be translated.
* "type" can be set to "info" or "error". If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background.

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

=== 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 guidelines of BGA is to AVOID the use of confirmation dialog. Confirmation dialogs slow down the game and bother players. The players knows that they have to pay attention about each move when they are playing online.

The situation 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 do not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

How to display a confirmation dialog:
<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>

=== Dialogs ===

At first, 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:

<pre>

// Create the new dialog. You should store the handler in a member variable to access it later
this.myDlg = new dijit.Dialog({ title: _("my dialog title to translate") });

// 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.attr("content", html );
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, a "close" button:
dojo.connect( $('closeDlg'), 'onclick', this, function(evt){
evt.preventDefault();
this.myDlg.hide();
} );

</pre>

Tip: be careful with "hide()" method to close your dialog: the dialog and its content is not completely removed from the DOM. It can cause you problems if you try to display the same dialog several times. A good practice is to wrap all the content of your dialog in a "<div id='myDlgContent'>" div element, and to call "dojo.destroy('myDlgContent')" before displaying your dialog.

=== 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 describe the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = array(
array( "one", "two", "three" ), // This is my first line
array( "four", "five", "six" ), // This is my second line
array( "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 = array(
array( "one", "two", array( "str" => "a string with an ${argument}", "args" => array( 'argument' => 'argument_value' ) ) ),
array( "four", "five", "six" ),
array( "seven", "height", "nine" )
);
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = array( '' );
foreach( $players as $player_id => $player )
{
$firstRow[] = array( 'str' => '${player_name}',
'args' => array( 'player_name' => $player['player_name'] ),
'type' => 'header'
);
}
$table[] = $firstRow;
</pre>

You can also use three extra attributes in the parameter array for the notification:

<pre>
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => '<div>Some header</div>',
"footer" => '<div>Some footer</div>',
"closelabel" => clienttranslate( "Closing button label" )
) );
</pre>

*'''header''': the content for this parameter will display before the table (also, the html will be parsed and player names will be colored according to the current game colors)
*'''footer''': the content for this parameter will display after the table (no parsing for coloring the player names)
*'''closelabel''': 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). NB: this last parameter is not yet - 24/02/2014 - deployed on the studio, but can be used already and will take effect immediately with the next update.

== Update players score ==

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>

== Players panels ==

=== 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><span id="stonecount_p${id}">0</span>\
</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 ===

'''this.disablePlayerPanel( player_id )'''

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.

'''this.enablePlayerPanel( player_id )'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels()'''

Enable all player panels that has been disabled before.

== 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 )'''

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.

'''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.

== 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 are sure that the "this" object will be set when the callback is called.

; updateCounters(counters)
: Useful for updating game counters in the player panel (such as resources).
: 'counters' arg is an associative array [counter_name_value => [ 'counter_name' => counter_name_value, 'counter_value' => counter_value_value], ... ]
: All counters must be referenced in this.gamedatas.counters and will be updated.
: DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

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