Board Game Arena - User contributions [en]

Gamehelpbeyondthesun

2026-03-20T00:31:23Z

Daveoh: Show colour icons with the technology types

[[Category:Card games]]
== Icons ==

[SHIP]/[SUPPLY]/[POPULATION]: Player cubes. Your [SUPPLY] are stored on your player board until converted to [SHIP] or [POPULATION].

[SUPPLY][ARROW][POPULATION]: Convert a Supply cube from the leftmost column into a Population cube.

[ORE]: Ore. You can see how much Ore you have in the player pane.

[LOSE_POPULATION]: Lose population (as part of the cost to perform an action).

[I]/[II]/[III]/[IIII]: Technology of level 1/2/3/4.

[RESEARCH][TECHX]: Research a technology. Requires a [POPULATION].

[VP]: Victory points.

[COLONIZE]: Colonize a System. You must control the System with ships with a combined power of at least the System's colonize cost.

== Technologies ==

The 4 types of Technologies have different characteristics, summarized below. A hybrid Technology generally contains characteristics of both of its types.

* 🟦 '''Scientific (blue):''' Ore production automation, research actions, and Ore bonuses
* 🟩 '''Economic (green):''' Food production automation, Population collection, and Ore collection
* 🟥 '''Military (red):''' Shipbuilding, movements, and upgrades
* 🟨 '''Commercial (yellow):''' Colonization actions, ship movements, and flexible actions

== Income Phase ==

In the income phase, you may choose one of the following three options.

* '''Population:''' From each Supply Column above an uncovered space on the Population track, take one Supply and convert it to a Population
* '''Ore:''' Gain a quantity of Ore equal to the sum of uncovered Ore quantities on the Ore track.
* '''Resource trade:''' You may make as many of the following trades as you wish.
** Spend 3 Ore to turn 1 of your cubes from your leftmost Supply Column into a Population.
** Pay 1 ore to take 1 Spaceship from anywhere and turn it into a Population cube.
** Return a Population to the rightmost Supply Column with an empty space to gain an ore.

== Triggering the End of the Game, End Game Scoring, and Victory Points==

When enough discs have been placed on Achievements, the next round will be the final round of the game:

* '''2 or 3 players:''' 3 Achievements claimed
* '''4 players:''' 4 Achievements claimed

Points are scored for the following

'''Technologies'''
* 1 VP / Level I Technologies
* 2 VP / Level II Technologies
* 3 VP / Level III Technologies

'''“Private Technologies”''' (from card bonuses)
* 2 VP / Level II Technologies
* 3 VP / Level III Technologies

'''Level IV Technologies'''
* # VP / Level IV Technologies (differs per card)

'''Automation Track'''
* Add all VP showing up to level reached
* After level 7, each additional level adds 1 VP

'''Colonized Systems'''
* # VP / All System Cards (check bottom of each System Card)

'''Uncolonized Outpost Discs''' (on System card or Shipyard Systems)
* 1 VP / Each

'''Non-controllable Locations''' (Sol and Deep Space)
* 1 VP / Faction(s) with the highest military power (tied players get the same VP)

'''Event Cards'''
* # VP / Event Card (Can provide VP. Found in some Achievement cards, attached to certain locations, or faction based)

'''Achievements'''
* # VP / Specified by achievement (Can not get same achievement 2x)

'''Tiebreaker'''

'''1.''' Combined production level (Food and Ore)

'''2.''' ''(If still tied after 1)'' The highest remaining Population cubes

'''3.''' ''(If still tied after 2)'' The highest remaining Ore

== Changes in BGA adaptation ==

Minor changes were necessary to allow the game to work smoothly on BGA. Special thanks to the designer, Dennis Chan, for consulting on how best to adapt the game to the BGA framework.

'''Spacetime Anomaly Studies:''' The research portion of the action is optional.

'''DEN 0255-4700:''' The colonize bonus is optional.

'''Galactic HQ, Black Market Industries, Giga-Corporations, Cygni 61, Mind/Machine Assimilation:''' You cannot use these in the middle of another action.

'''Giga-Corporations:''' You may only replace discs on your turn; however, at the end of the game, any remaining star discs on achievements are automatically replaced.

Gamehelprevive

2025-09-20T19:18:38Z

Daveoh: Updated Explore, and End of Game

== '''Important notes''' ==
If you already know the game, here are a few things you should know about this implementation:

* The crystal conversion is automated. Whenever you need to pay more than you have of a resource, the game will just use your crystals. If you get a surplus of crystals you can convert them.
* Each turn is strictly split into 2 parts for the 2 actions(unless the player hibernates). Every free action you do is considered part of the respective main action.
* It has already been clarified on BGG, that you can use crates for payment even if the crate would otherwise push you beyond the resource-limit. Here you can temporarily get beyond the limit within the action. At the end of that action any surplus is lost. If you want to do a free action before your second action that would give you a surplus for that action, you need to finish the first action with the button 'next action' first.
* When playing with the expansion, every point and devotion point you gain during an action, can be summed up to be converted 2:1
* The machine, that allows you to treat a card as any color for 1 action can only be used for card that is being played.
* If you play on a small screen, the supply/market is not visible per default. You can open with a button inthe action bar.
* If you're missing the player aid, go to user settings and turn on the help button, it will provide something similar

== '''About the Game''' ==
In Revive, you explore the land, so that you can populate and build on it. Each player has a tribe with a special ability and technologies that can be unlocked by populating.

They also have 3 machine tracks. Advancing on them can unlock free actions(machines) and other bonuses.

There are 3 basic Resources (gear, book, and food) and crystals which can be converted into any of the 3. The resources you can have are limited (max 3 crystals and 6 of each of the others). But when you get more crystals you can just convert them to any other.

== '''Turn overview''' ==
'''During your turn may either'''

A) Take 2 Main Actions (different or the same):

• Play a card

• Use your Switch

• Explore

• Build

• Populate

or

B) Hibernate

At any point during your turn (before between or after your 2 Actions, even before, during or after hibernating) you may

• use a machine

• use a crate

• use a special trade action that you unlocked with one of your technologies

The Main Actions in detail:

== '''Play a card''' ==
At the start of the game (after the setup is complete) you have 6 citizen cards. 3 of them are in your active area visible for all. The other 3 form your rest area (facedown but accessible for all) on the right of your player board.

Each card has 2 parts: One at the top and one at the bottom. On your player board you have 5 Card slots. 2 at the top, 2 at the bottom and one the the right. This last one is only available after you unlock the middle technology in the second row of your tribe.

When you play a card you have to put it in a slot that is either empty or contains only cards with a symbol at the visible border. If you put it in a top slot you get the top effect and visa versa. If you have unlocked the side slot you can put a card in there in any orientation to get the part you want.

Each card's slots also has space for 2-3 slot modules. Whenever you gain a slot module, put in any of these slots. They all have 1 or 2 colors. Whenever you play a card into a slot, also gain the effect of all modules in this slots containing the color of the card.

As mentioned above some cards have a slot symbol at the top or bottom border. if you play those cards with this part visible, you can later play a card in the same slot. The previous cards then works like a slot module, i.e. if it matches the new card, you get it's effect again.

== '''Use your Switch''' ==
On your player board there is a switch. As long as it is unused(the green part is visible) you can use it once to get any resource. The switch will be reset when you hibernate.

With the optional rule "advanced switch action" (introduced during campaign and enabled per default) you can alternatively copy the top effect of the card of another player. The player's card has to played into that a slot with its top part visible. You gain only the effect of that card, not slot modules. However the owner usually benefits as well, since the copied card is then put into their rest area, freeing the slot and coming back with the next hibernation

== '''Explore''' ==
To Explore, choose a facedown area tile which you can reach (you cannot pass through other facedown areas to Explore). Then pay the range (see below) and the cost shown along the top of the tile.

Some areas will show a small location or a water space in the middle (below the cost and above the reward). The front of these tiles will contain a space matching the type shown.

You gain the rewards shown along the bottom of the tile (usually points and a new card). The tile is then flipped face up, and you choose its orientation. (Each tile may be placed in one of two orientations.) Important: If any spaces on the tile you just flipped are adjacent to buildings owned by any player, the owning player now gains the rewards from these spaces.

When you gain a card, you can either pick one from the market or draw a facedown card from the deck. The gained card goes directly to your active area and is immediately available.

The only tiles where you don't get a card are the vast crystals introduced during the campaign

== '''Build''' ==
You have 5 normal building(cost 3 gears) and 3 large buildings(cost 5 gears) that you can build. They can only be built on desert spaces and each desert space can only hold 1 building. In addition to the food you need to pay for range (see below)

You then get bonuses for the spaces adjacent to the building:

* for forest, mountain and field spaces you get 1 advancement on the respective machine track
* for printed crystal spaces you get 1 crystal
* for water spaces you get the depicted bonus as long as you haven't built next to this water space before. You can only get the bonus from each water space once (exception: tribe ability of Hofstadterians moon side)
* for vast crystals (introduced in the campaign) you get 1 crystal and 1 point. Note that these tiles each count as 1 large space.

Large buildings double these rewards, except for the water spaces

If you build next to an unexplored tile, and that tile is explored later, you will then get the bonuses from the spaces placed next to your building, no matter who explored it.

== '''Populate''' ==
On your tribe board there are 7 technologies, that you can unlock by populating with the meeple placed next to them.

The first time you populate, you must use meeple from the bottommost technology. After that you can unlock any technologies that are connected to an already unlocked technology.

You can populate on any city space or large location (5-spaces-tiles at the corners). You have to pay for range (see below) and 2/3/4 books depending on the row the meeple comes from.

Each city and large location can hold 1 meeple from each player, but you have to pay an additional book to each player who is already on the city or large location you populate.

The technologies can be immediate one-time effects, continuous effects, trade actions which can be used any time during your turn or machines.

== '''Hibernate''' ==
Instead of doing 2 main actions, you can hibernate. If you that the following happens:

# All cards in your rest area go to your active area
# All played cards (tucked behind your board) go into your rest area
# Your switch is reset
# You get all used energy back
# You advance on the hibernation track (bottom right of the main board) and get the bonus of the new row or any below. If it was the 4th time you hibernated, you have to choose on artifact still available on the board and discard it

You can still do free action before, after or during the hibernation

== '''Paying for range''' ==
Most actions that happen on the main board require you to pay for range. As long as you have not build or populated you can count range from the starting space at the center.

As soon as you have buildings or meeples on the board you can no longer count range from the starting space. instead you can count range from any building or meeple. Some Tribes have additional stuff they can count range from.

The distance is determined by the number of spaces between the starting point and the target space. You can always take the shortest route, but you cannot count through vast crystals, lakes (expansion only), or unexplored tiles. If the target is a complete tile (for ex. when exploring) the space of that tile with smallest distance counts.

Range is paid with food in the amount of the distance. There are effects that can increase your range (permanently or for 1 action) so that you pay less for the distance.

== '''Machines and the machine track''' ==
On your player board there a machine spaces (Round spaces with a progress marker on it at the start of the game)

They are linked to 1-2 spaces of your machine tracks you once you have reach all linked spaces of a machine you unlock it. You place the progress marker on the next free space of the track that starts at the bottom left of the player board. On some spaces you get a bonus for that(A new energy or an artifact)

The first one of each track is pre-printed. For the others you can choose one of the 3 machines of the respective color from the market.

Machines can be used with energy. You start the game with only 1 energy, but you can gain more (mainly from unlocking progress marker or water spaces) during the game. When using a machine you put an energy token on it.

You can only put 1 energy token each machine. Until you get it back (by hibernating or other effects) you can not use that machine again.

The machine track has other spaces to unlock (hexagonal): On 3 spaces you get an artifact on the other 3 you get 2 points at the end of the game for each card of a certain color that you gained during the game(not counting your start cards)

If you advance beyond the last space of a machine track, you get the respective resource instead.

== '''Tribe abilities''' ==
Each tribe has a special ability at the bottom of their tribe board. Whenever you get the star-symbol somehow (from cards, slot modules or machines) you can execute that ability.

The first 5 times, you do that, remove one of the discs next to it and place it on the track on your player board as described above.

When they are empty you can still use the ability (unless your tribe needs certain tiles/tokens for it that you ran out of), but get no more discs.

== '''Points''' ==
Of course the main goal is to score points. Some points you get during the game (points with a blue marble in the background) and some at the end of the game (purple background). For points during the game you get bonuses when you reach certain spaces on the point track.

You do not get these bonuses when score end-game points.

== '''Artifacts and Artifact cards''' ==
depending on the game variant each player has an artifact card or there is 1 common artifact card for all players.

This card provides points at the end of the game.

For each of the 3 colors count the number of your artifacts of that color '''PLUS 1'''

Then count whatever the part of the card needs and multiply it with that number an with the the depicted points.

For example, if the yellow artifacts score 1 point for each energy and you have 6 energy and 3 yellow artifacts, score 6x4x1=24 points

Whenever you get an artifact choose any available artifact from the board. There no effect that gives you an artifact of a specific color.

The player who takes (or removes) the last artifact also gets the 4-Point token and triggers the game end. After their turn, all '''other''' players get one more turn.

If anyone else would get an artifact now, they get a 2-point token instead.

In the variant "long game" with 4 players 2 additional 2-point tokens are placed on the board that will be taken after the artifacts have been the depleted. The game end is triggered by the 2nd being taken

== '''End of the game''' ==
The game end is triggered when the last artifact is taken (see above). Then each '''other''' player takes one more turn.

At the end of the game each player scores points:

* the lowest visible points on their progress track(see machine tracks)
* points for gained cards if they have unlocked the respective spaces on the machine tracks
* Points from each large location they have populated
* 2/4-point markers (see artifacts)
* points for each 5 remaining resources
* points from the artifacts + artifact card

Ties are broken by the number of unscored resources and then by the total advancement of the machine tracks.

== '''Expansion Rules''' ==
The expansion "Call of the abyss" introduces several new parts:

=== Devotion Points ===
Devotion points are points that have a separate score track. At the end of the game they are just added to your victory points.

'''Whenever you get points or devotion points you can convert all or parts of them in a 2:1 ratio into the other.'''

The devotion track also provides rewards on certain spaces:

on some spaces you get a scyphoz card(see below). You draw 2 and choose which one to keep.

on one space you can populate for free(even if already populated) to a separate large location that is randomly drawn during setup. Normally it would be placed next to the track, but here, in order to save space, it is placed with the player panels (at the top or right of the screen)

That location is scored as usual at the end of the game

=== Scyphoz Cards ===
You get scyphoz cards only by getting devotion points(see above) these cards work like citizen cards, but don't have any of the 3 colors. Instead you can choose their color each round and even at the end of the game(happens automatically here)

They usually have stronger effects than normal citizen cards

=== Journey Cards ===
The switch action now has an additional option. Instead of using it as before, you can now use it to get a journey card. For each journey card you have to destroy (remove from the game) a card of a certain color from your active area.

Once you have it, you can resolve it at any time as a free action. When you do that, you get devotion points according to the level that you fulfilled and the flip the journey card facedown. From now on it counts as an additional flask symbol.

=== Lakes ===
Lakes are tiles that being placed on the board during setup. They cannot be explored.

When you build next to it you immediately get devotion points depending on the building type(1 for normal, 3 for large building) '''if you don't already have a building of that type next to that lake'''

Whenever you hibernate you get the rewards from the right column of the table on each lake if you have at least 1 of the respective building type next to it. Additional buildings of the same type next to it don't provide additional bonuses.

Gamehelpflipseven

2025-06-10T20:38:53Z

Daveoh:

== Overview ==

The deck consists of 94 cards:

* Number cards: Twelve 12's , eleven 11's, ten 10's, and so on... down to one 1. There is also one 0.
* Action cards: Three each of "Flip Three", "Freeze", and "Second Chance"
* Modifier cards: One each of +2, +4, +6, +8, +10, and a multiplier "X2"

Each round, if you do not bust, you will score and bank points equal to the total of card values in front of you. However, if you ever hit and draw a second card with the same number as one already in your line, you bust and are out of the round, scoring zero. (Note that the more valuable a card is, the more copies of it there are in the deck.)

When at least one player reaches 200 points and does not bust, the game will end that round, and the player with the most points wins.

If you Flip 7 unique number cards in a round, you automatically end the round and score 15 bonus points.

== Gameplay ==

Deal one card face up to each player. Then, each player in turn announces '''Hit''' or '''Stay'''.

* If you '''Hit''', you are dealt a card. Number cards go in a line in your player area, and modifier and action cards are placed above your number cards.
* If you '''Stay''', the round is over for you, but you have locked in your score for the round. You now wait until everyone else has either stayed or busted.

The round continues until everyone has chosen to stay or has busted. It also ends immediately if one player can Flip 7 unique number cards, and that player scores 15 bonus points. (Modifier and action cards do not count towards this limit.)

=== Action cards ===

If an '''Action Card''' comes up in dealing, the player who drew it must choose a player (including themselves) to give it to. There are three types of action cards in the game:

* '''Freeze''' forces a chosen player out of the round, though they still score their current cards.

* '''Flip three''' forces a chosen player to draw three cards. Action cards drawn this way are resolved after all three have been drawn. If the chosen player goes bust before the final card is drawn, they skip drawing any more cards.

* '''Second chance''' prevents the player from busting if they draw a duplicate number card. If this happens, the number card and the Second Chance card are both discarded, and the player's turn ends (they do not get to draw another card until their next turn.) A player may hold only one Second Chance card. If they draw another, it must be given to another player.

=== Modifier cards ===

Modifier cards increase the score by their value. For example, a hand of number cards 3, 4, and 12 and a modifier card of +10, gives the player 3+4+12+10 = 29 points.

Note that the x2 multiplier applies only to the base score, not the score after modification. (E.g. 3+4+12 = 19, X2 = 38, +10 modifier = 48.)

== Game End ==
At the end of the round when one or more players has 200 points or more, the player with the most points is the winner.

In the case of a tie, all players continue playing additional rounds until there is one winner.

Gamehelppaxpamir

2024-11-14T10:54:07Z

Daveoh: Coloured text

===Overview===

In Pax Pamir, each player assumes the role of a nineteenth-century Afghan leader attempting to forge a new state after the collapse of the Durrani Empire. Western histories often call this period “The Great Game” because of the role played by the Europeans who attempted to use Central Asia as a theater for their own rivalries

To win the game, have the most victory points after the final Dominance Check is resolved, or have a lead of at least 4 points after any Dominance Check is resolved.

If players are tied for victory points after the final Dominance Check, the player with the most red stars in their court among the tied players wins. If there is still a tie, the player with the most rupees among the tied players wins. If there is still a tie, whoever can cook the best chopan kebab wins.

===Starting Loyalty===

During setup, starting with a random player, each player chooses their starting loyalty. (See "Loyalty and Influence" below.)

After the last player has chosen their starting loyalty, that player will take the first turn. The game is now ready to play.

===Turn===

On your turn, you may take 0-2 actions (plus any free bonus actions) then perform Cleanup.

The three action types are: Purchase, Play, and Card Action:

{|class="wikitable" style="width:auto;" border="2"
|-
! Purchase
| Purchasing cards from the market is done via a skip penalty cost, i.e. the first card is free, if you wish to buy card 2, pay 1 rupee to card 1, if you wish to buy card 3, pay 1 rupee to card 1 and 1 rupee to card 2, and so on. If the card you purchased had rupees from before, you gain these rupees. (If when paying a skip cost, one or more spaces to pay the penalty to is empty, place the payment on the card on the opposite row first.)

If you purchase an event card, this is resolved then discarded, all other cards purchased go into your hand.
|-
! Play
| To play a card, check the region it is associated with. If you are the ruler, or there is no ruler, the card is free to play. If another player is the ruler, they may require you to pay them rupees equal to the number of tribes they have in that region in order to play the card. You may offer any number of rupees up to their number of tribes, including 0. The ruler will then accept or reject the offer. If the full cost is paid, it is automatically accepted. (Depending on the game state, players may wish to help each other out by waiving some or all of the bribe.)

If the criteria to play is met, you must play the card to either the far left or far right of your current Court row.

If the card is a '''Patriot''' which doesn't match your '''Loyalty''', you must change loyalty. See "Loyalty and Influence" below.

Finally, resolve all '''Impact Symbols'''.
|-
! Card Action
| After a card is in your Court, you can take one of the actions it provides. Some cards just provide a single action. However, if a card shows multiple icons, you must only pick one to use each turn.

Some actions are free, only taking an action point, whilst others have additional costs such as rupees.

Spies on cards have to be paid rupees to the owner in order to use them, the cost is equal to the number of spies of the same player. (i.e. if player 2 has 1 spy on card A, and player 3 has 2 spies on Card A, player 1 has to pay player 3 2 Rupees to use an action.)
|}

===Impact Symbols===

A Camel has you place a road coalition block on a border of the card's region

A Jezail has you place an army coalition block on the card's region

A Weighing Scales gives you 2 Rupees and reminds you that the card is Leveraged (see "Cards")

A Cylinder on Card has you place a Spy Cylinder on a matching region card in any player's court

A Crown has you place a Tribe Cylinder on the card's region

All the Suits have you to change the Favoured Suit

===Card Actions===

There are 6 main action types cards may provide

{|class="wikitable" style="width:auto;" border="2"
|-
! Tax
| Take Rupees equal to the card's rank from a player you share a region with (Economic Stars can counter this). If you can't tax another player, you can tax the market.
|-
! Gift
| Place a cylinder on a gift space at increasing cost of 2 then 4 then 6 Rupees
|-
! Build
| Place up to three armies or roads or combination of, at a cost of 2 rupees each
|-
! Move
| Based on the card's rank, gain that many movement points. A movement point moves either an army or spy. If moving a spy, it can move clockwise or counterclockwise from its current position, along the same player's court and even jumping to the next player's court. To move an army, there must be a loyal road on the border to move it from one region to the adjacent region.
|-
! Betray
| For 2 Rupees, discard a card from your or an opponent's court where you have a spy planted. After which, you may accept the discarded card as a Prize or let it be discarded (see "Loyalty and Influence"). This may also trigger the Leverage icon for the original owner.
|-
! Battle
| Pick either a card or a region. Remove tokens at that site equal to the rank of the battle card. Tribes, Spies, Roads, and Armies are all eligible for removal and, if allowed to remove more than one, they can be different. There are a few restrictions to this. You may not remove more than you have Armies or Spies at that site, i.e. a rank 2 battle card with 1 army/spy at the site can still only remove 1 token. Armies and Roads and Tribes of your loyalty are immune to removal (This prevents you weakening your current loyalty before switching loyalties).
|}

===Cleanup===

Check you aren't over Hand or Court Limit

If there are any Event cards in the left-most spot in the Market, discard them and resolve their Impact Event for all Players

If there were any rupees on these cards, they stay lingering in the empty spaces

Move all Market cards to the left, which allows cards to scoop up rupees in empty spaces even if they already had rupees of their own

Draw new Market cards into the now-empty rightmost spots in the Market

If one of the new cards was a Dominance, check to see if it's the only Dominance

If there is another Dominance, complete a Dominance Check, discard all Dominance cards, and draw new cards to fill the spaces

===Dominance Check===

To be successful, a single coalition must have the most blocks in play and four more than any other coalition.

If unsuccessful, the player with the most cylinders in play scores 3 points and the player with second most scores 1 point.

If successful, players in the winning coalition each score points based on how much influence they have. The player with the most scores 5, then 3, then 1. After which, remove all coalition blocks.

The fourth and final dominance check awards double points for every player involved.

In the case of a tie, tied players add up the victory points for the tied places and then divide that number by the number of tied players (rounding down). For example, in a dominance check where there is a winning coalition, if two players both have the second most amount of loyalty, they would each get 2 points (3 + 1 divided by 2).

===Court & Hand Limits===

During your turn, your court can contain any number of cards

However, at end of turn, your court can only have 3 + purple stars quantity of cards, any excess must be discarded

Likewise, your hand can contain any number of cards during the turn

However, at end of turn, your hand can only have 2 + blue stars quantity of cards, any excess must be discarded

===Stars===

★ Economic Stars reduce taxation

★ Military Stars provide a tie-breaker for end game

★ Political Stars increase size of Court

★ Intelligence Stars increase size of Hand

===Loyalty and Influence===

Each player is always loyal to one of the three coalitions, British, Russian, and Afghan. This affects which cards you may want to play into your court. Consider carefully if and when you want to change loyalty, to take advantage of the game state and earn the most victory points.

Your loyalty is important in gaining victory points from Dominance Checks. If you are loyal to the Dominant Coalition when a Dominance Check is resolved, you are eligible to score victory points depending on your amount of influence compared to other players of the same loyalty. (You'll want to be loyal to the right coalition at the right time, which may require changing loyalties during the game.)

You change loyalty whenever you play a Patriot, or gain a prize, of a '''different''' loyalty. The loyalty of a Patriot is determined by the colour and symbol on the banner containing the card's name, or at the bottom of the card when gaining it as a prize. You may reject a prize in order to maintain your current loyalty. When you change loyalty, you lose all patriots, gifts, and prizes you currently have, before gaining the new patriot or prize which caused you to change.

Your influence to your coalition is calculated as 1, plus the number of patriots, prizes, and gifts you have. If you have the most influence in the Dominant Coalition when a Dominance Check is resolved, you will score the most points. (See "Dominance Check" above.)

===Ruling a Region===

To rule a region, you must have one tribe there and more ruling pieces than any other

Once a ruler, you have the following bonuses

• You may take the Build action

• You have Tax Privilege

• You can Extract Bribes

=== Overthrow Rule ===
If you lose your last tribe in a region, all ''Political'' cards you own from that region must be immediately discarded

Likewise, if you lose your last ''Political'' card from a region, you must immediately remove all of your tribes from that region

===Cards===

Cards may have multiple actions on them, but only one of these actions may be taken per turn

If you need to discard a card with a spy, this is returned to its owner

If you need to discard a card with the Leveraged icon, either two rupees or 1 card per rupee owed must be discarded too

If you lose the last tribe in a region, all political cards associated with that region are also discarded

If you lose the last political card associated with a region, all tribes in that region are also discarded

===Suits===

There are four suits in the game, and one suit is always shown as favoured, starting with Political (purple) but this will change throughout the game

{|class="wikitable" style="width:auto;" border="2"
|-
! style="background-color:#ffc" | Economic (Yellow)
| Protect against taxation, manipulate rupees and piece movement
|-
! style="background-color:#fcc" | Military (Red)
| Manage armies and form coalitions
|-
! style="background-color:#fcf" | Political (Purple)
| Consolidate power and determine card playability
|-
! style="background-color:#ccf" | Intelligence (Blue)
| Manage diplomacy and compromise enemies
|}

Whichever suit is currently the Favoured Suit allow those cards to take a single action without counting against the turn's two-action limit

If Military is Favoured, purchasing cost of cards is doubled whilst Favoured

===Game End===

After a Dominance Check, if a player is at least 4 points ahead of everyone else, that player immediately wins

After the fourth Dominance Check card is resolved, the player with the most points wins

If there's a tie, the tie-breakers are: first, most Military stars, second most rupees, third cook a Chopan Kebab and the players vote on who cooked the best meal

Gamehelppaxpamir

2024-11-14T10:50:04Z

Daveoh: Starting loyalty, and loyalty and influence

===Overview===

In Pax Pamir, each player assumes the role of a nineteenth-century Afghan leader attempting to forge a new state after the collapse of the Durrani Empire. Western histories often call this period “The Great Game” because of the role played by the Europeans who attempted to use Central Asia as a theater for their own rivalries

To win the game, have the most victory points after the final Dominance Check is resolved, or have a lead of at least 4 points after any Dominance Check is resolved.

If players are tied for victory points after the final Dominance Check, the player with the most red stars in their court among the tied players wins. If there is still a tie, the player with the most rupees among the tied players wins. If there is still a tie, whoever can cook the best chopan kebab wins.

===Starting Loyalty===

During setup, starting with a random player, each player chooses their starting loyalty. (See "Loyalty and Influence" below.)

After the last player has chosen their starting loyalty, that player will take the first turn. The game is now ready to play.

===Turn===

On your turn, you may take 0-2 actions (plus any free bonus actions) then perform Cleanup.

The three action types are: Purchase, Play, and Card Action:

{|class="wikitable" style="width:auto;" border="2"
|-
! Purchase
| Purchasing cards from the market is done via a skip penalty cost, i.e. the first card is free, if you wish to buy card 2, pay 1 rupee to card 1, if you wish to buy card 3, pay 1 rupee to card 1 and 1 rupee to card 2, and so on. If the card you purchased had rupees from before, you gain these rupees. (If when paying a skip cost, one or more spaces to pay the penalty to is empty, place the payment on the card on the opposite row first.)

If you purchase an event card, this is resolved then discarded, all other cards purchased go into your hand.
|-
! Play
| To play a card, check the region it is associated with. If you are the ruler, or there is no ruler, the card is free to play. If another player is the ruler, they may require you to pay them rupees equal to the number of tribes they have in that region in order to play the card. You may offer any number of rupees up to their number of tribes, including 0. The ruler will then accept or reject the offer. If the full cost is paid, it is automatically accepted. (Depending on the game state, players may wish to help each other out by waiving some or all of the bribe.)

If the criteria to play is met, you must play the card to either the far left or far right of your current Court row.

If the card is a '''Patriot''' which doesn't match your '''Loyalty''', you must change loyalty. See "Loyalty and Influence" below.

Finally, resolve all '''Impact Symbols'''.
|-
! Card Action
| After a card is in your Court, you can take one of the actions it provides. Some cards just provide a single action. However, if a card shows multiple icons, you must only pick one to use each turn.

Some actions are free, only taking an action point, whilst others have additional costs such as rupees.

Spies on cards have to be paid rupees to the owner in order to use them, the cost is equal to the number of spies of the same player. (i.e. if player 2 has 1 spy on card A, and player 3 has 2 spies on Card A, player 1 has to pay player 3 2 Rupees to use an action.)
|}

===Impact Symbols===

A Camel has you place a road coalition block on a border of the card's region

A Jezail has you place an army coalition block on the card's region

A Weighing Scales gives you 2 Rupees and reminds you that the card is Leveraged (see "Cards")

A Cylinder on Card has you place a Spy Cylinder on a matching region card in any player's court

A Crown has you place a Tribe Cylinder on the card's region

All the Suits have you to change the Favoured Suit

===Card Actions===

There are 6 main action types cards may provide

{|class="wikitable" style="width:auto;" border="2"
|-
! Tax
| Take Rupees equal to the card's rank from a player you share a region with (Economic Stars can counter this). If you can't tax another player, you can tax the market.
|-
! Gift
| Place a cylinder on a gift space at increasing cost of 2 then 4 then 6 Rupees
|-
! Build
| Place up to three armies or roads or combination of, at a cost of 2 rupees each
|-
! Move
| Based on the card's rank, gain that many movement points. A movement point moves either an army or spy. If moving a spy, it can move clockwise or counterclockwise from its current position, along the same player's court and even jumping to the next player's court. To move an army, there must be a loyal road on the border to move it from one region to the adjacent region.
|-
! Betray
| For 2 Rupees, discard a card from your or an opponent's court where you have a spy planted. After which, you may accept the discarded card as a Prize or let it be discarded (see "Loyalty and Influence"). This may also trigger the Leverage icon for the original owner.
|-
! Battle
| Pick either a card or a region. Remove tokens at that site equal to the rank of the battle card. Tribes, Spies, Roads, and Armies are all eligible for removal and, if allowed to remove more than one, they can be different. There are a few restrictions to this. You may not remove more than you have Armies or Spies at that site, i.e. a rank 2 battle card with 1 army/spy at the site can still only remove 1 token. Armies and Roads and Tribes of your loyalty are immune to removal (This prevents you weakening your current loyalty before switching loyalties).
|}

===Cleanup===

Check you aren't over Hand or Court Limit

If there are any Event cards in the left-most spot in the Market, discard them and resolve their Impact Event for all Players

If there were any rupees on these cards, they stay lingering in the empty spaces

Move all Market cards to the left, which allows cards to scoop up rupees in empty spaces even if they already had rupees of their own

Draw new Market cards into the now-empty rightmost spots in the Market

If one of the new cards was a Dominance, check to see if it's the only Dominance

If there is another Dominance, complete a Dominance Check, discard all Dominance cards, and draw new cards to fill the spaces

===Dominance Check===

To be successful, a single coalition must have the most blocks in play and four more than any other coalition.

If unsuccessful, the player with the most cylinders in play scores 3 points and the player with second most scores 1 point.

If successful, players in the winning coalition each score points based on how much influence they have. The player with the most scores 5, then 3, then 1. After which, remove all coalition blocks.

The fourth and final dominance check awards double points for every player involved.

In the case of a tie, tied players add up the victory points for the tied places and then divide that number by the number of tied players (rounding down). For example, in a dominance check where there is a winning coalition, if two players both have the second most amount of loyalty, they would each get 2 points (3 + 1 divided by 2).

===Court & Hand Limits===

During your turn, your court can contain any number of cards

However, at end of turn, your court can only have 3 + purple stars quantity of cards, any excess must be discarded

Likewise, your hand can contain any number of cards during the turn

However, at end of turn, your hand can only have 2 + blue stars quantity of cards, any excess must be discarded

===Stars===

★ Economic Stars reduce taxation

★ Military Stars provide a tie-breaker for end game

★ Political Stars increase size of Court

★ Intelligence Stars increase size of Hand

===Loyalty and Influence===

Each player is always loyal to one of the three coalitions, British, Russian, and Afghan. This affects which cards you may want to play into your court. Consider carefully if and when you want to change loyalty, to take advantage of the game state and earn the most victory points.

Your loyalty is important in gaining victory points from Dominance Checks. If you are loyal to the Dominant Coalition when a Dominance Check is resolved, you are eligible to score victory points depending on your amount of influence compared to other players of the same loyalty. (You'll want to be loyal to the right coalition at the right time, which may require changing loyalties during the game.)

You change loyalty whenever you play a Patriot, or gain a prize, of a '''different''' loyalty. The loyalty of a Patriot is determined by the colour and symbol on the banner containing the card's name, or at the bottom of the card when gaining it as a prize. You may reject a prize in order to maintain your current loyalty. When you change loyalty, you lose all patriots, gifts, and prizes you currently have, before gaining the new patriot or prize which caused you to change.

Your influence to your coalition is calculated as 1, plus the number of patriots, prizes, and gifts you have. If you have the most influence in the Dominant Coalition when a Dominance Check is resolved, you will score the most points. (See "Dominance Check" above.)

===Ruling a Region===

To rule a region, you must have one tribe there and more ruling pieces than any other

Once a ruler, you have the following bonuses

• You may take the Build action

• You have Tax Privilege

• You can Extract Bribes

=== Overthrow Rule ===
If you lose your last tribe in a region, all ''Political'' cards you own from that region must be immediately discarded

Likewise, if you lose your last ''Political'' card from a region, you must immediately remove all of your tribes from that region

===Cards===

Cards may have multiple actions on them, but only one of these actions may be taken per turn

If you need to discard a card with a spy, this is returned to its owner

If you need to discard a card with the Leveraged icon, either two rupees or 1 card per rupee owed must be discarded too

If you lose the last tribe in a region, all political cards associated with that region are also discarded

If you lose the last political card associated with a region, all tribes in that region are also discarded

===Suits===

There are four suits in the game, and one suit is always shown as favoured, starting with Political (purple) but this will change throughout the game

{|class="wikitable" style="width:auto;" border="2"
|-
! style="background-color:#ffc" | Economic (Yellow)
| Protect against taxation, manipulate rupees and piece movement
|-
! style="background-color:#fcc" | Military (Red)
| Manage armies and form coalitions
|-
! style="background-color:#fcf" | Political (Purple)
| Consolidate power and determine card playability
|-
! style="background-color:#ccf" | Intelligence (Blue)
| Manage diplomacy and compromise enemies
|}

Whichever suit is currently the Favoured Suit allow those cards to take a single action without counting against the turn's two-action limit

If Military is Favoured, purchasing cost of cards is doubled whilst Favoured

===Game End===

After a Dominance Check, if a player is at least 4 points ahead of everyone else, that player immediately wins

After the fourth Dominance Check card is resolved, the player with the most points wins

If there's a tie, the tie-breakers are: first, most Military stars, second most rupees, third cook a Chopan Kebab and the players vote on who cooked the best meal

Main game logic: Game.php

2024-09-21T18:21:55Z

Daveoh: /* Notifications */

{{Studio_Framework_Navigation}}

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

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

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

== File Structure ==

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

Here is the basic structure:

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

== Accessing player information ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Accessing the database ==

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

'''IMPORTANT'''

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

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

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

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

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

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

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

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

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

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

</pre>

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

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

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

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

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

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

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

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

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

Result:
[
'myuser0',
'myuser1'
]

</pre>

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

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

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

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

<pre>

</pre>

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

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

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

The keys are strings, so you might want to store them in constants to avoid mistakes (the key must be at maximum 50 characters long).

The variable can be of any type (number, string, array, object) and will be stored as a JSON (so functions cannot be stored, and circular references on objects will trigger an Exception when storing).

Having a string key and a JSON serialization allows you to debug easily by looking at the bga_globals table content.

''Note: this globals module doesn't use cache, so every call to one of the following methods makes a DB request.''

'''globals->set(string $name, $mixed $obj): void'''

Define the value of a global variable.
<pre>
const FIRST_PLAYER_ID = "firstPlayerId";
$this->globals->set(FIRST_PLAYER_ID, array_keys($players)[0]);
</pre>

'''globals->get(string $name, $mixed $defaultValue = null): mixed'''

Get the value of a global variable. Returns `null` if not set, except specified otherwise in the optional `$defaultValue`.
<pre>
$currentFirstPlayerId = $this->globals->get(FIRST_PLAYER_ID);
...
$selectedCardsIds = $this->globals->get(SELECTED_CARDS_IDS, []);
</pre>

'''globals->getAll(...$names): array'''

Get the value of all global variables, as a key=>value array. You can set a list of names to only get matching variables. In that case, non-existent keys will not be set in the returned array, so if you have a key with null value, it means the key has been set to null previously.
<pre>
$variables = $this->globals->getAll();
...
$diceVariables = $this->globals->getAll(DIE1, DIE2);
</pre>

Use with PHP's [https://www.php.net/extract extract()] function to quickly assign multiple variables:
<pre>
extract($this->globals->getAll('endTime', 'hour', 'vipWelcome'));
// $endTime, $hour, and $vipWelcome (may) now exist

if (!empty($endTime)) {
...
</pre>

'''globals->delete(...$names): void'''

Delete a global variable or a list of global variables stored in database.
<pre>
$this->globals->delete(SELECTED_CARDS_IDS);
...
$this->globals->delete(SELECTED_CARDS_IDS, UNDO, AFTER_DISCARD_RETURN_STATE);
</pre>

'''globals->has(string $name): bool'''

Indicates if a global variable is stored in database.
<pre>
$cardSelectionIsStarted = $this->globals->has(SELECTED_CARDS_IDS);
</pre>

'''globals->inc(string $name, $int $inc): int'''

Increments the value of a global variable, and return the incremented value. Will trigger an exception if the variable is not a numeric value.
<pre>
$this->globals->inc(PLAYED_ACTIONS_IN_CURRENT_TURN, 1);
...
$totalSpent = $this->globals->inc(SPENT_COINS_IN_CURRENT_TURN, $cardCost);
</pre>

== Use globals (numbers only / game options) ==

Before the `$this->globals`, you could only store numeric values as globals. Theses "GameStateValues" are stored in the "global" table in the database, and you can access it with simple methods.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== BGA predefined globals ===

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

{| class="wikitable"
|-
! global_id !! label !! Meaning
|-
| 1 || || Current state
|-
| 2 || || Active player id
|-
| 3 || next_move_id || Next move number
|-
| 4 || || Game id
|-
| 5 || || Table creator id
|-
| 6 || playerturn_nbr || Player turn number
|-
| 7 || gameprogression || Game progression
|-
| 8 || initial_reflexion_time || Initial reflection time
|-
| 9 || additional_reflexion_time || Additional reflection time
|-
| 200 || reflexion_time_profile || Game speed
Real-time games:
* 0 = Real-time • Fast paced
* 1 = Real-time • Normal speed
* 2 = Real-time • Slow speed
* 9 = No time limit • with friends only

Turn-based games:
* 10 = Fast Turn-based • 24 moves per day
* 11 = Fast Turn-based • 12 moves per day
* 12 = Fast Turn-based • 8 moves per day
* 13 = Turn-based • 4 moves per day
* 14 = Turn-based • 3 moves per day
* 15 = Turn-based • 2 moves per day
* 17 = Turn-based • 1 move per day
* 19 = Turn-based • 1 move per 2 days
* 20 = No time limit • with friends only
|-
| 201 || bgaranking_mode || Game mode
* 0 = Normal mode
* 1 = Friendly mode (no ELO)
* 2 = Arena mode
|-
| 207 || game_language ||GAMESTATE_GAME_LANG
|-
| 300 || game_db_version ||GAMESTATE_GAMEVERSION: Current version of the game (when in production)
|-
| 301 || game_result_neutralized ||GAMESTATE_GAME_RESULT_NEUTRALIZED
|-
| 302 || neutralized_player_id ||GAMESTATE_NEUTRALIZED_PLAYER_ID
|-
| 304 || undo_moves_stored ||GAMESTATE_UNDO_MOVES_STORED
|-
| 305 || undo_moves_player ||GAMESTATE_UNDO_MOVES_PLAYER
|-
| 306 || lock_screen_timestamp ||GAMESTATE_LOCK_TIMESTAMP
|}

== Game states and active players ==

=== Activate player handling ===

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

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

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

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

=== Multiple activate player handling ===

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

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

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

This is to be used in state declaration:
<pre>
2 => array(
"name" => "playerTurnPlace",
"description" => clienttranslate('Other player must place ships'),
"descriptionmyturn" => clienttranslate('${you} must place ships (click on YOUR SHIPS board to place)'),
"type" => "multipleactiveplayer",
'action' => 'stMakeEveryoneActive',
'args' => 'arg_playerTurnPlace',
"possibleactions" => array( "actionBla" ),
"transitions" => array( "next" => 4, "last" => 99)
),
</pre>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Private parallel states ===

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

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

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

$this->gamestate->setAllPlayersMultiactive();
$this->gamestate->initializePrivateStateForAllActivePlayers();

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Inactive Players ====

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

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

== Actions (autowired) ==
The action function should be prefixed by "act" and match the names specified in the "possibleactions" field on the state file.

If your actions start with "act", they will be autowired, that means you can declare action functions on the game.php file and call them directly from the front (with bgaPerformAction). You don't need to use action.php file anymore. The query param from the front request will be matched with the PHP variable of the same name, and it needs to be properly typed. This works for basic types: int, bool, float, string.

<pre>
public function actPlayCard(int $cardId) { ... }
</pre>
This function can be called from front-side with
<pre>
this.bgaPerformAction('actPlayCard', {
cardId: this.selectedCardId // the "cardId" param match the PHP variable name
});
</pre>

(Note: if you also declare the function in the action.php, it will be used instead of the autowiring)

If you want more complex types like int array or JSON, you'll need to specify it using the Param attributes. Same if the PHP variable name is different from the front query param, or if you want to specify the tests that should be realized on the parameter before calling the function.

=== Possible attributes ===

'''BoolParam(?string $name = null)'''
<pre>
use \Bga\GameFramework\Actions\Types\BoolParam;

...

public function actRaiseBet(#[BoolParam(name: 'raise')] bool $raiseBet)

public function actRaiseBet(#[BoolParam(name: 'raise')] bool $raise) // NOTE: it's the same as actRaiseBet(bool $raise) if PHP var name and param name are the same
</pre>

'''IntParam(?string $name = null, public ?int $min = null, public ?int $max = null)'''
<pre>
use \Bga\GameFramework\Actions\Types\IntParam;

...

public function actPlayCard(#[IntParam(name: 'id')] int $cardId)

public function actSpendGold(#[IntParam(min: 1)] int $gold) // will trigger an exception if param is < 1

public function actPlaceCardOnSpot(int $cardId, #[IntParam(min: 1, max: 5)] int $spot) // will trigger an exception if spot is not in 1 to 5 range
</pre>

'''FloatParam(?string $name = null, public ?int $min = null, public ?int $max = null)'''

Works the same way as IntParam, import is <code>use \Bga\GameFramework\Actions\Types\FloatParam;</code>

'''StringParam(?string $name = null, public ?bool $alphanum = false, public ?bool $alphanum_dash = false, public ?bool $base64 = false, public ?array $enum)'''
<pre>
use \Bga\GameFramework\Actions\Types\StringParam;

...

public function actSubmitWord(#[StringParam(alphanum: true)] string $word) // will trigger an exception if the word is not alphanum

public function actChooseAction(#[StringParam(enum: ['move', 'attack', 'pass'])] string $action) // will trigger an exception if the parameter doesn't match a value in the enum
</pre>
Note: You should do one of the tests of the attribute, or test it yourself on the function, to unsure the user is not sending forbidden characters to the function.

'''IntArrayParam(?string $name = null, public ?int $min = null, public ?int $max = null)'''
<pre>
use \Bga\GameFramework\Actions\Types\IntArrayParam;

...

public function actDiscardCards(#[IntArrayParam] array $ids)

public function actDiscardCards(#[IntArrayParam(min: 2, max 8)] array $ids) // will trigger an exception if the array length is not in the 2 to 8 range. It doesn't check the min/max of the array values!
</pre>

This function can be called from front-side with
<pre>
const selectedCardIds = [8, 12, 25];
this.bgaPerformAction('actDiscardCards', {
ids: selectedCardIds.join(',')
});
</pre>

'''JsonParam(?string $name = null, public ?bool $associative = true, public ?bool $alphanum = true)'''
<pre>
use \Bga\GameFramework\Actions\Types\JsonParam;

...

public function actPlanComplexStuff(#[JsonParam] array $answer) // force conversion to array during PHP json decode
public function actPlanComplexStuff(#[JsonParam(associative: false)] object $answer) // force conversion to object during PHP json decode

public function actPlanComplexStuff(#[JsonParam(associative: null)] mixed $answer) // default PHP json decode
</pre>

=== checkAction ===
The autowiring also triggers the checkAction, so you don't have to call it at the beginning of the function. If you need a function that should not trigger checkAction an action that can be played during someone else turn), you can disable it this way:
<pre>
use \Bga\GameFramework\Actions\CheckAction;

...

#[CheckAction(false)]
public function actSetAutopass(bool $autopass)
</pre>

If you disable checkAction, you probably need to call checkPossibleAction instead at the beginning of your function.

=== act prefix ===
The act prefix needed to activate the autowiring is not just to have some consistency in naming, it's also intended to protect your code. If we let autowired action to any function, a player may do a request to 'setPlayerScore' function, even if you never intended for it to be called front side, and it would allow almost undetectable cheating for anyone reading the code of your game.

== Players turn order ==

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

'''getNextPlayerTable()'''

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

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

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

'''getPrevPlayerTable()'''

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

'''getPlayerAfter( $player_id )'''

Get player playing after given player in natural playing order.

'''getPlayerBefore( $player_id )'''

Get player playing before given player in natural playing order.

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

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

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

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

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

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

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

== Notifications ==

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

'''IMPORTANT'''

Notifications are crutial part of BGA framework. Everything which players see, including all changes which happen on frontend (including setup), are done via notfications.

Some notifications are built into the framework, and others are custom, game specific notifications. Generally, you should not send or handle framework notifications, except exposed APIs.

Example of framework notifications:
* game setup (first time client connects to game)
* game state change
* active player change
Example of custom notifications:
* game piece moved
* player scored points

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

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

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

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

There are conceptually two types of notification:
* public - sent to all clients who are listening - that includes all players in the table as well as spectators
* private - sent only to a single player

The bundle of notifications sent at the end of an action is considered a single "move" and the table's move counter increases.
If you are ONLY sending private notifications during action handling, they will not have an associated <code>move_id</code> (to avoid this, add simple public notification with empty message).
In the rare case that you want to change this behavior, you can apply some hackery described in [[BGA_Studio_Cookbook]]

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

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

=== NotifyAllPlayers ===

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

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

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

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

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

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

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

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

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

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

Complete notifyAllPlayers example (from "Reversi"):

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

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

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

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

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

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

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

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

==== HTML in Notifications ====

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

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

==== Recursive Notifications ====

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

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

==== Excluding some players ====

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

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

==== Using player names ====

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

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

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

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

=== NotifyPlayer ===

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

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

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

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

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

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

== Randomization ==

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

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

=== Dice and bga_rand ===

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

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

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

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

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

=== Arrays ===

PHP's [https://www.php.net/array_rand array_rand()] and [https://www.php.net/shuffle shuffle()] functions are not cryptographically secure. Instead, the following code based on PHP's [https://www.php.net/random_int random_int()] provides a better method to choose a random key, value, or slice of an array. (the slice preserves keys)

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

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

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

=== shuffle and cards shuffling ===

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

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

=== Other methods ===

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

== Game statistics ==

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

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

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

Create a statistic entry with a default value.

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

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

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

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

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

Set a statistic $name to $value.

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

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

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

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

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

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

== Translations ==

See [[Translations]]

== Manage player scores and Tie breaker ==

=== Normal scoring ===

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

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

Examples:
<pre>

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

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

</pre>

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

=== Tie breaker ===

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

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

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

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

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

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

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

=== Co-operative game ===

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

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

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

=== Semi-coop ===

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

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

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

Examples:
* Coup
* Not Alone
* Werewolves
* Quantum

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

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

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

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

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

=== Solo ===

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

=== Player elimination ===

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

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

Usage:

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

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

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

=== Scoring Helper functions ===

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

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

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

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

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

== Reflexion time ==

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

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

== Undo moves ==

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

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

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

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

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

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

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

== Managing errors and exceptions ==

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

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

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

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

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

== Zombie mode ==

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

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

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

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

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

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

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

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

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

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

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

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

== Player color preferences ==

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

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

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

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

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

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

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

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

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

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

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

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

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

== Legacy games API ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

If you met the following situation:

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

Then, you must use the following method:

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

player_id = player who write the text

text = text that has been written

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

== Language dependent games API ==

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

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

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

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

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

== Debugging and Tracing ==

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

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

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

== PHP 8 upgrade ==

See [[PHP 8 upgrade]]

[[Category:Studio]]

Gamehelptickettorideeurope

2023-12-31T15:18:37Z

Daveoh: Added a lot more info

== Beginning of the Game ==

Players start the game with four train cards in their hand. Before taking their first turn, players must choose which Destination Tickets they will keep from among those they were initially dealt. Each player must keep a minimum of two tickets although they may keep more. Put any Destination Tickets you wish to discard back in the game box without letting any of the other players see them. The Tickets that are put away may either be long routes or regular ones. The tickets you decide to keep are held until the end of the game.

== Game End ==

Each player starts the game with 45 train cars in their player color. When any one player’s stock of colored plastic trains gets down to two trains or less at the end of their turn, each player, including that player, gets one final turn. The game then ends and players calculate their final scores.

== Object of the Game ==

Points can be scored by:

<ol style="
margin:1em 0;
padding-inline-start:40px;
">
<li style="list-style-type:decimal;">'''Claiming a Route''' between two adjacent cities on the map</li>
<li style="list-style-type:decimal;">Successfully '''completing a Continuous Path of routes''' between two cities listed on your Destination Ticket(s)</li>
<li style="list-style-type:decimal;">Completing the '''Longest Continuous Path''' of routes to win the European Express Bonus card ('''+10 points''', ties are friendly)</li>
<li style="list-style-type:decimal;">For each unused '''Train Station''' kept in '''reserve''' at the end of the game ('''+4 points each''')</li>
</ol>

Points are deducted from the players’ total score for each of their Destination Tickets that are not successfully completed by the end of the game.

== Player Turn ==

On each turn, the active player must perform one (and only one) of the following four actions:

<ol style="
margin:1em 0;
padding-inline-start:40px;
">
<li style="list-style-type:decimal;">'''Draw Train Car Cards''' – The player may draw two Train cards (or just one, if the card they select is a face-up Locomotive)</li>
<li style="list-style-type:decimal;">'''Claim a Route''' – The player claims a route on the board by playing a set of Train cards from their hand that match the color and quantity of the spaces that make up the route. They place one of their colored trains on each space, and score the number of points indicated on the Route Scoring Table for that route’s length</li>
<li style="list-style-type:decimal;">'''Draw Destination Tickets''' – The player draws three Destination Tickets from the top of the Tickets deck, and must keep at least one of them</li>
<li style="list-style-type:decimal;">'''Build a Train Station''' – The player may build a Station in any city that does not yet have one. To build their first Train Station, the player plays one Train card of any color and places one of their Train Stations on that city. To build their second station, the player must play a set of two cards of the same color, and to build their third station, a set of three cards of the same color. Only one station is allowed per city.</li>
</ol>

== Scoring points from routes ==

When a player claims a route, they immediately score the number of points indicated for the length of the route just claimed.

{|class="wikitable" style="width:auto;" border="2"
! Route Length !! Points Scored
|-
| 1 🚃 || 1
|-
| 2 🚃🚃 || 2
|-
| 3 🚃🚃🚃 || 4
|-
| 4 🚃🚃🚃🚃 || 7
|-
| 6 🚃🚃🚃🚃🚃🚃 || 15
|-
| 8 🚃🚃🚃🚃🚃🚃🚃🚃 || 21
|}

== Double-Routes ==

Some cities are connected by Double-Routes. These are routes whose spaces are parallel and equal in number from one city to the other. One player can never claim both routes between the same cities during the course of the game.

Be aware of routes that are partially parallel to each other but are linked to different cities. These are not double-routes.

{{infoBox
|title={{player|=2}} {{player|=3}} Two or three player variant
|body=In two or three player games, only one of the Double-Routes can be used. A player can claim either of the two routes between cities, but the other route is then closed to the other players for the remainder of the game.
}}

== Locomotives ==

Locomotives are multi-colored train cards, and act as a wild colored train card. Locomotive cards can be played along with any set of cards when claiming a route. They are also vital to claiming Ferry routes (see Ferries).

== Ferries ==

Ferries are special Gray routes linking two adjacent cities across a body of water. They are easily identified by the Locomotive icon(s) featured on at least one of the spaces making the route.

To claim a Ferry Route, a player must play a Locomotive card for each Locomotive symbol on the route, and the usual set of cards of the proper color for the remaining spaces of that Ferry Route.

== Tunnels ==

Tunnels are special routes that are easily identified by the special tunnel marks and outlines surrounding each of their spaces.

When attempting to claim a Tunnel route, a player first lays down the number of cards required by the length of the route. Then the top three cards from the Train Card draw pile are turned face-up. For each card revealed whose color matches the color of the cards played to claim the Tunnel, an additional card of the same color (or a Locomotive) must now be played from their hand. Only then can the player successfully claim the Tunnel route.

If the player does not have enough additional Train cards of the matching color (or does not wish to play them), they take all their cards back in their hand, and their turn ends.

At the end of the turn, the three Train cards revealed for the Tunnel are discarded.

== Train Stations ==

A Train Station allows its owner to use one, and only one, of the routes belonging to another player, into (or out of) that city to help them connect the cities on their Destination Tickets.

Stations may be built on any unoccupied city, even if it currently has no claimed routes into it. Two players may never build a Station in the same city.

Each player may build a maximum of one Station per turn, and three Stations throughout the course of the game.

To build their first Station, a player plays and discards one Train card from their hand, and places one of their colored Train Stations on the chosen city. To build a second Station, the player must play and discard a set of two cards of any one color; and to build their third station, a set of three Train cards of any one color. As usual, you can replace any number of cards by Locomotives.

If a player uses the same Station to help connect cities on several different Tickets, they must use the same route into the city with the Station for all of those Tickets. The Train Station owner does not need to decide which route they will use until the end of the game.

A player is never required to build any Stations. For each Station a player has not used, four points are added to their score at the end of the game.

Gamehelpastra

2023-04-11T15:45:33Z

Daveoh: Final scoring - only active constellations are scored for their shown value

In Astra, great gods, legendary heroes and magical creatures live in the night sky’s Constellations. You and your fellow players will take on the role of astronomers to discover and bring them to life.

On your turn, you will collect and spend Stardust to mark stars, discover and collect Constellations, and earn various Boons and Abilities granted by the discovered Constellations. Additionally, you will also gain points for your efforts in exploring the night sky. Whoever has the most points by the end of the game wins.

== Gameplay ==
On your turn, you can activate abilities then you must choose between observing or resting.

At the beginning of your turn, you can activate any abilities depicted on your unexhausted Constellations, in any order. Once you have used an ability, the corresponding Constellation is exhausted.

''Note: Exhausted Constellations can be reactivated by the Rest action or with a Boon of Reactivation.''

=== Observing ===
When Observing, you can spend stardust to mark stars of undiscovered Constellations, spending 1 stardust per marked star.

If there were no marked stars on the undiscovered Constellation you want to observe, you must first mark the Constellation's starting star. If there were, your first marked star can be any star adjacent to a previously marked star. Then, you may mark an additional star that is adjacent to the star you have marked immediately before it. You may continue marking adjacent stars as long as they are directly connected with a single white line to the star you have just marked and you have Stardust to spend.

Whenever you mark a Grand star, you instantly gain 1 Wisdom. Wisdom will allow you to have more discovered Constellations.

You may take additional Observe actions, at the cost of spending 1 telescope token per extra Observe action.

=== Resting ===
When resting, first you must take as much stardust from the general supply as you need so that you end up with as much stardust as the current size of your Pouch.

Then, you must reactivate your discovered Constellations which have the element symbol matching the position of the marker on the active sphere.

Finally, the element marker moves to the next element symbol, in clockwise order.

=== Discovery Phase ===
At the end of your turn, if you had marked the last remaining star on Constellations, those are considered discovered. If multiple Constellations are discovered, you can choose in which order they are resolved.

Any other player who helped discovering the card, by previously marking stars on it, can pick one of the boons depicted at the bottom of the discovered card, starting from the player who had marked the most stars, then in descending majority order. A boon cannot be picked again if another player already picked it earlier.

You, who discovered the Constellation by marking the last star, do not get to pick a boon. Instead, you place the Constellation card face-up in front of you, giving you an ability to use in future turns. New Constellations are drawn from the deck to replace any discovered card.

If you end up having more Constellations than what your Wisdom limit allows, you must discard down to your Wisdom.

== Game end and final scoring ==
The game ends when the Constellation draw pile is emptied. If the first player triggers the endgame, everyone else play one last turn. If someone else triggers it, you then take turns until it is the first player’s turn, finishing the current round. Then, every player takes one last turn in one final round.

You then score points for:

* Pouch size: score points equal to the number above the rightmost marking on the Pouch size track
* Card limit: score points equal to the highest number marked on the Wisdom track
* Leftover Stardust: score 1 point for every third stardust remaining in your Pouch
* Marked stars: score 1 point for every second star you have marked across all the undiscovered Constellations
* Active Constellations: score points equal to the Final Scoring value shown on each of your Active Constellation Cards
* Element sets: for each element type you have constellations for, score 2/6/11 if you have 2/3/4 cards with the same element symbol. Also, score 6 points for each set of 4 different elements or 3 points for each set of 3 different elements
** Note: you start the game with 2 random elements for final scoring purposes, represented by the +

== Additional Rules for 2 players ==
When you play Astra with 2 players, a dummy 3rd player (Dreamer) is added, which marks undiscovered constellations when a player rests.

==== Rest ====
On the round marker, there is a number from 1 to 4. When a player rests, they must mark with the Dreamer color a number of stars on an undiscovered Constellation equal to the round marker number. The logic for selecting the stars is as follows:

* If there is a Constellation that has no marked stars yet, you must mark that one (if 2 or more are tied, current player picks).
* If all the undiscovered Constellations have at least 1 marked star on them, select the one with the highest number of stars (if 2 or more are tied, current player picks).

==== Discovery ====
If a constellation is is discovered, and the Dreamer dummy player finished the Constellation, no player receives the card. If the Dreamer did not receive the Constellation but had more stars marked than the player who did not receive the Constellation, the Dreamer always takes the 2 left boons.

Gamehelptzolkin

2020-08-06T12:07:35Z

Daveoh: Typo and rewording

Rules are here: http://czechgames.com/files/rules/tzolkin-rules-en.pdf

(A picture of all 18 Age II buildings: https://i.imgur.com/BOGVhXA.jpg )

== '''For Each Round''' ==

- Each player takes their turn, going around the table

- On a food day, feed your workers and take your rewards

- Advance the Calendar

== '''Player turn''' ==

- '''Beg for corn:''' If you have 2 or less corn, you may beg for corn unless you are at the bottom step of all three temples. (Turn in all corn, take 3 corn and move one step down on any temple)

- '''Either place workers OR pick up workers'''

-- ''Placing workers'': pay corn for the number of workers you place. The cost for the number of workers you place is 0, 1, 3, 6, 10, or 15 for, respectively, 1, 2, 3, 4, 5, or 6 workers placed on that turn, plus the cumulative cost noted next to each of your placed workers.

-- ''Picking up Workers'': You may pick up one or more of your placed workers. For each worker picked up either

--- Use the action where your worker was standing

--- Use a lower action on the wheel from where your worker was standing(if not
standing on a free action space,pay 1 corn for each step back)

--- Do nothing.

== '''Food Day''' ==

-'''Feed the Workers''' Each players must pay 2 corn for each worker they have in play (on a gear or in front of you) with the exception for any farms you own. You must feed as many workers as you have corn for.
-- For each worker not fed, you lose 3 points

-'''Take Rewards'''

--''Middle of Age (Brown days)''

--- Receive items shown on the left edge of temples from step you are on and all steps below

-- ''End of Age (Teal Days)''

--- Remove all Age 1 buildings and fill spaces with Age 2 buildings

--- Receive points shown on the right edge of temples for the step you are on.

--- Bonus points on each temple track for the player whose marker is highest. Bonus amount is shown above each temple. For ties, everyone receives half the bonus.

== '''Advance the Calendar''' ==

If there is no worker on the starting player space, place a corn on the current Tzolk'in gear tooth and advance the gear one day.

Otherwise:

- The worker on the Starting Player space returns to the player

-- If this person was not the starting player, they take the starting player marker.

-- If they were the starting player, the starting player marker is moved to the player on his left

- Advance the Tzolk'in Gear one day.

- The player that placed their worker on the Starting Player space may decide to advance the gear one extra day if the player board is light side up AND this advance will not push a player off the gears.

-- If you use this option, flip your board to dark side up.

-- This does not avoid food days.

== '''See also''' ==

[[Tips_tzolkin|Strategy Tips]]