Board Game Arena - User contributions [en]

Gamehelpgroundfloor

2026-08-10T07:51:33Z

BaronFraser: Created page with "= Ground Floor = ''A game for 1–5 players, by David Short.'' '''Ground Floor''' is a worker-placement / time-management game in which one to five players take on the role of Entrepreneurs running a young start-up company. Players spend their limited time (Time markers) to manage their business, aiming to become the CEO of the most prestigious company by earning the most Prestige Points. == Introduction == In '''Ground Floor''' one to five players adopt the role of..."

= Ground Floor =

''A game for 1–5 players, by David Short.''

'''Ground Floor''' is a worker-placement / time-management game in which one to five players take on the role of Entrepreneurs running a young start-up company. Players spend their limited time (Time markers) to manage their business, aiming to become the CEO of the most prestigious company by earning the most Prestige Points.

== Introduction ==

In '''Ground Floor''' one to five players adopt the role of Entrepreneurs responsible for the survival of their young start-up company. As CEO, a player will use their limited time to manage their business. Time is money, so they have to spend it wisely!

Does a player need to hire staff or refine production? What about launching a marketing campaign? Anything is possible with effective use of time, money, and information. But in order to reach that corner office of your skyscraper, a player has to start with everybody else… at the '''Ground Floor'''!

The goal is to become the CEO of the most prestigious company by accruing the most prestige points through expanding and improving your business.

=== The Game Board ===

The game board three tracks near the top-left corner, from top to bottom: the '''Rounds''' track, the '''Job Market''' track, and the '''Popularity''' track.

Near the top-right corner of the board the players find two spaces to place '''Economic Forecast''' cards – in the left box the current card is placed, the right box holds the deck of future cards.

From left to right there are various buildings with spaces where players may put their Time markers. These buildings are numbered '''A''' ('''Consulting Firm''') to '''I''' ('''Construction Company''').

=== The Player Boards ===

Each player has a player board.

On the left side are the six basic rooms which each player has in their company: Assembly, Training, Storage Closet, Meeting Room, Research & Testing, and Advertising. Each room lists what the players may do in it. To the right of the rooms is the Round Schedule, plus some Notes and reminders.

On the right side is the '''Employee Track''', where the CEO Marker and time markers track the size of your staff.

The Specialty Tile of each company and added Floors are placed in the notch at the center of the board.

=== Supply Cubes and Status Markers ===

Supply Cubes are necessary to produce goods. They may be stored in a player's Storage Closet and are often acquired in the Warehouse.

The Status Markers are placed in the starting spaces of the Rounds and Job Market tracks.

=== A Player's Components ===

In addition to a Player Board, each player receives, in their chosen player color, a CEO Marker, 2 Player markers, and 25 Time Markers.

=== The Cards ===

''Ground Floor'' includes 20 Economic Forecast Cards.

== Set Up ==

# The players place the game board on the table.
# Each player chooses a color to represent their business in the game and takes 1 CEO marker, 2 Player markers, and 4 Time markers in their chosen color. In addition, each player takes 1 player board, 1 player aid, 7 [Info] and 1 Supply cube. They also take, ''at random'', 1 Specialty tile and the Remodeled Room tile (or another advantage) awarded by their Specialty tile (see also chapter [[#Specialty Tiles|Specialty Tiles]]). They place the Specialty tile at the top of their player board, the Remodeled Room (if any) tile over the corresponding Ground Floor room, the Supply marker in their Storage Closet and the CEO together with 4 Time markers on their first space of the Employee track. The players place the remaining Money tokens, Info tokens, Time markers, Remodeled Room tiles, Untrained tokens and Supply cubes within easy reach of all players to create a General Stock.
# The players place one Status marker on the first space of the Rounds track.
# The players place one Status marker on the sixth space marked "5 / 5" of the Job Market.
# One player takes one Player marker of each player and stacks them, ''randomly'', on the first space of the Popularity track. The topmost Player marker determines the start player for the first Round.
# The players now separate the Economic Forecast cards into four piles (Depression, Recession, Stable and Boom). They shuffle each pile separately, then randomly discard half of the cards in each pile and put these back into the box (unseen) as they will not be needed in the game. Then, the players shuffle all 10 remaining cards together and place the deck face down on the ''Future'' Economic Forecast space on the game board. Then, they move the top card face down to the ''Current'' Economic Forecast space.
# The players stack one Player marker of each player on the "No Bonus" space of the Marketing Bonus track; the order does not matter.
# The players place one Supply cube on each of the four spaces of the Warehouse.
# The players place the Stage 1 [Stage 1] Floor and Tenant Improvement tiles next to the Construction Company area of the game board. They place all the Stage 2 [Stage 2] and Stage 3 [Stage 3] Improvement tiles off to the side.
# For the first games, the players should place bonus components back into the box (2 new Economic Forecast cards "Great Depression" and "Windfall", 5 Era cards, and 6 Event cards).
# The game is now ready to begin!

'''IMPORTANT NOTE:''' The players never start the game with the top card of the Economic Forecast deck being a Depression or Boom. If this occurs, they continue shuffling until a Recession or Stable card is the top card.

'''SUGGESTION FOR THE FIRST GAME:''' Instead of a random Economic Forecast deck, the players may choose to use a pre-set deck in order to ensure a less harsh economy. Shuffle each type of card separately. Then, construct the deck in this order (top to bottom), and put the remaining cards back in the box, they will not be needed:

: Stable, Stable, Recession, Recession, Stable, Boom, Recession.

'''NOTE (Improvement tiles):''' In a 2 or 3 player game, only one copy of each Improvement tile is available to purchase. Return additional copies of each Improvement tile to the box, they will not be needed.

== Game Play ==

Ground Floor is played over '''seven rounds''', divided in '''three stages''' [Stage 1], [Stage 2], [Stage 3]. Each round consists of five phases. Per phase, players will conduct several player turns.

These five phases form a round:

# '''Receive Income'''
# '''Hire Employees'''
# '''Schedule Business'''
# '''Conduct Business'''
# '''Reorganize'''

In each phase, turn order is determined by the position of the companies on the Popularity track. The most popular player/company, whose Player marker is ''furthest to the right'' on the track, goes first etc. If more than one player is on the same space, the Player Marker ''on top'' goes first.

'''Ground Floor''' ends after the '''Conduct Business''' phase of the seventh round has been completed.

'''IMPORTANT:''' Each time the rules describe costs or income, we will use the icons for all the different terms in this game. Please check the Player Aids for reference.

=== I – Receive Income ===

Players receive Money according to the location of their CEO marker on the Employee track. Some Improvements provide additional Money or Information during this phase.

If a player has hired an employee, they must pay 3 [Money] during this phase. If the player cannot afford to do so, they ''have to'' fire an employee, discarding 3 [Time] and moving the CEO marker down one space on the Employee track.

: ''EXAMPLE: Marion already hired an employee, and now receives an income of 6 [Money].''

=== II – Hire Employees ===

Players have the opportunity during this phase to hire new employees. In popularity order, each player may hire an employee at the current Job Market price. They move the Job Market Status marker to the right after each employee is hired (max. 7 [Money] / 7 [Info]).

Once all players have had the opportunity to hire, the most popular player may hire again and so forth. This continues until all players have finished hiring employees.

For each new employee that a player hires, they immediately move their CEO marker up on the Employee track to reflect the new size of their staff and place an Untrained [Untrained] token on the new employee's space next to the CEO.

'''IMPORTANT NOTE:''' The Time markers of an untrained employee are not available for use. The player gains these Time markers at start of the next round after the employee is trained, see [[#Ground Floor Rooms|Ground Floor Rooms]].

: ''EXAMPLE: Marion hires her second employee. She pays 5 [Money] / 5 [Info] and moves her CEO to the second space of her Employee track and places an [Untrained] token next to the CEO. As this employee is untrained, she gets the 3 [Time] after she trained that employee. She moves the Job Market Status marker to the right.''

=== III – Schedule Business ===

Players spend this phase scheduling their Time markers and investing in tasks. Players only have a finite amount of time to spend developing their business.

The CEO is a business' first employee, and provides 4 [Time]. Each additional ''trained'' employee provides 3 [Time].

During the Schedule Business phase, in Popularity order, players take turns assigning Time markers to tasks on their Player board ''or'' on the Game board. Time markers may ''not'' be assigned to Player boards belonging to other players.

On a player's turn they choose any ''one'' task and assign the number of Time markers from their Employee track indicated by that task. For tasks with multiple spaces for Time markers, the player must place their Time markers in the first available space in ''numerical order'' if spaces are marked.

If spaces are not marked with numbers, the player may place ''anywhere''.

Later, during '''Conduct Business''', ''all'' locations are resolved from top to bottom.

* See chapter [[#City Business|City Business]] for details of the tasks at these buildings.
* See chapter [[#Ground Floor Rooms|Ground Floor Rooms]], chapter [[#Tenant Improvements|Tenant Improvements]], and chapter [[#Floor Improvements|Floor Improvements]] for details of tasks.

Play then continues with the next most popular player etc., until each player has assigned all of the Time markers on their Employee track. Since each player may have a different number of employees, the same player may end up taking several turns in a row once their opponents have spent all of their time.

* Tasks on the Player board resolve ''immediately'', therefore any benefit gained from these tasks may be used in upcoming turns during the current Schedule Business phase.
* All tasks on the Game board will be resolved during the '''Conduct Business''' phase.

'''IMPORTANT NOTE:''' In contrast to the tasks on the Game board, the Ground Floor Rooms on a Player Board are unlimited. This means that they can be used over and over again during the same Schedule Business phase, placing the indicated number of Time markers each time.

: ''EXAMPLE: As her first action Marion pays 6 [Money] and places 1 [Time] from her Employee track on the first space of the Consulting Firm. Only later during the '''Conduct Business''' phase, Marion will resolve this action. Later during her turn, she places 1 [Time] from her Employee track in the Meeting Room of her Player board and immediately receives 1 [Info].''

=== Office Remodel ===

At any time during the Schedule Business phase, a player may remodel their Ground Floor rooms on the Player Board. Remodeling does ''not'' require any Time markers and is done in addition to their turn. The cost to remodel each Ground Floor room is 3 [Money] / 3 [Info]. After paying this cost, the player takes the desired Remodeled Room tile from the General Stock and places it on top of the corresponding Ground Floor room on their Player board. The benefit of a Remodeled room is available immediately, and has no effect on Time markers already assigned to that room.

: ''EXAMPLE: During the Schedule Business phase Marion decides to remodel her Ground Floor Training room. She pays 3 [Money] / 3 [Info] and places the remodeled Training room on that space. She can immediately use that room.''

=== IV – Conduct Business ===

During this phase, each area on the Game board is resolved in order:

# Consulting Firm
# Advertising Agency
# Marketing Bonus
# Warehouse
# Factory
# Stock Exchange
# Economic Forecast
# Retail Outlets
# Construction Company

See chapter [[#City Business|City Business]] for details of the tasks at these buildings.

=== V – Reorganize ===

The following steps are resolved in order during each Reorganize phase:

# All players move any Time markers from their Player board to the General Stock. Time markers on the Game board remain there, if not otherwise mentioned in chapter [[#City Business|City Business]].
# Each player in Popularity order may downsize, moving their CEO marker down one space for each employee fired. When firing an employee, the player loses Time markers and discards the matching 3 [Time] for that fired employee.
# All players replenish their Time markers according to their Employee track, even if some of their Time markers remain on the Game board.
# Move all the Player markers on the Marketing Bonus track to the "No Bonus" space.
# Add one Supply marker to the ''most expensive empty'' space at the Warehouse. If all of the spaces at the Warehouse are full, no markers are added.
# All Player markers on the Popularity track are moved one space to the left, one by one, in reverse popularity order. Player markers stacked in the same space will move together, keeping the order of the stack intact. Any Player marker in the leftmost space does not move.
# Update the Job Market by moving the Status marker to the left according to the ''Unemployed'' line on the current Economic Forecast card (min. 2 [Money] / 2 [Info]).
# Move the top card of the Future Economic Forecast deck ''face down'' to the Current Economic Forecast space.
# Move the Round Status marker one space to the right.
# At the end of the second round, add the [Stage 2] Improvement tiles to those remaining at the Construction Company. At the end of the fifth round, add the [Stage 3] tiles as well.

A new round is ready to begin.

== Game End ==

The game ends after the Conduct Business phase of the seventh round has been completed.

At that point, all players add up the Prestige Points [PP] for all Remodeled Rooms, Tenant Improvements, Floors, and Achievement Floors. They also count an additional 1 [PP] for each full set of 3 [Money] / 3 [Info].

The winner is the player with the most prestigious business, as measured by Prestige Points. In case of a tie, the most popular tied player (according to the Popularity track) wins.

== City Business ==

=== A – Consulting Firm ===

'''SCHEDULE BUSINESS:''' Players schedule business at the Consulting Firm for the opportunity to gain [Info] by placing 1 [Time] in the topmost available space in the left column and paying the indicated amount of [Money] for that space.

'''CONDUCT BUSINESS:''' All players with Time markers in the right column receive [Info] ''if and only if'' the corresponding space in the ''left'' column is occupied. Players with Time markers in the right column ''without'' the corresponding space in the left column occupied have had their meetings cancelled and do not receive any info. Move all Time markers from the right column to the General Stock, then slide all Time markers from the left column to the right column.

: ''EXAMPLE: During the Schedule Business phase, Angelika has two Time markers and Marion has 1 Time marker in the right column from the previous round. This round, Tanja and Angelika have both placed 1 Time marker in the Consulting Firm during the Schedule Business phase. Tanja paid 5 [Money] and Angelika paid 6 [Money].''
: ''During the Conduct Business phase, Angelika collects 20 [Info], but Marion gets nothing because there is no Time marker in the third space of the left column. All three Time markers from the left column are returned to the General Stock, and the Time markers from the right column slide over to the right column.''

=== B – Advertising Agency ===

'''SCHEDULE BUSINESS:''' Players schedule business at the Advertising Agency to boost their business' Popularity. It costs 1 [Money] / 1 [Info] to place 1 [Time] in any available space.

'''CONDUCT BUSINESS:''' This area resolves from top to bottom. The player with a Time marker in the top space will decide first which type of Marketing they wish to do. The player with the Time marker in the bottom space will get the advantage of choosing last.

The types of Marketing available are: Networking, Social Media, and Broadcast. Only one type may be chosen for each Time marker placed in the Advertising Agency.

* If Networking is chosen, then the player moves their 1 [Time] from the Advertising Agency to the Networking space. In addition they place 1 [Time] from the General Stock into the Networking space at no additional cost.
* If Social Media is chosen, then the player moves their 1 [Time] from the Advertising Agency to the Social Media space at an additional cost of 1 [Money] / 1 [Info].
* If Broadcast is chosen, then the player moves their 1 [Time] from the Advertising Agency to the Broadcast space at an additional cost of 2 [Money] / 2 [Info].

After players have decided where to place their Time markers, each marketing type is resolved one at a time as follows. Resolve Networking for all players first, then Social Media, then Broadcast.

For each marketing type, in popularity order, advance each player's Popularity marker once for every:

* 3 [Time] in Networking
* 2 [Time] in Social Media
* 1 [Time] in Broadcast

Advance the player's Popularity marker one additional space if that player had the ''single most'' Time markers in that marketing type. If multiple players are tied for the most Time markers, none of them receive this additional Popularity boost.

'''IMPORTANT NOTE:''' For each Marketing type, after all Time markers are accounted for and the Popularity track adjusted accordingly, move all Time markers that contributed to advancing in Popularity (including all Time markers of the player with the ''single most'') to the general stock. Any excess Time markers remain at the Advertising Agency and may contribute to Marketing in future rounds.

: ''EXAMPLE: While conducting business, first Networking is resolved. Marion advances first as she is the most popular. Marion advances one space on the Popularity track for 3 [Time]. Nikki is next most popular, and advances two spaces (one for having 3 [Time], and another for having the most Time markers in Networking). Angelika only has 1 [Time], and therefore does not advance in Popularity.''
: ''Next, Social Media is resolved: Angelika only has 1 [Time], which is not enough to advance in Popularity, so she does have the most Time markers in Social Media, so she does advance one space.''
: ''Finally, Broadcast is resolved: Tanja has 1 [Time], which meets the requirement for Broadcast and is the most Time markers there, so Tanja advances 2 spaces on the Popularity track.''
: ''All Time markers are returned to the General Stock, except for Angelika's Time marker in the Networking box. It did not contribute to Popularity, so it remains in the Networking box for next round.''

=== C – Marketing Bonus ===

'''SCHEDULE BUSINESS:''' The Marketing Bonus area is not available to players during the Schedule Business phase.

'''CONDUCT BUSINESS:''' In Popularity order, each player, except the least popular, chooses a Marketing bonus. Bonuses are awarded immediately, and each bonus may be chosen by only one player.

'''Marketing bonuses:'''

* Remodel 1 Room (for 1 [Money] / 1 [Info])
* Supply: Gain 1 [Supply]
* Money: Gain 2 [Money]
* Information: Gain 2 [Info]
* Temp: Gain 1 [Time] for the next round

'''IMPORTANT:''' In a 2-player game Marketing Bonuses are ''not'' used. Neither player will receive a Marketing Bonus, no matter how popular they are.

=== D – Warehouse ===

'''SCHEDULE BUSINESS:''' Players schedule business at the Warehouse in order to acquire new supplies. These supplies vary in cost. Players choose to spend [Money] or [Info] (never both) to place on any available space.

'''CONDUCT BUSINESS:''' Players collect the [Supply] next to their Time markers. When a player acquires a new [Supply], they must have a place to store it on their Ground Floor. If no storage space in their Storage Closet is available, then the [Supply] must be discarded back to the General Stock.

=== E – Factory ===

'''SCHEDULE BUSINESS:''' Players schedule business at the Factory to create products to sell at the Retail Outlets. Players pay 2 [Money] / 2 [Info] and 1 [Supply] to place 1 [Time] in the first available space in numerical order.

'''CONDUCT BUSINESS:''' In numerical order, players move their Time markers representing products from the Factory to Retail Outlets. At this time they have the opportunity to set the price for the product they are selling. There are four different price brackets, separated by a white line.

Later, the customers will purchase the products within the least expensive price bracket before buying products within a more expensive price bracket.

Player icons [3 players] and [4 players] dictate how many spaces are available at the Retail Outlets for the number of players in the game. For instance, in a 3-player game, players may place Time markers up to and including the spaces marked with the [3 players] on it, but not on spaces marked with the [4 players]. On each space, only one player can place a Time marker. If Retail Outlets become completely full while resolving the Factory, further Time markers may be placed in the Liquidation space, where they ''immediately'' sell for 3 [Money].

: ''EXAMPLE: During the Schedule Business phase, Angelika placed first, and Nikki last.''
: ''The Conduct Business phase resolves by moving from the Factory to Retail Outlets. Marion has a leftover Time marker from the previous round.''
: ''Angelika resolves first and picks the 8 [Money] space. Tanja picks the 12 [Money] space, Nikki chooses the 8 [Money] space, Angelika chooses the 12 [Money] space and finally Nikki chooses the 9 [Money] space.''

=== F – Stock Exchange ===

'''SCHEDULE BUSINESS:''' Players schedule business at the Stock Exchange to get [Money]. Players pay [Money] and/or [Info] to place 1 [Time] on any of the four spaces.

'''CONDUCT BUSINESS:''' All Time markers placed during Schedule Business move up into the Stock Exchange track one space at a time. This movement is ''not'' related to the Economic Forecast. Therefore the Time marker in the first space moves up, then the Time marker in the space below etc., follow the arrows from box to box. Each time a new Time marker enters the track, it pushes all the Time markers directly above them one space up.

Then, all Time markers on the Stock Exchange track, including the ones that just entered, move up according to the current Economic Forecast:

* '''Depression:''' 0 spaces
* '''Recession:''' 1 space
* '''Stable:''' 2 spaces
* '''Boom:''' 3 spaces

Finally, in Popularity order, each player with at least one Time marker on the Stock Exchange track decides whether to keep or remove any number of their Time Markers. Any Time marker that is kept on the track will stay there for the next round. Any Time marker that is removed will gain the player a multiple amount of [Money] according to the current Economic Forecast. Gaps are possible on the track due to this removal.

* '''Depression:''' 0 [Money]
* '''Recession:''' 1 [Money]
* '''Stable:''' 2 [Money]
* '''Boom:''' 3 [Money]

Each time a Time marker is pushed above the topmost space, the player ''has'' to '''Buy Out''' this Time marker and gets twice the amount of money according to the current Economic Forecast.

: ''EXAMPLE: During the Schedule Business phase, Nikki places a Time marker on the first space, and Tanja in the third space.''
: ''Marion and Nikki have Time markers in the Stock Exchange from the previous round. During the Conduct Business phase, first Nikki moves her Time marker onto the first space of the Stock Exchange, then Tanja, whose Time marker both pushes Nikki's and Marion's Time markers one space up.''
: ''The current Economic Forecast is "Stable", so all Time markers move 2 spaces up.''
: ''Finally, Nikki decides to remove both her Time markers to get 12 [Money]. Both Marion and Tanja decide to keep their Time Markers on the Stock Exchange.''

=== G – Economic Forecast ===

'''SCHEDULE BUSINESS:''' This area is not available to players during the Schedule Business phase.

'''CONDUCT BUSINESS:''' Once the Stock Exchange is completely resolved, reveal the Economic Forecast card in the ''current'' space.

=== H – Retail Outlets ===

'''SCHEDULE BUSINESS:''' Retail Outlets are not available to players during the Schedule Business phase.

'''CONDUCT BUSINESS:''' According to the Economic Forecast card, a number of consumers will buy products at the Retail Outlets based on the number of players in the game. Each consumer is attracted to the best deal, and will therefore buy from the businesses in the lowest price bracket. Within the lowest bracket, each consumer will purchase from the most popular business in that bracket. For each product sold, the player receives [Money] as printed on the space, removes the matching Time marker from the Retail Outlet, and places it back into the General Stock.

This continues until all consumers have bought one product each or all products have been sold, whichever comes first.

Any remaining Time markers at the Retail Outlets (representing products that did not sell) drop down to any lower price bracket (including Liquidation), from the lowest price bracket up, in Popularity order within a bracket. Players may choose which price within the new bracket to place their Time marker on. Any Time marker dropping into the Liquidation space immediately sells for 3 [Money].

: ''EXAMPLE: During the Conduct Business phase, the revealed Economic Forecast card is a "Stable", which brings 3 Consumers in this 4-player game.''
: ''The first consumer buys Angelika's product from the lowest price bracket for 8 [Money], as Angelika is the most popular. Marion is the next most popular player with a product in the lowest bracket, so the second consumer buys Marion's product for 6 [Money]. Nikki is the only player left with products in the lowest price bracket, so the third customer will buy her cheapest product for 6 [Money].''
: ''After the third consumer has bought, three products remain in the Retail Outlets. From the lowest price bracket up, those products drop in price. First, Nikki's product drops from 8 [Money] to the Liquidation box and sells immediately for 3 [Money]. Then, since Angelika is more popular than Tanja, Angelika's 12 [Money] product drops to a lower price bracket. Angelika may choose to set the new price at 8 [Money], 6 [Money] or Liquidation for 3 [Money] right now. Finally, Tanja must choose a new price (8 [Money], 6 [Money] or Liquidation) as well.''

=== I – Construction Company ===

'''SCHEDULE BUSINESS:''' Players schedule business at the Construction Company in order to expand their business with a new Improvement. Players pay 5 [Money] and 1 [Info] to place 1 [Time] in the first available space in numerical order. Player icons [3 players], [4 players] and [5 players] dictate how many spaces are available for the number of players in the game. For instance, in a 4-player game, players place Time markers up to and including the spaces marked with the [4 players] on it, but not on the space marked with [5 players].

'''CONDUCT BUSINESS:''' In numerical order, each player has the option of buying an available Improvement. Starting with space 1, a Tenant Improvement can be bought for 7 [Money] / 1 [Info], or a Floor Improvement can be bought for 7 [Money] plus 2 [Money] / 2 [Info] per existing Floor on a Player's Player board. Players pay the cost for their chosen Improvement, add it to their Player board, and move their Time marker to the General Stock. Floors are placed on top of their building (move the Specialty tile up to make space), and Tenant Improvements replace a Ground Floor room or may be placed on an Empty Floor tile.

See chapter [[#Tenant Improvements|Tenant Improvements]] and chapter [[#Floor Improvements|Floor Improvements]] for details of their tasks.

'''NOTE:''' Players start with the Ground Floor and the Specialty tile; they are not purchased. Additionally, the Specialty tile is not considered to be a floor!

: ''EXAMPLE: Angelika's building consists of the following floors. During the game, she paid the following costs for each floor:''
:: A – Ground Floor: Not purchased
:: B – 2nd Floor: costs 4 [Money] / 4 [Info]
:: C – 3rd Floor: costs 6 [Money] / 6 [Info]
:: D – 4th Floor: costs 8 [Money] / 8 [Info]
:: E – 5th Floor: costs 10 [Money] / 10 [Info]
:: F – 6th Floor: costs 12 [Money] / 12 [Info]
:: G – Specialty tile: Not purchased

== Ground Floor Rooms ==

Each player can use these six rooms on their Player boards. During the game, each Player can remodel any of their rooms to get access to upgraded benefits.

When one or more Time Markers are required, all required Time markers must be placed at once. Once the Time marker requirement has been met, all Ground Floor Rooms provide their respective benefit immediately. These rooms have unlimited use.

Each remodeled Ground Floor Room is worth 2 [PP] at the end of the game.

=== Advertising ===

; STANDARD : Place 1 [Time] on Advertising to place 1 [Time] from the General Stock into the Networking box at the Advertising Agency.
; REMODELED : Place 1 [Time] on Advertising to place 1 [Time] from the General Stock into the Networking box at the Advertising Agency OR place 2 [Time] on Advertising to place 1 [Time] from the General Stock into the Social Media box at the Advertising Agency.

=== Assembly ===

; STANDARD : Place 3 [Time] on Assembly to acquire 1 [Supply]. A newly acquired [Supply] must have a place in the Storage Closet to be stored or it is discarded.
; REMODELED : Place 2 [Time] on Assembly to acquire 1 [Supply]. A newly acquired [Supply] must have a place in the Storage Closet to be stored or it is discarded.

=== Meeting Room ===

; STANDARD : Place 1 [Time] on the Meeting Room to gain 1 [Info].
; REMODELED : Place 1 [Time] on the Meeting Room to gain 1 [Info], or place 2 [Time] on the Meeting Room to gain 3 [Info].

=== Research & Testing ===

; STANDARD : Place 1 [Time] on Research & Testing and spend 1 [Supply] from your Storage Closet to gain 3 [Info].
; REMODELED : Place 1 [Time] on Research & Testing and spend 1 [Supply] from your Storage Closet to either gain 4 [Info] or gain 2 [Money] / 2 [Info].

=== Storage Closet ===

; STANDARD : Store 1 [Supply] indefinitely with no time cost.
; REMODELED : Store up to 2 [Supply] indefinitely with no time cost. When remodeling the Storage Closet, the remodeled Storage Closet comes into play with 1 new [Supply] on it.

=== Training ===

; STANDARD : Place 2 [Time] on Training to remove 1 [Untrained] token from your Employee track. The Time markers for this trained employee are available for use at the start of the next round.
; REMODELED : Place 1 [Time] on Training to remove 1 [Untrained] token from your Employee track. The Time markers for this trained employee are available for use at the start of the next round.

== Tenant Improvements ==

There are two of each regular Tenant Improvement tile, and only one Tenant Improvement Achievement tile.

'''IMPORTANT NOTE:''' In a 2 or 3 player game, only one copy of each Tenant Improvement tile is available for purchase.

When players expand their business with a new Tenant Improvement, they can either place it on an "Empty Floor" Improvement space or on top of another room. This other room (either a previous Tenant Improvement or a Ground Floor room) becomes inaccessible to the Player; its ability cannot be used nor can it be remodeled. However, its Prestige Points will still count at the end of the game.

Each regular Tenant Improvement tile is worth 3 [PP] at the end of the game. Respectively, the Tenant Improvement Achievement tile is worth 1 [PP], but grants additional bonus Prestige Points.

=== Stage 1 – Tenant Improvements [Stage 1] ===

; Human Resources : During the Hire Employees phase of each round, Human Resources allows the owner to hire at a discount of 3 [Money] / 3 [Info], to a minimum cost of 1 [Money] / 1 [Info]. ''EXAMPLE: Marion already owns the Human Resources office, when she hires her third employee. Instead of paying the actual costs for hiring of 5 [Money] / 5 [Info], she only needs to pay 2 [Money] / 2 [Info].''

; Internship Program : During the Receive Income phase of each round, the owner of Internship Program receives 1 additional [Time]. This 1 [Time] does not count as an employee and therefore does not affect the Employee Track or the player's Money income. This 1 [Time] functions exactly the same as any other [Time] in the game.

; Network Admin : During the Receive Income phase of each round, the owner of Network Admin receives an additional 2 [Info].

=== Stage 2 – Tenant Improvements [Stage 2] ===

; Niche Market : During the Conduct Business phase of each round, the owner of Niche Market is not required to drop the price of any of their products that do not sell at the Retail Outlets. This ability is optional and may be applied to one or more of the owner's products.

; Premium Product : The owner of Premium Product receives an additional 2 [Money] for each product sold at the Retail Outlets. This includes any Liquidated products.

; Public Relations : During the Reorganize phase at the end of each round, the owner of Public Relations does not move their Player marker down on the Popularity track.

=== Stage 3 – Tenant Improvements [Stage 3] ===

; Tenant Improvement Achievement : At the end of the game, the owner of Tenant Improvement Achievement scores an additional 1 [PP] for each Tenant Improvement they have purchased, including Tenant Improvement Achievement.

== Floor Improvements ==

There are two of each regular Floor Improvement tile, only one of each Achievement Floor tile.

'''IMPORTANT NOTE:''' In a 2 or 3 player game, only one copy of each Floor Improvement tile is available for purchase.

When players expand their business with a new Floor, they place it above their Ground Floor, below their Specialty Tile. Each subsequent Floor will be placed above the last one etc.

Each Floor Improvement tile is worth between 2 [PP] and 8 [PP] at the end of the game, as written on the different tiles. Most Achievement Floor tiles also grant additional bonus Prestige Points.

In the first stage of the game, only Stage 1 [Stage 1] Improvements are available. Beginning in the third round, the Stage 2 [Stage 2] Improvements become available, and beginning with the sixth round, the Stage 3 [Stage 3] Improvements become available as well.

Players may purchase one Improvement per Time marker in the Construction Company, and may never build an Improvement already on their Player board. If a player cannot afford to or chooses not to buy an Improvement, they simply move their Time marker to the General Stock.

=== Stage 1 – Floor Improvements [Stage 1] ===

; Empty Floor : The Empty Floor comes with one ''free'' Tenant Improvement of the owner's choice. The Tenant Improvement must be from the Stages currently available for purchase next to the Construction Company area of the game board. The Tenant Improvement is placed on one of the two spaces on the Empty Floor tile. The second space may be filled with another Tenant Improvement purchased at a later time.

=== Stage 2 – Floor Improvements [Stage 2] ===

; Assembly Line : Place 1 [Time] on Assembly Line to acquire 1 [Supply]. A newly acquired [Supply] must have a place to be stored in the Storage Closet or it is discarded. Assembly Line may be used a maximum of two times each round.

; Conference Room : Place 2 [Time] on Conference Room to gain 3 [Info]. Conference Room may be used a maximum of two times each round.

; Construction Admin : Place 3 [Time] on Construction Admin to place 1 [Time] from the General Stock in the next available space at the Construction Company. Construction Admin may be used a maximum of three times each round.

; In-House Factory : Place 2 [Time] on In-House Factory and spend 1 [Supply] from your Storage Closet to place 1 [Time] from the General Stock in the next available space at the Factory. In-House Factory may be used a maximum of two times each round.

; Investor : During the Receive Income phase of each round, the owner of Investor receives an additional 3 [Money].

; I.T. Department : During the Receive Income phase of each round, the owner of I.T. Department receives an additional 4 [Info].

; Marketing Department : Place 2 [Time] on Marketing Department to place 1 [Time] from the General Stock into the Broadcast box at the Advertising Agency. Marketing Department may be used a maximum of three times each round.

; Online Store : Place 3 [Time] on Online Store and spend 1 [Supply] from your Storage Closet to gain 6 [Money]. Online Store may be used a maximum of two times each round.

; Research Lab : Place 1 [Time] on Research Lab and spend 1 [Supply] from your Storage Closet to gain 3 [Money] / 3 [Info]. Research Lab may be used a maximum of three times each round.

; Telecommunications : Place 1 [Time] on Telecommunications to gain 1 [Info]. Telecommunications may be used a maximum of three times each round.

=== Stage 3 – Floor Improvements [Stage 3] ===

; Corner Office Achievement : Corner Office Achievement is worth 8 [PP].

; Corporate Merger Achievement : Corporate Merger Achievement is worth 8 [PP].

; Executive Achievement : At the end of the game, the owner of Executive Achievement scores additional 2 [PP] for each "Achievement" Floor Improvement they have purchased, including Executive Achievement.

; Improvement Achievement : At the end of the game, the owner of Improvement Achievement scores additional 1 [PP] for each Remodeled Room on their Ground Floor. Tenant Improvements do not count toward this bonus.

; Marketing Achievement : At the end of the game, the owner of Marketing Achievement scores additional 2 [PP] for each Popularity level they have attained. The Popularity track has three levels, divided by vertical black lines.

; Office Renovation : Place 2 [Time] on Office Renovation to remodel 1 Ground Floor room. Place the Remodeled Room tile over the Ground Floor room on the Player board. Office Renovation may be used a maximum of 3 times each round.

; Production Achievement : At the end of the game, the owner of Production Achievement scores additional 3 [PP] for each Supply in their Storage Closet.

; Retention Achievement : At the end of the game, the owner of Retention Achievement scores additional 1 [PP] for each employee in their staff, according to the CEO marker on the Employee track. It does not matter if the employees have been trained.

; Skyline Achievement : At the end of the game, the owner of Skyline Achievement scores additional 1 [PP] for each Floor Improvement they have purchased, including Skyline Achievement.

== Specialty Tiles ==

The players start the game with one of these Specialty tiles, giving them different advantages.

The Specialty tiles always are on top of the players' buildings, representing the type of company controlled by the players. These Specialties are not considered to be floors and do ''not'' affect the costs for new Floor Improvements.

; E-Commerce : The owner of this specialty starts each round with 1 additional [Time]. However, this player does not start the game with any Ground Floor rooms remodeled.

; Emerging Technology (Research & Testing Room Speciality) : The owner of this specialty starts the game with the remodeled Research & Testing Room tile and places that tile on their Player board.

; Industrial (Assembly Room Speciality) : The owner of this specialty starts the game with the remodeled Assembly Room tile and places that tile on their Player board.

; Inheritance : The owner of this specialty starts the game with an additional 3 [Money] / 1 [Info], for a total of 3 [Money] / 8 [Info]. However, this player does not start the game with any Ground Floor rooms remodeled.

; Non-Profit (Training Room Speciality) : The owner of this specialty starts the game with the remodeled Training Room tile and places that tile on their Player board.

; Publishing (Advertising Room Speciality) : The owner of this specialty starts the game with the remodeled Advertising Room tile and places that tile on their Player board.

; Retail (Storage Closet Speciality) : The owner of this specialty starts the game with the remodeled Storage Closet Room tile and places that tile on their Player board. Remember: A remodeled Storage Closet comes with a free [Supply], which means this player starts the game with 2 [Supply].

; Web Based (Meeting Room Speciality) : The owner of this specialty starts the game with the remodeled Meeting Room tile and places that tile on their Player board.

== Automa Rules ==

'''Ground Floor''' may also be played by 1 to 3 players by adding 1 or 2 Automas, competitive Entrepreneurs who are played by the game itself.

All of the base game set up and game rules apply, with the following modifications.

'''NOTE''': In the BGA adaptation, Automata may only be played in solo games, and at least 1 Automata ''must'' be selected in every solo game.

=== Automa Set Up ===

# Set up the game for the number of players playing, including any Automas. For example, if there is 1 human and 1 Automa, then set the game up for 2 players.
# Choose an Entrepreneur to represent each Automa. These Automas have different difficulty levels: ''Pei'' is easy, ''Gropius'' medium, and ''Hadid'' is hard to beat. By default, each Automa places its CEO on the first space on the Employee track and places four Time markers next to that CEO. ''Hadid'' also gets one of the Internship Program Tenant Improvements. When playing with 2 or 3 players, use the extra copy in the box, so the other Internship Program is available in the General Stock. This means that Hadid's CEO plays with 5 Time markers for the entire game.
# The players create each default Automa deck as follows: 1× Consulting Firm, 1× Advertising Agency, 1× Warehouse, 1× Factory, 1× Stock Exchange, 1× Construction Company. ''Hadid'' starts with an extra Factory in her deck. ''Pei'' starts with one Automa Office card in his deck. ''Gropius'' does not start with any additional cards in his deck. Place the remaining cards sorted by type into the General Stock.
# An Automa receives the ''E-Commerce'' Specialty, other Automas receive Specialty randomly.
# An Automa always starts as the first player. Randomize the player order for remaining humans and other Automas.

=== Automa Conventions ===

An Automa always follows the base game rules, with the following modifications.

==== During the Whole Game ====

* An Automa never keeps or gains any [Money], or [Info], or [Supply]. It has an unlimited pool of each of those.
* An Automa starts each round with a thoroughly shuffled deck.
* An Automa never activates any abilities of its floors or Tenant Improvements during the game.
* At the start of Stage 3 [Stage 3], add an extra Construction Company card into each Automa deck.
* When an Automa remodels or gains a Tenant Improvement, it does not matter where it goes, because Automas do not activate abilities anyway.
* If an Automa deck is ever exhausted during a turn, reshuffle its cards and continue the round.

==== I) Receive Income ====

* An Automa never receives income.

==== II) Hire Employees ====

* ''Pei'' never hires employees.
* ''Hadid'' never hires employees.
* ''Gropius'' hires if the Job Market is at 7 [Money] / 7 [Info]. If Gropius hires, shuffle an extra Factory card into his Automa deck. Afterwards, Gropius never hires again.

==== III) Schedule Business ====

* When an Automa takes its turn, turn over the topmost card of its deck and by default place 1 [Time] on the best available space of the building specified on the revealed Automa card.
* '''F)''' When placing at the Stock Exchange, an Automa places 1 [Time] on a space in this priority: 1 [Money], then 1 [Money] / 1 [Info], then 1 [Info] / 2 [Money] and finally 1 [Info].
* When an Automa's turn is over, discard all revealed Automa cards into a discard pile. Note, each Automa will have their own individual deck and discard pile.

==== IV) Conduct Business ====

* '''B)''' When resolving the Advertising Agency, turn over the next Automa card and reference the bottom left corner to see what type of marketing is done.
* '''C)''' If a Marketing Bonus is awarded, an Automa takes bonuses in this priority: Remodel, Temp, Supply, Money, Info.
* '''E)''' When resolving the Factory, if all products are guaranteed to sell, then the Automa will place its 1 [Time] on the Retail Outlet at the highest price available. Otherwise, for each Automa Time marker turn over the next Automa card and reference the bottom right corner to see what type to place in.
* '''F)''' When resolving the Stock Exchange, an Automa only sells during Boom, Stable, or at a Buy Out. It stays in otherwise.
* '''I)''' When resolving the Construction Company, an Automa always buys a random Floor from the current stage during Boom and Stable. Otherwise it will buy a random Tenant Improvement from the current stage in all other economies. If an Automa goes to the Construction Company more than once in the same round, then in all subsequent visits it will buy a random Tenant Improvement from the current stage.
* '''I)''' When resolving the Construction Company during Stage 3, an Automa will always buy a random Achievement Floor from Stage 3 with each and every Time marker.
* Each time an Automa buys a Floor or Tenant Improvement, shuffle an extra Automa Office card into its deck.
* If an Automa reveals an Automa Office card on its turn, simply put 1 [Time] anywhere on its player board. It does not matter where it goes, because Automas do not activate abilities anyway.

==== End of the Game ====

* An Automa scores Prestige Points like any other player. When scoring their Achievement Floors, score them as if they are maxed out.

== Bonus: Era Cards ==

Before the game begins, the players shuffle the Era cards and choose one at random. The chosen Era will direct the construction of the Economic Forecast deck for the game.

== Bonus: New Economic Forecast Cards ==

The players may add these cards as desired. Check chapter [[#Set Up|Set Up]], bullet point 6 for details.

=== Great Depression ===

During the construction of the Economic Forecast deck, before shuffling each type of card, replace one Depression card with Great Depression. ''This means Great Depression might not be in the final deck.'' During a Great Depression there will be no customers, therefore no products will sell at the Retail Outlets. In addition, unemployment is at its highest, so during Reorganize the Status marker at the Job Market is moved all the way to the left (to the 7 [Money] / 7 [Info] space).

=== Windfall ===

During the construction of the Economic Forecast deck, before shuffling each type of card, replace one Boom card with Windfall. ''This means Windfall might not be in the final deck.'' During a Windfall, customers will be plentiful, therefore all products will sell at the Retail Outlets. In addition, unemployment is at its lowest, so during Reorganize the Status marker at the Job Market is moved all the way to the right (to the 7 [Money] / 7 [Info] space).

== Bonus: Events ==

Each Event card alters the rules for one of the Game board areas.

Before the game begins, the players shuffle the Event deck and choose one Event card at random. The chosen Event will indicate which board area is affected for the game. Place the card on the board above the affected area as a reminder and reference.

== Credits ==

'''Author:''' David Short

'''1st edition Development:''' Seth Jaffee

'''2nd edition Development:''' Henning Kröpke, Uli Blennemann

'''Graphics:''' Harald Lieske

'''Layout:''' Filip Stransky

'''Notable Playtesters:''' Nathan Emmerich, Chris Hall, Matt Manis, Josh Martin, Jon Peoble, Eileen Short, Mike Tunison

Copyright 2018 Spielworxx, Nielande 12, D-48727 Billerbeck — www.spielworxx.de

Gamehelpbunnykingdomtown

2026-06-13T03:58:24Z

BaronFraser:

== Overview and Aim of the Game ==

''Bunny Kingdom: Town'' is a tile-drafting and placement game played over 4 rounds.

During each round, you'll be '''planning''' and '''constructing''' new Buildings to develop the Neighborhoods under your control.

Choose your construction plans carefully to boost your strategy, but watch out: those you overlook could be just what your opponent needs!

Each new Building you construct will bring you resources or increase your influence. Don't forget to satisfy the '''requests''' of your new townsfolk, which will remain secret until the end of the game and could completely change the outcome.

During final scoring, the player with the most '''Golden Carrots''' is the winner!

== Setup ==

At the start of the game, Upgrade Tiles are randomly drawn until the total cost totals 8 or more.

Each player starts the game with 2 Coins.

The initial bridges and plot cards are set up based on the game's chosen Setup Card.

=== Setup Cards ===

When setting up a game, you can choose a Setup Card (or select a random one). These determine which plots are initially available (the spaces where you can build your building) and where the game's bridges will be placed.
{| class="wikitable"
|+
!Card
!Choose For
!Plots and Bridges
|-
|1: A Golden Opportunity
|First game
|[[File:SetupCard01.jpg|thumb|Starting Plots and Bridges]]
|-
|2: New arrivals
|A game with spread-out plots
|[[File:SetupCard02.jpg|thumb|Starting Plots and Bridges]]
|-
|3: At the forest's edge
|A high-wood game
|[[File:SetupCard03.jpg|thumb|Starting Plots and Bridges]]
|-
|4: By the water
|Initial plots along the river
|[[File:SetupCard04.jpg|thumb|Starting Plots and Bridges]]
|-
|5: On the other side of the river
|A game with no bridges
|[[File:SetupCard05.jpg|thumb|Starting Plots (no Bridges)]]
|-
|6: Beyond the horizon
|A random setup
|[[File:SetupCard06.jpg|thumb|Starting Plots are randomly drawn. Players place 1 Bridge each.]]
|}

== The round ==

A game of ''Bunny Kingdom: Town'' is played over '''4 rounds''', with each player taking turns being the first player.

Each round consists of a series of player '''turns''', continuing until all available Building tiles have been taken.

=== Preparing a new round ===

At the start of each new round, complete the following steps.

# '''Each player receives 2 Coins''' from the reserve. ''(You received 3 during setup, so you'll start the first round with 5.)''
# '''Reveal the first 5 tiles from the Building pile''' and place them on the designated spaces on the board. ''These are the Buildings you can construct during this round.''
# '''Each player draws 2 Request cards''' and chooses 1 which they place face down in front of them. Place the unchosen cards into the discard pile face-up.

You can now begin the round.

=== The turn ===

Each player will now play their turn, starting with the first player. On your turn, '''you must perform the Plan action'''. You may then, if you wish, '''Construct one or more Buildings'''. Before or after either of these two actions, you may also '''Create one or more Upgrades'''.

==== Plan (mandatory) ====

''This action allows you to obtain new Building tiles''. On your turn, '''you must''' perform the Plan action. To do so, choose an available Building tile from the track and place it into your reserve. '''Do not reveal a new Building tile to replace the one you took!'''

==== Construct (optional) ====

'''This action lets you construct Buildings from your reserve to develop the town and your Neighborhoods.'''

===== Placing a Building =====

Once you have completed your Plan action, you may, if you wish, construct one or more Buildings. To construct a Building, complete the following steps:

# Choose a Building tile from your reserve.
# Choose an available Plot card and immediately pay its cost in Coins as shown on the board, depending on its position on the track. Then add it to your reserve.
# Place your Building tile onto the space shown on the Plot card (as indicated by the presence of an Architect token). Place the Architect token above the Plot card’s track space. Place a Bunny from your reserve onto the Building you constructed. If the space contains a wood token, add it to your reserve.

The first card on the track is free — you can take that Plot without paying any Coins.

Some Buildings '''must''' be placed onto waterfront spaces (as shown by the waterfront icon). If there are no available waterfront Plots (or if they're too expensive), you cannot construct those Buildings. '''All other Buildings have no placement restrictions'''.

If you cannot or do not wish to construct a Building, skip this step and keep the Buildings in your reserve for a future turn.

If you constructed a Building, move on to '''Activating a Neighborhood'''. Otherwise, go straight to '''End of the turn'''.

===== Activating a Neighborhood =====

''Activating a Neighborhood lets you collect resources and increase your influence by gainaing precious Golden Carrots''. Each time you construct a Building, apply any '''When Constructed''' effects it has, then calculate your Neighborhood's influence.

;'''Neighborhood'''
:A group of orthogonally adjacent Buildings under your control is called a Neighborhood. Buildings on different sides of the river are not part of the same Neighborhood, unless they are connected by a Bridge token.

===== Building triggers =====

Each Building has either a '''When Constructed''' or a '''When Activated''' effect which triggers at a specific moment when activating a Neighborhood.

;When Constructed
:These Buildings have a one-off effect that is triggered only when they are first placed onto a Plot. They do not reactivate multiple times during the game, unless they return to your reserve and are placed again later.

;When Activated
:When a Neighborhood is activated, all of its Buildings’ effects are triggered at once.

===== Calculating the influence of a Neighborhood =====

After constructing a Building and applying its '''When Constructed''' effect, calculate the influence of the Neighborhood it was added to:

Multiply the number of active '''stars''' on the Buildings in the Neighborhood by the number of '''different Building types''' (which are not Illegal ) present in that Neighborhood. The total obtained represents the number of '''Golden Carrots'''you gain for that Neighborhood. Move your Bunny forward that number of spaces on the score track.

;Stars
:Stars represent a Building's prestige and the wealth it brings to its Neighborhood. Some Stars only count towards a Neighborhood's influence if the Neighborhood contains at least one Building of the type shown. If it doesn't, then the Star isn't active (and isn't counted).

;Building Types
:Buildings have different '''types'''. The more different types of Building a Neighborhood has (giving it a variety of different shops and services), the more influential it will be. There are '''5 different Building types''' that contribute to a Neighborhood's influence:
:* Leisure
:* Work
:* Civic
:* Residential
:* Knowledge
:'''Illegal Buildings''' do not contribute to influence.

;The Park
:The '''Park''' is a joker tile. It can be counted as any Building type. You can choose its type each time you calculate its Neighborhood's influence. Certain Request cards may also require you to choose its type at the end of the game; in that case, you can only choose its type once.

===== Constructing additional Buildings =====

As long as you have Buildings in your reserve, you can keep placing them during the '''Construct''' phase. Each additional Building you place costs costs 1 extra Coin in addition to the cost of the Plot. Other than this additional cost, proceed as normal to construct it. New Plot cards will be revealed at the end of the turn only.

Keeping Buildings in reserve for later can often be a good idea. A better location may become available, or a certain Plot may become less expensive. It’s up to you to choose the best strategy to optimize the development of your Neighborhoods!

==== Create (optional) ====

''Upgrades bring you additional bonuses that make it easier to develop your Neighborhoods.''

'''At any time during your turn''', before or after your Plan or Construct actions, you can create as many Upgrades as you wish by spending Wood. All spent Wood is put back into the reserve. To create an Upgrade, complete the following steps

# Choose 1 available Upgrade tile.
# Pay its cost in '''Wood'''.
# Place it onto one of the 3 slots on your side of the board.

You have '''3 Upgrade slots'''. Once you have created 3, you cannot buy any more. Make sure you choose carefully, as each Upgrade can have considerable impact on your strategy. The Upgrades revealed during setup will be the only ones available for the entire game.

* '''When purchased''' Upgrades: apply the effect immediately.
* '''All the time''' Upgrades: apply the effect whenever it's possible.

=== End of the turn ===

At the end of your turn, complete the following steps:

# '''Slide the Plot cards along''': slide all the Plot cards on the track, reducing each card's cost.
# '''Reveal new Plot cards''': fill the empty spaces on the track with new cards from the pile. Use Architect tokens to indicate the new Plots available on the board.

Check whether the '''End of the round''' has been triggered. If it hasn’t, then it’s now your opponent’s turn.

== End of the round ==

If you take the last available Building tile from the board, the end of the round is triggered. End your turn as normal, then check the pile of Building tiles:

* '''If the pile of Building tiles is not empty''', prepare a new round.
* '''If the pile of Building tiles pile is empty''', and you have just finished the 4th round, go to '''End of the game'''.

== End of the game ==

At the end of the game, complete the following steps:

# '''Reveal your Request cards''': Starting with the player in the lowest position on the score track, reveal your Request cards one by one and check if your meet their scoring conditions.
# '''Determine the winner''': The player with the most Golden Carrots wins and becomes the mayor of the new town! In the case of a draw, the player with the most coins wins. If the draw persists, the two players share their victory!

'''Note''': apply the effects of the '''Community Leader''' and '''Watchmaker''' Request cards at end of game, '''not''' when you first obtain them.

== Credits ==

* '''Design''': Richard Garfield
* '''Illustrations''': Jiahui Eva Gao
* '''Project management''': Adrien Fenouillet
* '''Graphic Design''': Charlie Metz
* '''Proofreading''': Xavier Taverne, Robin Leplumey
* '''Editorial assistant''': Camille Cherchour
* '''3D visuals''': Valentin Jacoberger
* '''Translation''': Georgina Fenouillet

Published by '''IELLO''' — 9, avenue des Érables, lot 341, 54180 Heillecourt, France · [https://iello.fr iello.fr] · contact@iello.fr

Gamehelpbunnykingdomtown

2026-06-10T09:01:46Z

BaronFraser: Added setup cards

== Overview and Aim of the Game ==

''Bunny Kingdom: Town'' is a tile-drafting and placement game played over 4 rounds.

During each round, you'll be '''planning''' and '''constructing''' new Buildings to develop the Neighborhoods under your control.

Choose your construction plans carefully to boost your strategy, but watch out: those you overlook could be just what your opponent needs!

Each new Building you construct will bring you resources or increase your influence. Don't forget to satisfy the '''requests''' of your new townsfolk, which will remain secret until the end of the game and could completely change the outcome.

During final scoring, the player with the most '''Golden Carrots''' is the winner!

== Setup Cards ==

When setting up a game, you can choose a Setup Card (or select a random one). These determine which plots are initially available (the spaces where you can build your building) and where the game's bridges will be placed.
{| class="wikitable"
|+
!Card
!Choose For
!Plots and Bridges
|-
|1: A Golden Opportunity
|First game
|[[File:SetupCard01.jpg|thumb|Starting Plots and Bridges]]
|-
|2: New arrivals
|A game with spread-out plots
|[[File:SetupCard02.jpg|thumb|Starting Plots and Bridges]]
|-
|3: At the forest's edge
|A high-wood game
|[[File:SetupCard03.jpg|thumb|Starting Plots and Bridges]]
|-
|4: By the water
|Initial plots along the river
|[[File:SetupCard04.jpg|thumb|Starting Plots and Bridges]]
|-
|5: On the other side of the river
|A game with no bridges
|[[File:SetupCard05.jpg|thumb|Starting Plots (no Bridges)]]
|-
|6: Beyond the horizon
|A random setup
|[[File:SetupCard06.jpg|thumb|Starting Plots are randomly drawn. Players place 1 Bridge each.]]
|}

== The round ==

A game of ''Bunny Kingdom: Town'' is played over '''4 rounds''', with each player taking turns being the first player.

Each round consists of a series of player '''turns''', continuing until all available Building tiles have been taken.

=== Preparing a new round ===

At the start of each new round, complete the following steps.

# '''Each player receives 2 Coins''' from the reserve. ''(You received 3 during setup, so you'll start the first round with 5.)''
# '''Reveal the first 5 tiles from the Building pile''' and place them on the designated spaces on the board. ''These are the Buildings you can construct during this round.''
# '''Each player draws 2 Request cards''' and chooses 1 which they place face down in front of them. Place the unchosen cards into the discard pile face-up.

You can now begin the round.

=== The turn ===

Each player will now play their turn, starting with the first player. On your turn, '''you must perform the Plan action'''. You may then, if you wish, '''Construct one or more Buildings'''. Before or after either of these two actions, you may also '''Create one or more Upgrades'''.

==== Plan (mandatory) ====

''This action allows you to obtain new Building tiles''. On your turn, '''you must''' perform the Plan action. To do so, choose an available Building tile from the track and place it into your reserve. '''Do not reveal a new Building tile to replace the one you took!'''

==== Construct (optional) ====

'''This action lets you construct Buildings from your reserve to develop the town and your Neighborhoods.'''

===== Placing a Building =====

Once you have completed your Plan action, you may, if you wish, construct one or more Buildings. To construct a Building, complete the following steps:

# Choose a Building tile from your reserve.
# Choose an available Plot card and immediately pay its cost in Coins as shown on the board, depending on its position on the track. Then add it to your reserve.
# Place your Building tile onto the space shown on the Plot card (as indicated by the presence of an Architect token). Place the Architect token above the Plot card’s track space. Place a Bunny from your reserve onto the Building you constructed. If the space contains a wood token, add it to your reserve.

The first card on the track is free — you can take that Plot without paying any Coins.

Some Buildings '''must''' be placed onto waterfront spaces (as shown by the waterfront icon). If there are no available waterfront Plots (or if they're too expensive), you cannot construct those Buildings. '''All other Buildings have no placement restrictions'''.

If you cannot or do not wish to construct a Building, skip this step and keep the Buildings in your reserve for a future turn.

If you constructed a Building, move on to '''Activating a Neighborhood'''. Otherwise, go straight to '''End of the turn'''.

===== Activating a Neighborhood =====

''Activating a Neighborhood lets you collect resources and increase your influence by gainaing precious Golden Carrots''. Each time you construct a Building, apply any '''When Constructed''' effects it has, then calculate your Neighborhood's influence.

;'''Neighborhood'''
:A group of orthogonally adjacent Buildings under your control is called a Neighborhood. Buildings on different sides of the river are not part of the same Neighborhood, unless they are connected by a Bridge token.

===== Building triggers =====

Each Building has either a '''When Constructed''' or a '''When Activated''' effect which triggers at a specific moment when activating a Neighborhood.

;When Constructed
:These Buildings have a one-off effect that is triggered only when they are first placed onto a Plot. They do not reactivate multiple times during the game, unless they return to your reserve and are placed again later.

;When Activated
:When a Neighborhood is activated, all of its Buildings’ effects are triggered at once.

===== Calculating the influence of a Neighborhood =====

After constructing a Building and applying its '''When Constructed''' effect, calculate the influence of the Neighborhood it was added to:

Multiply the number of active '''stars''' on the Buildings in the Neighborhood by the number of '''different Building types''' (which are not Illegal ) present in that Neighborhood. The total obtained represents the number of '''Golden Carrots'''you gain for that Neighborhood. Move your Bunny forward that number of spaces on the score track.

;Stars
:Stars represent a Building's prestige and the wealth it brings to its Neighborhood. Some Stars only count towards a Neighborhood's influence if the Neighborhood contains at least one Building of the type shown. If it doesn't, then the Star isn't active (and isn't counted).

;Building Types
:Buildings have different '''types'''. The more different types of Building a Neighborhood has (giving it a variety of different shops and services), the more influential it will be. There are '''5 different Building types''' that contribute to a Neighborhood's influence:
:* Leisure
:* Work
:* Civic
:* Residential
:* Knowledge
:'''Illegal Buildings''' do not contribute to influence.

;The Park
:The '''Park''' is a joker tile. It can be counted as any Building type. You can choose its type each time you calculate its Neighborhood's influence. Certain Request cards may also require you to choose its type at the end of the game; in that case, you can only choose its type once.

===== Constructing additional Buildings =====

As long as you have Buildings in your reserve, you can keep placing them during the '''Construct''' phase. Each additional Building you place costs costs 1 extra Coin in addition to the cost of the Plot. Other than this additional cost, proceed as normal to construct it. New Plot cards will be revealed at the end of the turn only.

Keeping Buildings in reserve for later can often be a good idea. A better location may become available, or a certain Plot may become less expensive. It’s up to you to choose the best strategy to optimize the development of your Neighborhoods!

==== Create (optional) ====

''Upgrades bring you additional bonuses that make it easier to develop your Neighborhoods.''

'''At any time during your turn''', before or after your Plan or Construct actions, you can create as many Upgrades as you wish by spending Wood. All spent Wood is put back into the reserve. To create an Upgrade, complete the following steps

# Choose 1 available Upgrade tile.
# Pay its cost in '''Wood'''.
# Place it onto one of the 3 slots on your side of the board.

You have '''3 Upgrade slots'''. Once you have created 3, you cannot buy any more. Make sure you choose carefully, as each Upgrade can have considerable impact on your strategy. The Upgrades revealed during setup will be the only ones available for the entire game.

* '''When purchased''' Upgrades: apply the effect immediately.
* '''All the time''' Upgrades: apply the effect whenever it's possible.

=== End of the turn ===

At the end of your turn, complete the following steps:

# '''Slide the Plot cards along''': slide all the Plot cards on the track, reducing each card's cost.
# '''Reveal new Plot cards''': fill the empty spaces on the track with new cards from the pile. Use Architect tokens to indicate the new Plots available on the board.

Check whether the '''End of the round''' has been triggered. If it hasn’t, then it’s now your opponent’s turn.

== End of the round ==

If you take the last available Building tile from the board, the end of the round is triggered. End your turn as normal, then check the pile of Building tiles:

* '''If the pile of Building tiles is not empty''', prepare a new round.
* '''If the pile of Building tiles pile is empty''', and you have just finished the 4th round, go to '''End of the game'''.

== End of the game ==

At the end of the game, complete the following steps:

# '''Reveal your Request cards''': Starting with the player in the lowest position on the score track, reveal your Request cards one by one and check if your meet their scoring conditions.
# '''Determine the winner''': The player with the most Golden Carrots wins and becomes the mayor of the new town! In the case of a draw, the player with the most coins wins. If the draw persists, the two players share their victory!

'''Note''': apply the effects of the '''Community Leader''' and '''Watchmaker''' Request cards at end of game, '''not''' when you first obtain them.

== Credits ==

* '''Design''': Richard Garfield
* '''Illustrations''': Jiahui Eva Gao
* '''Project management''': Adrien Fenouillet
* '''Graphic Design''': Charlie Metz
* '''Proofreading''': Xavier Taverne, Robin Leplumey
* '''Editorial assistant''': Camille Cherchour
* '''3D visuals''': Valentin Jacoberger
* '''Translation''': Georgina Fenouillet

Published by '''IELLO''' — 9, avenue des Érables, lot 341, 54180 Heillecourt, France · [https://iello.fr iello.fr] · contact@iello.fr

File:SetupCard06.jpg

2026-06-10T08:59:59Z

BaronFraser:

Bunny Kingdown Town Setup Card 6

File:SetupCard05.jpg

2026-06-10T08:59:09Z

BaronFraser:

Bunny Kingdown Town Setup Card 5

File:SetupCard04.jpg

2026-06-10T08:58:38Z

BaronFraser:

Bunny Kingdown Town Setup Card 4

File:SetupCard03.jpg

2026-06-10T08:57:57Z

BaronFraser:

Bunny Kingdown Town Setup Card 3

File:SetupCard02.jpg

2026-06-10T08:56:46Z

BaronFraser:

Bunny Kingdown Town Setup Card 2

File:SetupCard01.jpg

2026-06-10T08:55:42Z

BaronFraser:

Bunny Kingdown Town Setup Card 1

Gamehelpbunnykingdomtown

2026-05-08T23:21:45Z

BaronFraser: /* B. Activating a Neighborhood */

== Overview and Aim of the Game ==

''Bunny Kingdom: Town'' is a tile-drafting and placement game played over 4 rounds.

During each round, you'll be '''planning''' and '''constructing''' new Buildings to develop the Neighborhoods under your control.

Choose your construction plans carefully to boost your strategy, but watch out: those you overlook could be just what your opponent needs!

Each new Building you construct will bring you resources or increase your influence. Don't forget to satisfy the '''requests''' of your new townsfolk, which will remain secret until the end of the game and could completely change the outcome.

During final scoring, the player with the most '''Golden Carrots''' is the winner!

== The round ==

A game of ''Bunny Kingdom: Town'' is played over '''4 rounds''', with each player taking turns being the first player.

Each round consists of a series of player '''turns''', continuing until all available Building tiles have been taken.

=== Preparing a new round ===

At the start of each new round, complete the following steps.

# '''Each player receives 2 Coins''' from the reserve. ''(You received 3 during setup, so you'll start the first round with 5.)''
# '''Reveal the first 5 tiles from the Building pile''' and place them on the designated spaces on the board. ''These are the Buildings you can construct during this round.''
# '''Each player draws 2 Request cards''' and chooses 1 which they place face down in front of them. Place the unchosen cards into the discard pile face-up.

You can now begin the round.

=== The turn ===

Each player will now play their turn, starting with the first player. On your turn, '''you must perform the Plan action'''. You may then, if you wish, '''Construct one or more Buildings'''. Before or after either of these two actions, you may also '''Create one or more Upgrades'''.

==== Plan (mandatory) ====

''This action allows you to obtain new Building tiles''. On your turn, '''you must''' perform the Plan action. To do so, choose an available Building tile from the track and place it into your reserve. '''Do not reveal a new Building tile to replace the one you took!'''

==== Construct (optional) ====

'''This action lets you construct Buildings from your reserve to develop the town and your Neighborhoods.'''

===== Placing a Building =====

Once you have completed your Plan action, you may, if you wish, construct one or more Buildings. To construct a Building, complete the following steps:

# Choose a Building tile from your reserve.
# Choose an available Plot card and immediately pay its cost in Coins as shown on the board, depending on its position on the track. Then add it to your reserve.
# Place your Building tile onto the space shown on the Plot card (as indicated by the presence of an Architect token). Place the Architect token above the Plot card’s track space. Place a Bunny from your reserve onto the Building you constructed. If the space contains a wood token, add it to your reserve.

The first card on the track is free — you can take that Plot without paying any Coins.

Some Buildings '''must''' be placed onto waterfront spaces (as shown by the waterfront icon). If there are no available waterfront Plots (or if they're too expensive), you cannot construct those Buildings. '''All other Buildings have no placement restrictions'''.

If you cannot or do not wish to construct a Building, skip this step and keep the Buildings in your reserve for a future turn.

If you constructed a Building, move on to '''Activating a Neighborhood'''. Otherwise, go straight to '''End of the turn'''.

===== Activating a Neighborhood =====

''Activating a Neighborhood lets you collect resources and increase your influence by gainaing precious Golden Carrots''. Each time you construct a Building, apply any '''When Constructed''' effects it has, then calculate your Neighborhood's influence.

;'''Neighborhood'''
:A group of orthogonally adjacent Buildings under your control is called a Neighborhood. Buildings on different sides of the river are not part of the same Neighborhood, unless they are connected by a Bridge token.

===== Building triggers =====

Each Building has either a '''When Constructed''' or a '''When Activated''' effect which triggers at a specific moment when activating a Neighborhood.

;When Constructed
:These Buildings have a one-off effect that is triggered only when they are first placed onto a Plot. They do not reactivate multiple times during the game, unless they return to your reserve and are placed again later.

;When Activated
:When a Neighborhood is activated, all of its Buildings’ effects are triggered at once.

===== Calculating the influence of a Neighborhood =====

After constructing a Building and applying its '''When Constructed''' effect, calculate the influence of the Neighborhood it was added to:

Multiply the number of active '''stars''' on the Buildings in the Neighborhood by the number of '''different Building types''' (which are not Illegal ) present in that Neighborhood. The total obtained represents the number of '''Golden Carrots'''you gain for that Neighborhood. Move your Bunny forward that number of spaces on the score track.

;Stars
:Stars represent a Building's prestige and the wealth it brings to its Neighborhood. Some Stars only count towards a Neighborhood's influence if the Neighborhood contains at least one Building of the type shown. If it doesn't, then the Star isn't active (and isn't counted).

;Building Types
:Buildings have different '''types'''. The more different types of Building a Neighborhood has (giving it a variety of different shops and services), the more influential it will be. There are '''5 different Building types''' that contribute to a Neighborhood's influence:
:* Leisure
:* Work
:* Civic
:* Residential
:* Knowledge
:'''Illegal Buildings''' do not contribute to influence.

;The Park
:The '''Park''' is a joker tile. It can be counted as any Building type. You can choose its type each time you calculate its Neighborhood's influence. Certain Request cards may also require you to choose its type at the end of the game; in that case, you can only choose its type once.

===== Constructing additional Buildings =====

As long as you have Buildings in your reserve, you can keep placing them during the '''Construct''' phase. Each additional Building you place costs costs 1 extra Coin in addition to the cost of the Plot. Other than this additional cost, proceed as normal to construct it. New Plot cards will be revealed at the end of the turn only.

Keeping Buildings in reserve for later can often be a good idea. A better location may become available, or a certain Plot may become less expensive. It’s up to you to choose the best strategy to optimize the development of your Neighborhoods!

==== Create (optional) ====

''Upgrades bring you additional bonuses that make it easier to develop your Neighborhoods.''

'''At any time during your turn''', before or after your Plan or Construct actions, you can create as many Upgrades as you wish by spending Wood. All spent Wood is put back into the reserve. To create an Upgrade, complete the following steps

# Choose 1 available Upgrade tile.
# Pay its cost in '''Wood'''.
# Place it onto one of the 3 slots on your side of the board.

You have '''3 Upgrade slots'''. Once you have created 3, you cannot buy any more. Make sure you choose carefully, as each Upgrade can have considerable impact on your strategy. The Upgrades revealed during setup will be the only ones available for the entire game.

* '''When purchased''' Upgrades: apply the effect immediately.
* '''All the time''' Upgrades: apply the effect whenever it's possible.

=== End of the turn ===

At the end of your turn, complete the following steps:

# '''Slide the Plot cards along''': slide all the Plot cards on the track, reducing each card's cost.
# '''Reveal new Plot cards''': fill the empty spaces on the track with new cards from the pile. Use Architect tokens to indicate the new Plots available on the board.

Check whether the '''End of the round''' has been triggered. If it hasn’t, then it’s now your opponent’s turn.

== End of the round ==

If you take the last available Building tile from the board, the end of the round is triggered. End your turn as normal, then check the pile of Building tiles:

* '''If the pile of Building tiles is not empty''', prepare a new round.
* '''If the pile of Building tiles pile is empty''', and you have just finished the 4th round, go to '''End of the game'''.

== End of the game ==

At the end of the game, complete the following steps:

# '''Reveal your Request cards''': Starting with the player in the lowest position on the score track, reveal your Request cards one by one and check if your meet their scoring conditions.
# '''Determine the winner''': The player with the most Golden Carrots wins and becomes the mayor of the new town! In the case of a draw, the player with the most coins wins. If the draw persists, the two players share their victory!

'''Note''': apply the effects of the '''Community Leader''' and '''Watchmaker''' Request cards at end of game, '''not''' when you first obtain them.

== Credits ==

* '''Design''': Richard Garfield
* '''Illustrations''': Jiahui Eva Gao
* '''Project management''': Adrien Fenouillet
* '''Graphic Design''': Charlie Metz
* '''Proofreading''': Xavier Taverne, Robin Leplumey
* '''Editorial assistant''': Camille Cherchour
* '''3D visuals''': Valentin Jacoberger
* '''Translation''': Georgina Fenouillet

Published by '''IELLO''' — 9, avenue des Érables, lot 341, 54180 Heillecourt, France · [https://iello.fr iello.fr] · contact@iello.fr

Gamehelpbunnykingdomtown

2026-05-08T23:21:32Z

BaronFraser: /* A. Placing a Building */

== Overview and Aim of the Game ==

''Bunny Kingdom: Town'' is a tile-drafting and placement game played over 4 rounds.

During each round, you'll be '''planning''' and '''constructing''' new Buildings to develop the Neighborhoods under your control.

Choose your construction plans carefully to boost your strategy, but watch out: those you overlook could be just what your opponent needs!

Each new Building you construct will bring you resources or increase your influence. Don't forget to satisfy the '''requests''' of your new townsfolk, which will remain secret until the end of the game and could completely change the outcome.

During final scoring, the player with the most '''Golden Carrots''' is the winner!

== The round ==

A game of ''Bunny Kingdom: Town'' is played over '''4 rounds''', with each player taking turns being the first player.

Each round consists of a series of player '''turns''', continuing until all available Building tiles have been taken.

=== Preparing a new round ===

At the start of each new round, complete the following steps.

# '''Each player receives 2 Coins''' from the reserve. ''(You received 3 during setup, so you'll start the first round with 5.)''
# '''Reveal the first 5 tiles from the Building pile''' and place them on the designated spaces on the board. ''These are the Buildings you can construct during this round.''
# '''Each player draws 2 Request cards''' and chooses 1 which they place face down in front of them. Place the unchosen cards into the discard pile face-up.

You can now begin the round.

=== The turn ===

Each player will now play their turn, starting with the first player. On your turn, '''you must perform the Plan action'''. You may then, if you wish, '''Construct one or more Buildings'''. Before or after either of these two actions, you may also '''Create one or more Upgrades'''.

==== Plan (mandatory) ====

''This action allows you to obtain new Building tiles''. On your turn, '''you must''' perform the Plan action. To do so, choose an available Building tile from the track and place it into your reserve. '''Do not reveal a new Building tile to replace the one you took!'''

==== Construct (optional) ====

'''This action lets you construct Buildings from your reserve to develop the town and your Neighborhoods.'''

===== Placing a Building =====

Once you have completed your Plan action, you may, if you wish, construct one or more Buildings. To construct a Building, complete the following steps:

# Choose a Building tile from your reserve.
# Choose an available Plot card and immediately pay its cost in Coins as shown on the board, depending on its position on the track. Then add it to your reserve.
# Place your Building tile onto the space shown on the Plot card (as indicated by the presence of an Architect token). Place the Architect token above the Plot card’s track space. Place a Bunny from your reserve onto the Building you constructed. If the space contains a wood token, add it to your reserve.

The first card on the track is free — you can take that Plot without paying any Coins.

Some Buildings '''must''' be placed onto waterfront spaces (as shown by the waterfront icon). If there are no available waterfront Plots (or if they're too expensive), you cannot construct those Buildings. '''All other Buildings have no placement restrictions'''.

If you cannot or do not wish to construct a Building, skip this step and keep the Buildings in your reserve for a future turn.

If you constructed a Building, move on to '''Activating a Neighborhood'''. Otherwise, go straight to '''End of the turn'''.

===== B. Activating a Neighborhood =====

''Activating a Neighborhood lets you collect resources and increase your influence by gainaing precious Golden Carrots''. Each time you construct a Building, apply any '''When Constructed''' effects it has, then calculate your Neighborhood's influence.

;'''Neighborhood'''
:A group of orthogonally adjacent Buildings under your control is called a Neighborhood. Buildings on different sides of the river are not part of the same Neighborhood, unless they are connected by a Bridge token.

===== Building triggers =====

Each Building has either a '''When Constructed''' or a '''When Activated''' effect which triggers at a specific moment when activating a Neighborhood.

;When Constructed
:These Buildings have a one-off effect that is triggered only when they are first placed onto a Plot. They do not reactivate multiple times during the game, unless they return to your reserve and are placed again later.

;When Activated
:When a Neighborhood is activated, all of its Buildings’ effects are triggered at once.

===== Calculating the influence of a Neighborhood =====

After constructing a Building and applying its '''When Constructed''' effect, calculate the influence of the Neighborhood it was added to:

Multiply the number of active '''stars''' on the Buildings in the Neighborhood by the number of '''different Building types''' (which are not Illegal ) present in that Neighborhood. The total obtained represents the number of '''Golden Carrots'''you gain for that Neighborhood. Move your Bunny forward that number of spaces on the score track.

;Stars
:Stars represent a Building's prestige and the wealth it brings to its Neighborhood. Some Stars only count towards a Neighborhood's influence if the Neighborhood contains at least one Building of the type shown. If it doesn't, then the Star isn't active (and isn't counted).

;Building Types
:Buildings have different '''types'''. The more different types of Building a Neighborhood has (giving it a variety of different shops and services), the more influential it will be. There are '''5 different Building types''' that contribute to a Neighborhood's influence:
:* Leisure
:* Work
:* Civic
:* Residential
:* Knowledge
:'''Illegal Buildings''' do not contribute to influence.

;The Park
:The '''Park''' is a joker tile. It can be counted as any Building type. You can choose its type each time you calculate its Neighborhood's influence. Certain Request cards may also require you to choose its type at the end of the game; in that case, you can only choose its type once.

===== Constructing additional Buildings =====

As long as you have Buildings in your reserve, you can keep placing them during the '''Construct''' phase. Each additional Building you place costs costs 1 extra Coin in addition to the cost of the Plot. Other than this additional cost, proceed as normal to construct it. New Plot cards will be revealed at the end of the turn only.

Keeping Buildings in reserve for later can often be a good idea. A better location may become available, or a certain Plot may become less expensive. It’s up to you to choose the best strategy to optimize the development of your Neighborhoods!

==== Create (optional) ====

''Upgrades bring you additional bonuses that make it easier to develop your Neighborhoods.''

'''At any time during your turn''', before or after your Plan or Construct actions, you can create as many Upgrades as you wish by spending Wood. All spent Wood is put back into the reserve. To create an Upgrade, complete the following steps

# Choose 1 available Upgrade tile.
# Pay its cost in '''Wood'''.
# Place it onto one of the 3 slots on your side of the board.

You have '''3 Upgrade slots'''. Once you have created 3, you cannot buy any more. Make sure you choose carefully, as each Upgrade can have considerable impact on your strategy. The Upgrades revealed during setup will be the only ones available for the entire game.

* '''When purchased''' Upgrades: apply the effect immediately.
* '''All the time''' Upgrades: apply the effect whenever it's possible.

=== End of the turn ===

At the end of your turn, complete the following steps:

# '''Slide the Plot cards along''': slide all the Plot cards on the track, reducing each card's cost.
# '''Reveal new Plot cards''': fill the empty spaces on the track with new cards from the pile. Use Architect tokens to indicate the new Plots available on the board.

Check whether the '''End of the round''' has been triggered. If it hasn’t, then it’s now your opponent’s turn.

== End of the round ==

If you take the last available Building tile from the board, the end of the round is triggered. End your turn as normal, then check the pile of Building tiles:

* '''If the pile of Building tiles is not empty''', prepare a new round.
* '''If the pile of Building tiles pile is empty''', and you have just finished the 4th round, go to '''End of the game'''.

== End of the game ==

At the end of the game, complete the following steps:

# '''Reveal your Request cards''': Starting with the player in the lowest position on the score track, reveal your Request cards one by one and check if your meet their scoring conditions.
# '''Determine the winner''': The player with the most Golden Carrots wins and becomes the mayor of the new town! In the case of a draw, the player with the most coins wins. If the draw persists, the two players share their victory!

'''Note''': apply the effects of the '''Community Leader''' and '''Watchmaker''' Request cards at end of game, '''not''' when you first obtain them.

== Credits ==

* '''Design''': Richard Garfield
* '''Illustrations''': Jiahui Eva Gao
* '''Project management''': Adrien Fenouillet
* '''Graphic Design''': Charlie Metz
* '''Proofreading''': Xavier Taverne, Robin Leplumey
* '''Editorial assistant''': Camille Cherchour
* '''3D visuals''': Valentin Jacoberger
* '''Translation''': Georgina Fenouillet

Published by '''IELLO''' — 9, avenue des Érables, lot 341, 54180 Heillecourt, France · [https://iello.fr iello.fr] · contact@iello.fr

Gamehelpbunnykingdomtown

2026-05-08T23:21:01Z

BaronFraser: Created page with "== Overview and Aim of the Game == ''Bunny Kingdom: Town'' is a tile-drafting and placement game played over 4 rounds. During each round, you'll be '''planning''' and '''constructing''' new Buildings to develop the Neighborhoods under your control. Choose your construction plans carefully to boost your strategy, but watch out: those you overlook could be just what your opponent needs! Each new Building you construct will bring you resources or increase your influence..."

== Overview and Aim of the Game ==

''Bunny Kingdom: Town'' is a tile-drafting and placement game played over 4 rounds.

During each round, you'll be '''planning''' and '''constructing''' new Buildings to develop the Neighborhoods under your control.

Choose your construction plans carefully to boost your strategy, but watch out: those you overlook could be just what your opponent needs!

Each new Building you construct will bring you resources or increase your influence. Don't forget to satisfy the '''requests''' of your new townsfolk, which will remain secret until the end of the game and could completely change the outcome.

During final scoring, the player with the most '''Golden Carrots''' is the winner!

== The round ==

A game of ''Bunny Kingdom: Town'' is played over '''4 rounds''', with each player taking turns being the first player.

Each round consists of a series of player '''turns''', continuing until all available Building tiles have been taken.

=== Preparing a new round ===

At the start of each new round, complete the following steps.

# '''Each player receives 2 Coins''' from the reserve. ''(You received 3 during setup, so you'll start the first round with 5.)''
# '''Reveal the first 5 tiles from the Building pile''' and place them on the designated spaces on the board. ''These are the Buildings you can construct during this round.''
# '''Each player draws 2 Request cards''' and chooses 1 which they place face down in front of them. Place the unchosen cards into the discard pile face-up.

You can now begin the round.

=== The turn ===

Each player will now play their turn, starting with the first player. On your turn, '''you must perform the Plan action'''. You may then, if you wish, '''Construct one or more Buildings'''. Before or after either of these two actions, you may also '''Create one or more Upgrades'''.

==== Plan (mandatory) ====

''This action allows you to obtain new Building tiles''. On your turn, '''you must''' perform the Plan action. To do so, choose an available Building tile from the track and place it into your reserve. '''Do not reveal a new Building tile to replace the one you took!'''

==== Construct (optional) ====

'''This action lets you construct Buildings from your reserve to develop the town and your Neighborhoods.'''

===== A. Placing a Building =====

Once you have completed your Plan action, you may, if you wish, construct one or more Buildings. To construct a Building, complete the following steps:

# Choose a Building tile from your reserve.
# Choose an available Plot card and immediately pay its cost in Coins as shown on the board, depending on its position on the track. Then add it to your reserve.
# Place your Building tile onto the space shown on the Plot card (as indicated by the presence of an Architect token). Place the Architect token above the Plot card’s track space. Place a Bunny from your reserve onto the Building you constructed. If the space contains a wood token, add it to your reserve.

The first card on the track is free — you can take that Plot without paying any Coins.

Some Buildings '''must''' be placed onto waterfront spaces (as shown by the waterfront icon). If there are no available waterfront Plots (or if they're too expensive), you cannot construct those Buildings. '''All other Buildings have no placement restrictions'''.

If you cannot or do not wish to construct a Building, skip this step and keep the Buildings in your reserve for a future turn.

If you constructed a Building, move on to '''Activating a Neighborhood'''. Otherwise, go straight to '''End of the turn'''.

===== B. Activating a Neighborhood =====

''Activating a Neighborhood lets you collect resources and increase your influence by gainaing precious Golden Carrots''. Each time you construct a Building, apply any '''When Constructed''' effects it has, then calculate your Neighborhood's influence.

;'''Neighborhood'''
:A group of orthogonally adjacent Buildings under your control is called a Neighborhood. Buildings on different sides of the river are not part of the same Neighborhood, unless they are connected by a Bridge token.

===== Building triggers =====

Each Building has either a '''When Constructed''' or a '''When Activated''' effect which triggers at a specific moment when activating a Neighborhood.

;When Constructed
:These Buildings have a one-off effect that is triggered only when they are first placed onto a Plot. They do not reactivate multiple times during the game, unless they return to your reserve and are placed again later.

;When Activated
:When a Neighborhood is activated, all of its Buildings’ effects are triggered at once.

===== Calculating the influence of a Neighborhood =====

After constructing a Building and applying its '''When Constructed''' effect, calculate the influence of the Neighborhood it was added to:

Multiply the number of active '''stars''' on the Buildings in the Neighborhood by the number of '''different Building types''' (which are not Illegal ) present in that Neighborhood. The total obtained represents the number of '''Golden Carrots'''you gain for that Neighborhood. Move your Bunny forward that number of spaces on the score track.

;Stars
:Stars represent a Building's prestige and the wealth it brings to its Neighborhood. Some Stars only count towards a Neighborhood's influence if the Neighborhood contains at least one Building of the type shown. If it doesn't, then the Star isn't active (and isn't counted).

;Building Types
:Buildings have different '''types'''. The more different types of Building a Neighborhood has (giving it a variety of different shops and services), the more influential it will be. There are '''5 different Building types''' that contribute to a Neighborhood's influence:
:* Leisure
:* Work
:* Civic
:* Residential
:* Knowledge
:'''Illegal Buildings''' do not contribute to influence.

;The Park
:The '''Park''' is a joker tile. It can be counted as any Building type. You can choose its type each time you calculate its Neighborhood's influence. Certain Request cards may also require you to choose its type at the end of the game; in that case, you can only choose its type once.

===== Constructing additional Buildings =====

As long as you have Buildings in your reserve, you can keep placing them during the '''Construct''' phase. Each additional Building you place costs costs 1 extra Coin in addition to the cost of the Plot. Other than this additional cost, proceed as normal to construct it. New Plot cards will be revealed at the end of the turn only.

Keeping Buildings in reserve for later can often be a good idea. A better location may become available, or a certain Plot may become less expensive. It’s up to you to choose the best strategy to optimize the development of your Neighborhoods!

==== Create (optional) ====

''Upgrades bring you additional bonuses that make it easier to develop your Neighborhoods.''

'''At any time during your turn''', before or after your Plan or Construct actions, you can create as many Upgrades as you wish by spending Wood. All spent Wood is put back into the reserve. To create an Upgrade, complete the following steps

# Choose 1 available Upgrade tile.
# Pay its cost in '''Wood'''.
# Place it onto one of the 3 slots on your side of the board.

You have '''3 Upgrade slots'''. Once you have created 3, you cannot buy any more. Make sure you choose carefully, as each Upgrade can have considerable impact on your strategy. The Upgrades revealed during setup will be the only ones available for the entire game.

* '''When purchased''' Upgrades: apply the effect immediately.
* '''All the time''' Upgrades: apply the effect whenever it's possible.

=== End of the turn ===

At the end of your turn, complete the following steps:

# '''Slide the Plot cards along''': slide all the Plot cards on the track, reducing each card's cost.
# '''Reveal new Plot cards''': fill the empty spaces on the track with new cards from the pile. Use Architect tokens to indicate the new Plots available on the board.

Check whether the '''End of the round''' has been triggered. If it hasn’t, then it’s now your opponent’s turn.

== End of the round ==

If you take the last available Building tile from the board, the end of the round is triggered. End your turn as normal, then check the pile of Building tiles:

* '''If the pile of Building tiles is not empty''', prepare a new round.
* '''If the pile of Building tiles pile is empty''', and you have just finished the 4th round, go to '''End of the game'''.

== End of the game ==

At the end of the game, complete the following steps:

# '''Reveal your Request cards''': Starting with the player in the lowest position on the score track, reveal your Request cards one by one and check if your meet their scoring conditions.
# '''Determine the winner''': The player with the most Golden Carrots wins and becomes the mayor of the new town! In the case of a draw, the player with the most coins wins. If the draw persists, the two players share their victory!

'''Note''': apply the effects of the '''Community Leader''' and '''Watchmaker''' Request cards at end of game, '''not''' when you first obtain them.

== Credits ==

* '''Design''': Richard Garfield
* '''Illustrations''': Jiahui Eva Gao
* '''Project management''': Adrien Fenouillet
* '''Graphic Design''': Charlie Metz
* '''Proofreading''': Xavier Taverne, Robin Leplumey
* '''Editorial assistant''': Camille Cherchour
* '''3D visuals''': Valentin Jacoberger
* '''Translation''': Georgina Fenouillet

Published by '''IELLO''' — 9, avenue des Érables, lot 341, 54180 Heillecourt, France · [https://iello.fr iello.fr] · contact@iello.fr

Main game logic: Game.php

2026-05-08T11:33:54Z

BaronFraser: /* Sending private data to some players */

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

'''Note:''' this file is now named Game.php, located in the modules/php directory. If you see it named yourgamename.game.php in the root dir, it's the legacy usage. In the legacy usage, the namepaces don't exists.

== 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.
getAllDatas accepts a magic parameter <code>int $currentPlayerId</code> (or <code>int $currentPlayerNo</code>) to fetch the information from the point of view of the current player id (or no). It should not have any other parameter.
* '''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!

; getPlayerCount() (or getPlayersNumber() that is an alias )
: 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.

; <nowiki>getActivePlayerId(): string</nowiki>
: 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.
: In general, you shouldn't use this method. It is available as a magic param in getArgs / onEnteringState / act functions, and shouldn't be needed anywhere else.

; 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

; getPlayerNameByNo($playerNo)
: Get the name by no

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

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

; getPlayerIdByNo(int $playerNo) int
: Get the player id by player no.

; 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) string
: 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. It is available as a magic param in act functions, and also in getAllDatas, and shouldn't be needed anywhere.
: '''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). Can be easily replaced by $this->getPlayerNameById($currentPlayerId);

; 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). Can be easily replaced by $this->getPlayerColorById($currentPlayerId);

; 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
: Be careful using this method (see above). Should never be needed, zombie players should behave like real players, and everything specific to zombie should be set in the zombie method only.

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

For player score and tiebreaker, see [[Main game logic: Game.php#Manage player scores and Tie breaker]]

== 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, '''as long as the SQL statement uses single quotes around the string. This is important!'''
''Note: if you using standard types in ajax actions, like AT_alphanum it is sanitized before arrival. This function is only needed if you manage to get an unchecked string, like in the games where user has to enter text as a response.''
''Note: This function does not escape % and _ by default, which are wildcards if used in an SQL "LIKE" statement. The developer must determine if this is desirable behavior.''

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

== Use bga 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.''

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

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

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

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

You can specify the expected class type, if you save a class and don't want it returned as a stdClass.
<pre>
$undo = new Undo($playerId, $moves);
$this->bga->globals->set(UNDO, $undo);

$undo = $this->bga->globals->get(UNDO); // will return an stdClass
$undo = $this->bga->globals->get(UNDO, class: Undo::class); // will return an Undo class
</pre>
Note: your class should be a plain object with no mandatory constructor params. Example:
<pre>
class Undo {
public function __construct(
public ?int $playerId = null,
public ?array $moves = null,
) {}
}
</pre>

'''bga->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->bga->globals->getAll();
...
$diceVariables = $this->bga->globals->getAll(DIE1, DIE2);
</pre>

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

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

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

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

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

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

'''bga->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->bga->globals->inc(PLAYED_ACTIONS_IN_CURRENT_TURN, 1);
...
$totalSpent = $this->bga->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>

'''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 must transition to a state in the action triggering this call, so the change of active player is notified to the front.

; $this->activePrevPlayer()
: Make the previous player active (in the natural player order).
: Note: you must transition to a state in the action triggering this call, so the change of active player is notified to the front.

; $this->gamestate->changeActivePlayer( $player_id )
: You can call this method to make any player active.
: Note: you must transition to a state in the action triggering this call, so the change of active player is notified to the front.

; $this->getActivePlayerId() string
: Return the "active_player" id
: Note: it does NOT mean that this player is active right now, because state type could be GAME or MULTIPLE_ACTIVE_PLAYER
: Note: avoid using this method in a MULTIPLE_ACTIVE_PLAYER state because it does not mean anything.
: In general, you shouldn't use this method. It is available as a magic param in getArgs / onEnteringState / act functions, and shouldn't be needed anywhere else.

=== 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 MULTIPLE_ACTIVE_PLAYER 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 MULTIPLE_ACTIVE_PLAYER 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" => MULTIPLE_ACTIVE_PLAYER,
'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, by transition name or State class name.

; $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, by transition name or State class name, 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, by transition name or State class name, 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 ACTIVE_PLAYER type gamestate, it will return an array with one value (the active player id).
: During a MULTIPLE_ACTIVE_PLAYER 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. Next state param is a transition name or State class name.
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 (or the state class name), and NOT the name of the target game state, see [[Your game state machine: states.inc.php]] for more information about states.
:''with State classes, you should not need it and you can just return the class name of the next state.''

'''$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
:''with State classes, you should not need it and you can just return the class name of the next state.''

; $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.
:''With auto-wired actions, you should not need it.''

; $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 actUnpass(int $currentPlayerId) {
$this->gamestate->checkPossibleAction('actUnpass'); // player changed mind about passing while others were thinking
$this->gamestate->setPlayersMultiactive([$currentPlayerId], 'error', false);
}

; $this->gamestate->getCurrentMainState()
: Returns the current main state, ignoring private parallel states.
: To get the state as an array, use <code>$this->gamestate->getCurrentMainState()->toArray()</code> and it will get a result similar to $this->gamestate->state()
: To get the state name, use <code>$this->gamestate->getCurrentMainState()->name</code>

; $this->gamestate->getCurrentMainStateId()
: Returns the current main state id, ignoring private parallel states. (previously, it was the state_id() function, that returned the state numer as a string).

; $this->gamestate->getCurrentState(int $playerId)
: Returns the current state for a player. If the player is in private parallel state, it means the current private state for this player.
: To get the state as an array, use <code>$this->gamestate->getCurrentState($playerId)->toArray()</code>
: To get the state name, use <code>$this->gamestate->getCurrentState($playerId)->name</code>

; $this->gamestate->getCurrentStateId(int $playerId)
: Returns the current state id for a player. If the player is in private parallel state, it means the current private state for this player.

; $this->gamestate->isMultiactiveState()
: Return true if we are in MULTIPLE_ACTIVE_PLAYER 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, or be a state class name.
: 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, by transition name or State class name.
: 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, by transition name or State class name.
: 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.) NewStateId can also be a state class name.
: 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 MULTIPLE_ACTIVE_PLAYER 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 ensure 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
});
</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>

On client side:

const lala ={a: 2, b: "string", c: [1,2,4]};
this.bgaPerformAction("actPlanComplexStuff", {
answer: JSON.stringify(lala)
});

It's also possible to decode the Json to a PHP class, similar to what is done with $this->globals->get with class parameter.

<pre>
use \Bga\GameFramework\Actions\Types\JsonParam;

...
class Answer {
public function __construct(
public int $a,
public string $b,
public array $c,
) {}
}
public function actPlanComplexStuff(#[JsonParam(class: Answer::class)] $answer) {} // specifying the class to map the json to
public function actPlanComplexStuff(#[JsonParam] Answer $answer) {} // same result, but the class is detected automatically by the framework thanks to the typed param.

public function actPlanMultipleComplexStuff(#[JsonParam(class: Answer::class)] array $answers) {} // can decode an array of Answer::class
</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) { ... }

#[CheckAction(false)]
public function actCancelChooseAction() {
$this->gamestate->checkPossibleAction('actCancelChooseAction');
...
}

</pre>

If you disable <code>checkAction</code>, you probably need to call <code>$this->gamestate->checkPossibleAction</code> instead at the beginning of your function. You likely also want to disable client checkAction calls implied by bgaPerformAction.

=== 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 (act* in State classes or Game.php). It is a MUST actually. At least one notification must be sent (but it includes state transition which sends it)
* game state transition (onEnteringState in State classes)
* 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]

Do not put HTML in the notifications. If you want to have pretty pictures in the log check this [[BGA_Studio_Cookbook#Inject_images_and_styled_html_in_the_log]].

=== Notify ===

'''bga->notify->all(string $notification_type,string | NotificationMessage $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 notify all example (from "Reversi"):

<pre>
$this->bga->notify->all( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),
array(
'player_id' => $player_id,
'player_name' => $this->getPlayerNameById($player_id),
'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 notify->player 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->bga->notify->all( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),
array(
'player_id' => $player_id,
'player_name' => $this->getPlayerNameById($player_id),
'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.

==== 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->bga->notify->all('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'] ]
]
]);

==== Sending private data to 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 to see a different message and get some private data.

You can use the <code>_private</code> arg to send private data to designated players, in a similar fashion of the onEnteringState <code>_private</code> flag. <code>_private</code> is an array that have the player id to send private information to, and the value if the different notification using NotificationMessage to send both the replacing log and the args that will be accessible on front side in args._private.

Example:
<pre>
use Bga\GameFramework\NotificationMessage;

(...)

$this->bga->notify->all('cardPicked', clienttranslate('${player_name} takes a secret card from the deck'), [
'playerId' => $playerId,
'player_name' => $this->getPlayerNameById($playerId),
'_private' => [
$playerId => new NotificationMessage(clienttranslate('You take ${_private.card_name} from the deck'), [
'card' => $card,
'card_name' => $this->getCardName($card),
'i18n' => ['card_name']
]),
],
]);
</pre>
Note that the message uses <code>${_private.card_name}</code> to access the data in the private args.

If you don't need to change the log, but only send private args, you can send an array of args instead of the NotificationMessage object.

If you add <code>_merge_private => true</code> next to <code>_private</code>, the private informations will be accessible in `args` instead of `args._private`.

If you want all your <code>_private</code> objects to be merged (state args and notif args), call <code>$this->bga->notify->alwaysMergePrivate();</code> in your Game constructor instead of adding the <code>_merge_private</code> flag on each arg.

==== 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->bga->notify->all(
'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 ===

'''bga->notify->player(int $player_id, string $notification_type, string | NotificationMessage $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 should be used only if you send some private information to a player, NOT wanting to send a public notification at the same time for the same reason. See paragraph '''Sending private data to some players''' that should cover most of your need to send a private notif.

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->bga->notify->player($player_id,'message', clienttranslate('You draw ${card_name}'), [ ... ]);
or
$this->bga->notify->player($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 notify->all() for any notification that spectators should get.

=== Notification decorators ===

'''bga->notify->addDecorator(callable $fn)'''

Add a decorator function that will be called on notification args before each call of notify->all and notify->player. ''Note: it won't work with deprecated functions notifyAllPlayers and notifyPlayer.''

To avoid duplicating the code in your notification args, you can register decorators in your Game __construct function.
// in construct :
$this->bga->notify->addDecorator(fn(string $message, array $args) => $this->decoratePlayerNameNotifArg($message, $args));
// could also be written this (ugly) way : $this->bga->notify->addDecorator([$this, 'decoratePlayerNameNotifArg']);

// with the Utils functions
public function decoratePlayerNameNotifArg(string $message, array $args): array {
// if the notif message contains ${player_name} but it isn't set in the args, add it on args from $args['player_id']
if (isset($args['player_id']) && !isset($args['player_name']) && str_contains($message, '${player_name}')) {
$args['player_name'] = $this->getPlayerNameById($args['player_id']);
}
return $args;
}
With this example, you can call <code>$this->bga->notify->all("pass", clienttranslate('${player_name} passes'), [ "player_id" => $player_id ]);</code> and the front will receive the player_name arg along the player_id one.

You can also declare it as an inline function :
// in construct :
this->bga->notify->addDecorator(function(string $message, array $args) {
// if the notif message contains ${card_name} but it isn't set in the args, add it on args from $args['card']
// also set it up for translations by adding it to the i18n array
if (isset($args['card']) && !isset($args['card_name']) && str_contains($message, '${card_name}')) {
$args['card_name'] = $args['card']->name;
$args['i18n'][] = ['card_name'];
}
return $args;
});
With this example, you can call <code>$this->bga->notify->all("playCard", clienttranslate('${player_name} plays ${card_name}'), [ "player_id" => $player_id, card => $card ]);</code> and the front will receive the card_name arg with the flag to translate it.

== 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.json]] to see how you define statistics for your game.

'''bga->tableStats->init(string|array $nameOrNames, int|float|bool $value)'''

'''bga->playerStats->init(string|array $nameOrNames, int|float|bool $value, bool $updateTableStat = false)'''

previously : initStat( $table_or_player, $name, $value)

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 xxxStats->set or xxxStats->inc, 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.

'$nameOrNames' is the name of your statistic, as it has been defined in your stats.inc.php file, or an array of those names.

'$value' is the initial value of the statistic.

'updateTableStat' for playerStats initiates the tableStats of the same name, so if you store for example 'playedTurns' in both 'table' and 'player' call only <code>bga->playerStats->init('playedTurns', 0, true)</code> and it will init for both 'table' and 'player'.

'''bga->tableStats->set(string $name, int|float|bool $value)'''

'''bga->playerStats->set(string $name, int|float|bool $value, int $player_id)'''

'''bga->playerStats->setAll(string $name, int|float|bool $value)''' (same as set, but for all players at once)

previously : setStat( $value, $name, $player_id = null )

Set a statistic $name to $value.

'''bga->tableStats->inc(string $name, int|float $delta)'''

'''bga->playerStats->inc(string $name, int|float $delta, int $player_id, bool $updateTableStat = false)'''

'''bga->playerStats->incAll(string $name, int|float $delta)''' (same as inc, but for all players at once)

previously : incStat( $delta, $name, $player_id = null )

Increment (or decrement) specified statistic value by $delta value. Same behavior as setStat function, except you cannot increment boolean values. 'updateTableStat' will also inc the tableStats of the same name.

'''bga->tableStats->get(string $name): int|float|bool'''

'''bga->playerStats->get(string $name, int $player_id): int|float|bool'''

previously : getStat( $name, $player_id = null )

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

'''bga->playerStats->getAll(string $name): array'''

Returns the values for all players, as an associative array $player_id => $value

== 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 using $this->bga->playerScore. bga->playerScore is a [[PlayerCounter and TableCounter|PlayerCounter]], so it has the same methods.

Examples:
<pre>

// +2 points to active player
$this->bga->playerScore->inc($activePlayerId, 2);

// Set score of active player to 5
$this->bga->playerScore->set($activePlayerId, 5);

</pre>

=== Tie breaker ===

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

Tie breaker is using $this->bga->playerScoreAux. It is updated exactly like $this->bga->playerScore. bga->playerScoreAux is a [[PlayerCounter and TableCounter|PlayerCounter]], so it has the same methods.

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 "playerScoreAux" functionality, you must describe the formula to use in your gameinfos.jsonc file like this:

<pre>
"tie_breaker_description": "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.

Note: if you need to need you score_aux to be reverse (lowest value wins), please contact Studio support to get a solution.

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

=== Reverse scoring and reverse tie-breaker ===

If your game has a reverse scoring (lowest value wins) or reverse tie-breaker (lowest tie-breaker wins), you need to set-up a GameResult object to tell BGA this specificity.

On your last state (usually EndScore.php), instead of returning 99 to go the end game, return a GameResult. returning a GameResult object in a State class will then go the end game.
<pre>
use Bga\GameFramework\GameResult\GameResult;
use Bga\GameFramework\GameResult\Player;

...

public function onEnteringState() {
...

$playersDb = $this->game->getCollectionFromDb("SELECT * FROM `player`");
$players = Player::fromPlayersDb($playersDb);
return GameResult::individualRanking($players, reverseScore: true);
}
</pre>
For reverse tie-breaker, it will be `reverseScoreAux: true`.

If your game has running tables with negative scores to handle reverse scoring and you want to use the reverse scoring, add this just before the return line:
<pre>
if ($this->bga->playerScore->getMin() < 0) {
foreach ($players as &$player) {
$player->score = -$player->score;
}
}
</pre>
So game started before the change will reverse the score (negative to positive) before creating the GameResult object.
And anywhere you change the score, you must continue the way it was started :
<pre>
$addedPoints = 3;
if ($this->bga->playerScore->getMin() < 0) {
$addedPoints = -$addedPoints;
}
$this->bga->playerScore->inc($playerId, $addedPoints);
</pre>
If there are negative score, the game will continue with negative scores, else it will continue with positive scores.

=== Result neutralization ===

when a player quits a running table, the results of the game will be neutralized (everyone has score set to 1, except the first quitter that will be at 0 and will be ranked last in addition to reputation drop). We cannot keep the ranking among the remaining players, as the quitter being replaced by a zombie might unbalance the rest of the game interaction, for example the player playing just after can get advantages with the situation.

For some games where there is almost no interaction between player, like some roll & write games, there is no real reason to neutralize the game results when a player quits. In that case, you can ask the Studio Support to activate the "Keep ranking on player quit" flag for your game. The zombie mode must be fully functional to allow the game to continue with leavers. Note that the BGA team might refuse to activate it, if it is considered the zombie player will unbalance the results of the remaining players.

When this flag is activated, a player quitting a game will still be penalized, but the ranking you set at the end of the game will stay, and the eliminated player(s) will have their score set to -1. It also means if a second player quits the game, he will also be penalized, because he has no reason to quit and can continue the game. If the game ends with 2 remaining players, it's now possible for one of them to concede.

To request this mode, click on "Contact us / Support" at the bottom of the page in Studio and then work through to a "My problem has not been solved" and then enter your request. The flag can be set independently in Studio and Production, so make sure to request it for both (unless you just want to experiment in Studio).

Note: the flag will fully work for games started AFTER activation. It may display incorrect messages for games started before the activation but players left after. For this reason, it's best to request it when going to alpha, else accept some strange bug reports about this situation, that will solve itself when all existing tables are started after the activation.

=== Co-operative game ===

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

Add the following in gameinfos.jsonc :
"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.jsonc:

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

* In your PHP code:
$this->eliminatePlayer( <player_to_eliminate_id> );
* Player to eliminate should NOT be active anymore at the end of the action that triggers the eliminatePlayer function.
* 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:''' If you eliminate the last player, make sure the action will end by going to the end game state. If it doesn't, BGA will jump straight to it, without calling your end score state or anything similar.

=== Player concede ===

It should be rarely needed, but if you absolutely need to run some code when a player concedes, you can create a function called onConcede in the Game class like this :
<pre>
function onConcede() {
$this->bga->notify->all('test', 'Something to do when the player concedes');
}
</pre>
If you want to get the conceder id:
<pre>
function onConcede($concederTeam) {
$this->bga->notify->all('test', 'Something to do when the player concedes '.$concederTeam->players[0]->id);
}
</pre>

Never change state on this function. It should be limited to computing stats or similar small stuff.

To not break the game end, any exception triggered by this function will be catched and simply logged, so make sure your code stay simple and never trigger an exception and it will be hard to detect!

== Reflexion time ==

; function giveExtraTime( $player_id, $specific_time=null )
: Give standard extra time to this player in real time game. It does not affect turn based games.
: Standard extra time (when you don't pass $specific_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 "specific_time" argument (rarely used). Using $specific_time is not recommended as this does not adjust for the game speed.
: Important Note: the total reflection time cannot be more than time allowed for the turn. So you can never make it 10 minutes if turn max is 3 min (the max is determined by game speed). As a consequence there is no point adding this at the begging of the turn of in game setup, it only matters after the action which does not lead to turn end (which is when this player becomes inactive).
: Note: standard extra time is automatically doubled for begginer

function actionBla($args) {
$this->checkAction('actionBla');
$playerId = (int)$this->getActivePlayerId();
$this->giveExtraTime($player_id);
// do some inter-turn action
$this->notifyAll(...);
// no state transition as this player did an action but stayed active
}

; '''$this->bga->tableOptions->isTurnBased(): bool'''
: Returns true if game is turn based
:
; '''$this->bga->tableOptions->isRealTime(): bool'''
: Returns true if game is in real time

== 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 actUndo() {
$this->undoRestorePoint();
return PlayTurn::class; // 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().

=== Manually remove game logs ===
Only use it if you have custom undo and you fully understand how logs and replay works!

; $this->bga->logs->getCurrentMoveId()
: Returns the current move id, when doing an action, that should be stored along informations to undo.

; $this->bga->logs->remove(int $startMoveId)
: Remove all logs from a move id that was stored during an action using `getCurrentMoveId()`. The game should be in the exact same point as it was before the stored action!

Example:
<pre>
// in the action code, do all the action code, notify it, and store the custom undo
$this->bga->globals->set(UNDO_ACTION, new Undo(
movedTiles: $tiles,
moveId: $this->bga->logs->getCurrentMoveId(),
));

return ConfirmAction::class;
</pre>
<pre>
$undo = $this->bga->globals->get(UNDO_ACTION);
// in the undo action code, do all the revert action code, notify it, then remove the logs
$this->bga->logs->remove($undo->moveId);
// don't do any action/notif after removing the logs
return PlayAction::class;
</pre>

== 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 UserException(string|NotificationMessage $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 will be displayed to the player, as it's a UserException, the error message should be translated (with clientranslate(), and if there are args wrap them into a NotificationMessage)
: Throwing such an exception is NOT considered a bug, so it is not traced in BGA error logs.

Note: if your IDE doesn't do it for you, you'll need to add <code>use Bga\GameFramework\UserException;</code> at the top of your file.

Example from Gomoku:
<pre>
throw new UserException(clienttranslate("There is already a stone on this intersection, you can't play there"));
</pre>
Example with translated UserException using args :
<pre>
throw new UserException(new NotificationMessage(clienttranslate('You must play a card bigger than ${min}', [min => $minCardValue])));
</pre>

; throw new SystemException (string|NotificationMessage $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.

; throw new VisibleSystemException (string|NotificationMessage $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.
: it should not be translated, as it's just to bring debug details to you when the player reports the issue.

== Zombie mode ==

When a player leaves a game for any reason (expelled, quit), he becomes a "zombie player". You must implement a Zombie that will handle the role of the leaver player

Read [[Zombie Mode|Zombie mode]] to get all details of the expected code.

== User preferences ==
'''$this->bga->userPreferences->get(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.

''To test it, you can set your preferred color on your BGA Studio account.''

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

On your gameinfos.jsonc 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->bga->legacy->setTeam( $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.

; $this->'''bga->'''legacy->set(string $key, int $playerId, mixed $value, int $ttl = 365)
: ( deprecated alias: $this->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).

; $this->'''bga->'''legacy->get(string $key, int $playerId, mixed $defaultValue = null)
: ( deprecated alias: $this->retrieveLegacyData($player_id, $key) ⚠️ this alias was returning a JSON-encoded value, while the get function returns the real value )
: 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

; $this->'''bga->'''legacy->delete(string $key, int $playerId)
: ( deprecated alias: $this->removeLegacyData($player_id, $key) )
: Remove some legacy data with the given key
: (useful to free some data to avoid going over 64k)

; $this->'''bga->'''legacy->setTeam(mixed $value, int $ttl = 365)
: ( deprecated alias: 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

; $this->'''bga->'''legacy->getTeam(mixed $defaultValue = null)
: ( deprecated alias: $this->retrieveLegacyData() ⚠️ this alias was returning a JSON-encoded value, while the getTeam function returns the real value )
: Same as retrieveLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)

; $this->'''bga->'''legacy->deleteTeam()
: ( deprecated alias: $this->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.

== Tournament API (🚧 Beta) ==

The Tournament API is meant only for tournament encounters. It lets you persist per‑player data within a tournament and access deterministic seeds shared by all encounters of a tournament step.

Do not use this for preferences or long‑term progression: if a table is not linked to a tournament, these requests will fail, and all tournament data is wiped when the tournament ends anyway.

You can use it for:
* enforcing tournament‑wide constraints (ex: keep the same deck across all rounds)
* deterministic setup shared across a tournament step (ex: generate the same map layout for all encounters in a step)
; $this->'''bga->'''tournament->isTournament()
: Returns true if this table is a tournament encounter.
: Use this to guard tournament‑only logic.

; $this->'''bga->'''tournament->getSeedInfo()
: Returns an associative array containing deterministic seeds for tournament encounters.
: Keys:
:* <code>tournament_seed</code>: stable across the whole tournament.
:* <code>step_seed</code>: stable across a tournament step (same for all encounters in that step).
:* <code>parent_tournament_seed</code>: stable across the parent tournament (the reference tournament for sub-tournaments of Groups Stage tournament mode).
:
: Note: This call is already guarded internally, no external call is made unless the table is a tournament encounter.

; $this->'''bga->'''tournament->storePlayerGameData(int $playerId, string $key, mixed $data)
: Store per‑player game data for the current tournament.
: Data is JSON‑encoded automatically.
: The cumulative size of all data stored for a player in a tournament (even over multiple keys) is limited to 64 KiB.
: Keys must be 1–16 characters and letters/numbers only.

; $this->'''bga->'''tournament->retrievePlayerGameData(int $playerId, string $key)
: Retrieve per‑player game data for the current tournament.
: If `$key` contains '%', returns an array of key => value pairs (or [] if no match).
: Otherwise, returns a single value (or null if no match).
: Returned values are JSON‑decoded automatically.

; $this->'''bga->'''tournament->removePlayerGameData(int $playerId, string $key)
: Remove per‑player game data for the current tournament.
: You can use '%' in `$key` to remove multiple entries at once.
: All tournament data is removed automatically when the tournament is finished.

== 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.jsonc 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": { "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.jsonc.

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.

'''getBgaEnvironment(): string'''
:Returns "studio" for studio and "prod" for production environment (i.e. where games current runs). Only useful for debbugging hooks.
Note: alpha server is also "prod"

== Creating other classes ==

You can create other classes in the <code>modules/php</code> dir, next to your <code>Game.php</code> file.

If they are names following the PSR-4, they will be autoloaded by BGA (no require_once needed). This doesn't work for the "legacy way" (=<code>YourGameName.game.php</code> at the game root dir).

For example, writing <code>new ScoreManager()</code> in your Game file will try to load the class <code>ScoreManager</code> of namespace <code>Bga\Games\YourGameName</code> in <code>modules/php/ScoreManager.php</code>

Don't forget to add namespace <code>Bga\Games\YourGameName;</code> at the beginning of your module.

You can even put these classes in sublevels : the class <code>Bga\Games\YourGameName\Cards\StandardCard</code> will be automatically loaded if it is stored in <code>modules/php/Cards/StandardCard.php</code>

[[Category:Studio]]

Main game logic: Game.php

2026-05-08T11:32:55Z

BaronFraser: /* Sending private data to some players */

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

'''Note:''' this file is now named Game.php, located in the modules/php directory. If you see it named yourgamename.game.php in the root dir, it's the legacy usage. In the legacy usage, the namepaces don't exists.

== 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.
getAllDatas accepts a magic parameter <code>int $currentPlayerId</code> (or <code>int $currentPlayerNo</code>) to fetch the information from the point of view of the current player id (or no). It should not have any other parameter.
* '''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!

; getPlayerCount() (or getPlayersNumber() that is an alias )
: 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.

; <nowiki>getActivePlayerId(): string</nowiki>
: 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.
: In general, you shouldn't use this method. It is available as a magic param in getArgs / onEnteringState / act functions, and shouldn't be needed anywhere else.

; 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

; getPlayerNameByNo($playerNo)
: Get the name by no

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

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

; getPlayerIdByNo(int $playerNo) int
: Get the player id by player no.

; 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) string
: 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. It is available as a magic param in act functions, and also in getAllDatas, and shouldn't be needed anywhere.
: '''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). Can be easily replaced by $this->getPlayerNameById($currentPlayerId);

; 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). Can be easily replaced by $this->getPlayerColorById($currentPlayerId);

; 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
: Be careful using this method (see above). Should never be needed, zombie players should behave like real players, and everything specific to zombie should be set in the zombie method only.

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

For player score and tiebreaker, see [[Main game logic: Game.php#Manage player scores and Tie breaker]]

== 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, '''as long as the SQL statement uses single quotes around the string. This is important!'''
''Note: if you using standard types in ajax actions, like AT_alphanum it is sanitized before arrival. This function is only needed if you manage to get an unchecked string, like in the games where user has to enter text as a response.''
''Note: This function does not escape % and _ by default, which are wildcards if used in an SQL "LIKE" statement. The developer must determine if this is desirable behavior.''

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

== Use bga 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.''

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

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

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

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

You can specify the expected class type, if you save a class and don't want it returned as a stdClass.
<pre>
$undo = new Undo($playerId, $moves);
$this->bga->globals->set(UNDO, $undo);

$undo = $this->bga->globals->get(UNDO); // will return an stdClass
$undo = $this->bga->globals->get(UNDO, class: Undo::class); // will return an Undo class
</pre>
Note: your class should be a plain object with no mandatory constructor params. Example:
<pre>
class Undo {
public function __construct(
public ?int $playerId = null,
public ?array $moves = null,
) {}
}
</pre>

'''bga->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->bga->globals->getAll();
...
$diceVariables = $this->bga->globals->getAll(DIE1, DIE2);
</pre>

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

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

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

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

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

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

'''bga->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->bga->globals->inc(PLAYED_ACTIONS_IN_CURRENT_TURN, 1);
...
$totalSpent = $this->bga->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>

'''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 must transition to a state in the action triggering this call, so the change of active player is notified to the front.

; $this->activePrevPlayer()
: Make the previous player active (in the natural player order).
: Note: you must transition to a state in the action triggering this call, so the change of active player is notified to the front.

; $this->gamestate->changeActivePlayer( $player_id )
: You can call this method to make any player active.
: Note: you must transition to a state in the action triggering this call, so the change of active player is notified to the front.

; $this->getActivePlayerId() string
: Return the "active_player" id
: Note: it does NOT mean that this player is active right now, because state type could be GAME or MULTIPLE_ACTIVE_PLAYER
: Note: avoid using this method in a MULTIPLE_ACTIVE_PLAYER state because it does not mean anything.
: In general, you shouldn't use this method. It is available as a magic param in getArgs / onEnteringState / act functions, and shouldn't be needed anywhere else.

=== 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 MULTIPLE_ACTIVE_PLAYER 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 MULTIPLE_ACTIVE_PLAYER 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" => MULTIPLE_ACTIVE_PLAYER,
'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, by transition name or State class name.

; $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, by transition name or State class name, 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, by transition name or State class name, 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 ACTIVE_PLAYER type gamestate, it will return an array with one value (the active player id).
: During a MULTIPLE_ACTIVE_PLAYER 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. Next state param is a transition name or State class name.
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 (or the state class name), and NOT the name of the target game state, see [[Your game state machine: states.inc.php]] for more information about states.
:''with State classes, you should not need it and you can just return the class name of the next state.''

'''$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
:''with State classes, you should not need it and you can just return the class name of the next state.''

; $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.
:''With auto-wired actions, you should not need it.''

; $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 actUnpass(int $currentPlayerId) {
$this->gamestate->checkPossibleAction('actUnpass'); // player changed mind about passing while others were thinking
$this->gamestate->setPlayersMultiactive([$currentPlayerId], 'error', false);
}

; $this->gamestate->getCurrentMainState()
: Returns the current main state, ignoring private parallel states.
: To get the state as an array, use <code>$this->gamestate->getCurrentMainState()->toArray()</code> and it will get a result similar to $this->gamestate->state()
: To get the state name, use <code>$this->gamestate->getCurrentMainState()->name</code>

; $this->gamestate->getCurrentMainStateId()
: Returns the current main state id, ignoring private parallel states. (previously, it was the state_id() function, that returned the state numer as a string).

; $this->gamestate->getCurrentState(int $playerId)
: Returns the current state for a player. If the player is in private parallel state, it means the current private state for this player.
: To get the state as an array, use <code>$this->gamestate->getCurrentState($playerId)->toArray()</code>
: To get the state name, use <code>$this->gamestate->getCurrentState($playerId)->name</code>

; $this->gamestate->getCurrentStateId(int $playerId)
: Returns the current state id for a player. If the player is in private parallel state, it means the current private state for this player.

; $this->gamestate->isMultiactiveState()
: Return true if we are in MULTIPLE_ACTIVE_PLAYER 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, or be a state class name.
: 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, by transition name or State class name.
: 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, by transition name or State class name.
: 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.) NewStateId can also be a state class name.
: 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 MULTIPLE_ACTIVE_PLAYER 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 ensure 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
});
</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>

On client side:

const lala ={a: 2, b: "string", c: [1,2,4]};
this.bgaPerformAction("actPlanComplexStuff", {
answer: JSON.stringify(lala)
});

It's also possible to decode the Json to a PHP class, similar to what is done with $this->globals->get with class parameter.

<pre>
use \Bga\GameFramework\Actions\Types\JsonParam;

...
class Answer {
public function __construct(
public int $a,
public string $b,
public array $c,
) {}
}
public function actPlanComplexStuff(#[JsonParam(class: Answer::class)] $answer) {} // specifying the class to map the json to
public function actPlanComplexStuff(#[JsonParam] Answer $answer) {} // same result, but the class is detected automatically by the framework thanks to the typed param.

public function actPlanMultipleComplexStuff(#[JsonParam(class: Answer::class)] array $answers) {} // can decode an array of Answer::class
</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) { ... }

#[CheckAction(false)]
public function actCancelChooseAction() {
$this->gamestate->checkPossibleAction('actCancelChooseAction');
...
}

</pre>

If you disable <code>checkAction</code>, you probably need to call <code>$this->gamestate->checkPossibleAction</code> instead at the beginning of your function. You likely also want to disable client checkAction calls implied by bgaPerformAction.

=== 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 (act* in State classes or Game.php). It is a MUST actually. At least one notification must be sent (but it includes state transition which sends it)
* game state transition (onEnteringState in State classes)
* 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]

Do not put HTML in the notifications. If you want to have pretty pictures in the log check this [[BGA_Studio_Cookbook#Inject_images_and_styled_html_in_the_log]].

=== Notify ===

'''bga->notify->all(string $notification_type,string | NotificationMessage $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 notify all example (from "Reversi"):

<pre>
$this->bga->notify->all( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),
array(
'player_id' => $player_id,
'player_name' => $this->getPlayerNameById($player_id),
'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 notify->player 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->bga->notify->all( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),
array(
'player_id' => $player_id,
'player_name' => $this->getPlayerNameById($player_id),
'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.

==== 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->bga->notify->all('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'] ]
]
]);

==== Sending private data to 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 to see a different message and get some private data.

You can use the <code>_private</code> arg to send private data to designated players, in a similar fashion of the onEnteringState <code>_private</code> flag. <code>_private</code> is an array that have the player id to send private information to, and the value if the different notification using NotificationMessage to send both the replacing log and the args that will be accessible on front side in args._private.

Example:
<pre>
use Bga\GameFramework\NotificationMessage;

(...)

$this->bga->notify->all('cardPicked', clienttranslate('${player_name} takes a secret card from the deck'), [
'playerId' => $playerId,
'player_name' => $this->getPlayerNameById($playerId),
'_private' => [
$playerId => new NotificationMessage(clienttranslate('You take ${_private.card_name} from the deck'), [
'card' => $card,
'card_name' => $this->getCardName($card),
'i18n' => ['card_name']
]),
],
]);
</pre>
Note that the message uses <code>${_private.card_name}</code> to access the data in the private args.

If you don't need to change the log, but only send private args, you can send an array of args instead of the NotificationMessage object.

If you add <code>_merge_private => true</code> next to <code>_private</code>, the private informations will be accessible in `args` instead of `args._private`. This seems to be required for your interceptFormatStringToken to intercept and alter private args when displaying in the notification log.

If you want all your <code>_private</code> objects to be merged (state args and notif args), call <code>$this->bga->notify->alwaysMergePrivate();</code> in your Game constructor instead of adding the <code>_merge_private</code> flag on each arg.

==== 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->bga->notify->all(
'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 ===

'''bga->notify->player(int $player_id, string $notification_type, string | NotificationMessage $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 should be used only if you send some private information to a player, NOT wanting to send a public notification at the same time for the same reason. See paragraph '''Sending private data to some players''' that should cover most of your need to send a private notif.

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->bga->notify->player($player_id,'message', clienttranslate('You draw ${card_name}'), [ ... ]);
or
$this->bga->notify->player($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 notify->all() for any notification that spectators should get.

=== Notification decorators ===

'''bga->notify->addDecorator(callable $fn)'''

Add a decorator function that will be called on notification args before each call of notify->all and notify->player. ''Note: it won't work with deprecated functions notifyAllPlayers and notifyPlayer.''

To avoid duplicating the code in your notification args, you can register decorators in your Game __construct function.
// in construct :
$this->bga->notify->addDecorator(fn(string $message, array $args) => $this->decoratePlayerNameNotifArg($message, $args));
// could also be written this (ugly) way : $this->bga->notify->addDecorator([$this, 'decoratePlayerNameNotifArg']);

// with the Utils functions
public function decoratePlayerNameNotifArg(string $message, array $args): array {
// if the notif message contains ${player_name} but it isn't set in the args, add it on args from $args['player_id']
if (isset($args['player_id']) && !isset($args['player_name']) && str_contains($message, '${player_name}')) {
$args['player_name'] = $this->getPlayerNameById($args['player_id']);
}
return $args;
}
With this example, you can call <code>$this->bga->notify->all("pass", clienttranslate('${player_name} passes'), [ "player_id" => $player_id ]);</code> and the front will receive the player_name arg along the player_id one.

You can also declare it as an inline function :
// in construct :
this->bga->notify->addDecorator(function(string $message, array $args) {
// if the notif message contains ${card_name} but it isn't set in the args, add it on args from $args['card']
// also set it up for translations by adding it to the i18n array
if (isset($args['card']) && !isset($args['card_name']) && str_contains($message, '${card_name}')) {
$args['card_name'] = $args['card']->name;
$args['i18n'][] = ['card_name'];
}
return $args;
});
With this example, you can call <code>$this->bga->notify->all("playCard", clienttranslate('${player_name} plays ${card_name}'), [ "player_id" => $player_id, card => $card ]);</code> and the front will receive the card_name arg with the flag to translate it.

== 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.json]] to see how you define statistics for your game.

'''bga->tableStats->init(string|array $nameOrNames, int|float|bool $value)'''

'''bga->playerStats->init(string|array $nameOrNames, int|float|bool $value, bool $updateTableStat = false)'''

previously : initStat( $table_or_player, $name, $value)

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 xxxStats->set or xxxStats->inc, 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.

'$nameOrNames' is the name of your statistic, as it has been defined in your stats.inc.php file, or an array of those names.

'$value' is the initial value of the statistic.

'updateTableStat' for playerStats initiates the tableStats of the same name, so if you store for example 'playedTurns' in both 'table' and 'player' call only <code>bga->playerStats->init('playedTurns', 0, true)</code> and it will init for both 'table' and 'player'.

'''bga->tableStats->set(string $name, int|float|bool $value)'''

'''bga->playerStats->set(string $name, int|float|bool $value, int $player_id)'''

'''bga->playerStats->setAll(string $name, int|float|bool $value)''' (same as set, but for all players at once)

previously : setStat( $value, $name, $player_id = null )

Set a statistic $name to $value.

'''bga->tableStats->inc(string $name, int|float $delta)'''

'''bga->playerStats->inc(string $name, int|float $delta, int $player_id, bool $updateTableStat = false)'''

'''bga->playerStats->incAll(string $name, int|float $delta)''' (same as inc, but for all players at once)

previously : incStat( $delta, $name, $player_id = null )

Increment (or decrement) specified statistic value by $delta value. Same behavior as setStat function, except you cannot increment boolean values. 'updateTableStat' will also inc the tableStats of the same name.

'''bga->tableStats->get(string $name): int|float|bool'''

'''bga->playerStats->get(string $name, int $player_id): int|float|bool'''

previously : getStat( $name, $player_id = null )

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

'''bga->playerStats->getAll(string $name): array'''

Returns the values for all players, as an associative array $player_id => $value

== 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 using $this->bga->playerScore. bga->playerScore is a [[PlayerCounter and TableCounter|PlayerCounter]], so it has the same methods.

Examples:
<pre>

// +2 points to active player
$this->bga->playerScore->inc($activePlayerId, 2);

// Set score of active player to 5
$this->bga->playerScore->set($activePlayerId, 5);

</pre>

=== Tie breaker ===

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

Tie breaker is using $this->bga->playerScoreAux. It is updated exactly like $this->bga->playerScore. bga->playerScoreAux is a [[PlayerCounter and TableCounter|PlayerCounter]], so it has the same methods.

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 "playerScoreAux" functionality, you must describe the formula to use in your gameinfos.jsonc file like this:

<pre>
"tie_breaker_description": "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.

Note: if you need to need you score_aux to be reverse (lowest value wins), please contact Studio support to get a solution.

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

=== Reverse scoring and reverse tie-breaker ===

If your game has a reverse scoring (lowest value wins) or reverse tie-breaker (lowest tie-breaker wins), you need to set-up a GameResult object to tell BGA this specificity.

On your last state (usually EndScore.php), instead of returning 99 to go the end game, return a GameResult. returning a GameResult object in a State class will then go the end game.
<pre>
use Bga\GameFramework\GameResult\GameResult;
use Bga\GameFramework\GameResult\Player;

...

public function onEnteringState() {
...

$playersDb = $this->game->getCollectionFromDb("SELECT * FROM `player`");
$players = Player::fromPlayersDb($playersDb);
return GameResult::individualRanking($players, reverseScore: true);
}
</pre>
For reverse tie-breaker, it will be `reverseScoreAux: true`.

If your game has running tables with negative scores to handle reverse scoring and you want to use the reverse scoring, add this just before the return line:
<pre>
if ($this->bga->playerScore->getMin() < 0) {
foreach ($players as &$player) {
$player->score = -$player->score;
}
}
</pre>
So game started before the change will reverse the score (negative to positive) before creating the GameResult object.
And anywhere you change the score, you must continue the way it was started :
<pre>
$addedPoints = 3;
if ($this->bga->playerScore->getMin() < 0) {
$addedPoints = -$addedPoints;
}
$this->bga->playerScore->inc($playerId, $addedPoints);
</pre>
If there are negative score, the game will continue with negative scores, else it will continue with positive scores.

=== Result neutralization ===

when a player quits a running table, the results of the game will be neutralized (everyone has score set to 1, except the first quitter that will be at 0 and will be ranked last in addition to reputation drop). We cannot keep the ranking among the remaining players, as the quitter being replaced by a zombie might unbalance the rest of the game interaction, for example the player playing just after can get advantages with the situation.

For some games where there is almost no interaction between player, like some roll & write games, there is no real reason to neutralize the game results when a player quits. In that case, you can ask the Studio Support to activate the "Keep ranking on player quit" flag for your game. The zombie mode must be fully functional to allow the game to continue with leavers. Note that the BGA team might refuse to activate it, if it is considered the zombie player will unbalance the results of the remaining players.

When this flag is activated, a player quitting a game will still be penalized, but the ranking you set at the end of the game will stay, and the eliminated player(s) will have their score set to -1. It also means if a second player quits the game, he will also be penalized, because he has no reason to quit and can continue the game. If the game ends with 2 remaining players, it's now possible for one of them to concede.

To request this mode, click on "Contact us / Support" at the bottom of the page in Studio and then work through to a "My problem has not been solved" and then enter your request. The flag can be set independently in Studio and Production, so make sure to request it for both (unless you just want to experiment in Studio).

Note: the flag will fully work for games started AFTER activation. It may display incorrect messages for games started before the activation but players left after. For this reason, it's best to request it when going to alpha, else accept some strange bug reports about this situation, that will solve itself when all existing tables are started after the activation.

=== Co-operative game ===

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

Add the following in gameinfos.jsonc :
"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.jsonc:

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

* In your PHP code:
$this->eliminatePlayer( <player_to_eliminate_id> );
* Player to eliminate should NOT be active anymore at the end of the action that triggers the eliminatePlayer function.
* 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:''' If you eliminate the last player, make sure the action will end by going to the end game state. If it doesn't, BGA will jump straight to it, without calling your end score state or anything similar.

=== Player concede ===

It should be rarely needed, but if you absolutely need to run some code when a player concedes, you can create a function called onConcede in the Game class like this :
<pre>
function onConcede() {
$this->bga->notify->all('test', 'Something to do when the player concedes');
}
</pre>
If you want to get the conceder id:
<pre>
function onConcede($concederTeam) {
$this->bga->notify->all('test', 'Something to do when the player concedes '.$concederTeam->players[0]->id);
}
</pre>

Never change state on this function. It should be limited to computing stats or similar small stuff.

To not break the game end, any exception triggered by this function will be catched and simply logged, so make sure your code stay simple and never trigger an exception and it will be hard to detect!

== Reflexion time ==

; function giveExtraTime( $player_id, $specific_time=null )
: Give standard extra time to this player in real time game. It does not affect turn based games.
: Standard extra time (when you don't pass $specific_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 "specific_time" argument (rarely used). Using $specific_time is not recommended as this does not adjust for the game speed.
: Important Note: the total reflection time cannot be more than time allowed for the turn. So you can never make it 10 minutes if turn max is 3 min (the max is determined by game speed). As a consequence there is no point adding this at the begging of the turn of in game setup, it only matters after the action which does not lead to turn end (which is when this player becomes inactive).
: Note: standard extra time is automatically doubled for begginer

function actionBla($args) {
$this->checkAction('actionBla');
$playerId = (int)$this->getActivePlayerId();
$this->giveExtraTime($player_id);
// do some inter-turn action
$this->notifyAll(...);
// no state transition as this player did an action but stayed active
}

; '''$this->bga->tableOptions->isTurnBased(): bool'''
: Returns true if game is turn based
:
; '''$this->bga->tableOptions->isRealTime(): bool'''
: Returns true if game is in real time

== 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 actUndo() {
$this->undoRestorePoint();
return PlayTurn::class; // 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().

=== Manually remove game logs ===
Only use it if you have custom undo and you fully understand how logs and replay works!

; $this->bga->logs->getCurrentMoveId()
: Returns the current move id, when doing an action, that should be stored along informations to undo.

; $this->bga->logs->remove(int $startMoveId)
: Remove all logs from a move id that was stored during an action using `getCurrentMoveId()`. The game should be in the exact same point as it was before the stored action!

Example:
<pre>
// in the action code, do all the action code, notify it, and store the custom undo
$this->bga->globals->set(UNDO_ACTION, new Undo(
movedTiles: $tiles,
moveId: $this->bga->logs->getCurrentMoveId(),
));

return ConfirmAction::class;
</pre>
<pre>
$undo = $this->bga->globals->get(UNDO_ACTION);
// in the undo action code, do all the revert action code, notify it, then remove the logs
$this->bga->logs->remove($undo->moveId);
// don't do any action/notif after removing the logs
return PlayAction::class;
</pre>

== 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 UserException(string|NotificationMessage $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 will be displayed to the player, as it's a UserException, the error message should be translated (with clientranslate(), and if there are args wrap them into a NotificationMessage)
: Throwing such an exception is NOT considered a bug, so it is not traced in BGA error logs.

Note: if your IDE doesn't do it for you, you'll need to add <code>use Bga\GameFramework\UserException;</code> at the top of your file.

Example from Gomoku:
<pre>
throw new UserException(clienttranslate("There is already a stone on this intersection, you can't play there"));
</pre>
Example with translated UserException using args :
<pre>
throw new UserException(new NotificationMessage(clienttranslate('You must play a card bigger than ${min}', [min => $minCardValue])));
</pre>

; throw new SystemException (string|NotificationMessage $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.

; throw new VisibleSystemException (string|NotificationMessage $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.
: it should not be translated, as it's just to bring debug details to you when the player reports the issue.

== Zombie mode ==

When a player leaves a game for any reason (expelled, quit), he becomes a "zombie player". You must implement a Zombie that will handle the role of the leaver player

Read [[Zombie Mode|Zombie mode]] to get all details of the expected code.

== User preferences ==
'''$this->bga->userPreferences->get(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.

''To test it, you can set your preferred color on your BGA Studio account.''

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

On your gameinfos.jsonc 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->bga->legacy->setTeam( $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.

; $this->'''bga->'''legacy->set(string $key, int $playerId, mixed $value, int $ttl = 365)
: ( deprecated alias: $this->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).

; $this->'''bga->'''legacy->get(string $key, int $playerId, mixed $defaultValue = null)
: ( deprecated alias: $this->retrieveLegacyData($player_id, $key) ⚠️ this alias was returning a JSON-encoded value, while the get function returns the real value )
: 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

; $this->'''bga->'''legacy->delete(string $key, int $playerId)
: ( deprecated alias: $this->removeLegacyData($player_id, $key) )
: Remove some legacy data with the given key
: (useful to free some data to avoid going over 64k)

; $this->'''bga->'''legacy->setTeam(mixed $value, int $ttl = 365)
: ( deprecated alias: 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

; $this->'''bga->'''legacy->getTeam(mixed $defaultValue = null)
: ( deprecated alias: $this->retrieveLegacyData() ⚠️ this alias was returning a JSON-encoded value, while the getTeam function returns the real value )
: Same as retrieveLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)

; $this->'''bga->'''legacy->deleteTeam()
: ( deprecated alias: $this->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.

== Tournament API (🚧 Beta) ==

The Tournament API is meant only for tournament encounters. It lets you persist per‑player data within a tournament and access deterministic seeds shared by all encounters of a tournament step.

Do not use this for preferences or long‑term progression: if a table is not linked to a tournament, these requests will fail, and all tournament data is wiped when the tournament ends anyway.

You can use it for:
* enforcing tournament‑wide constraints (ex: keep the same deck across all rounds)
* deterministic setup shared across a tournament step (ex: generate the same map layout for all encounters in a step)
; $this->'''bga->'''tournament->isTournament()
: Returns true if this table is a tournament encounter.
: Use this to guard tournament‑only logic.

; $this->'''bga->'''tournament->getSeedInfo()
: Returns an associative array containing deterministic seeds for tournament encounters.
: Keys:
:* <code>tournament_seed</code>: stable across the whole tournament.
:* <code>step_seed</code>: stable across a tournament step (same for all encounters in that step).
:* <code>parent_tournament_seed</code>: stable across the parent tournament (the reference tournament for sub-tournaments of Groups Stage tournament mode).
:
: Note: This call is already guarded internally, no external call is made unless the table is a tournament encounter.

; $this->'''bga->'''tournament->storePlayerGameData(int $playerId, string $key, mixed $data)
: Store per‑player game data for the current tournament.
: Data is JSON‑encoded automatically.
: The cumulative size of all data stored for a player in a tournament (even over multiple keys) is limited to 64 KiB.
: Keys must be 1–16 characters and letters/numbers only.

; $this->'''bga->'''tournament->retrievePlayerGameData(int $playerId, string $key)
: Retrieve per‑player game data for the current tournament.
: If `$key` contains '%', returns an array of key => value pairs (or [] if no match).
: Otherwise, returns a single value (or null if no match).
: Returned values are JSON‑decoded automatically.

; $this->'''bga->'''tournament->removePlayerGameData(int $playerId, string $key)
: Remove per‑player game data for the current tournament.
: You can use '%' in `$key` to remove multiple entries at once.
: All tournament data is removed automatically when the tournament is finished.

== 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.jsonc 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": { "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.jsonc.

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.

'''getBgaEnvironment(): string'''
:Returns "studio" for studio and "prod" for production environment (i.e. where games current runs). Only useful for debbugging hooks.
Note: alpha server is also "prod"

== Creating other classes ==

You can create other classes in the <code>modules/php</code> dir, next to your <code>Game.php</code> file.

If they are names following the PSR-4, they will be autoloaded by BGA (no require_once needed). This doesn't work for the "legacy way" (=<code>YourGameName.game.php</code> at the game root dir).

For example, writing <code>new ScoreManager()</code> in your Game file will try to load the class <code>ScoreManager</code> of namespace <code>Bga\Games\YourGameName</code> in <code>modules/php/ScoreManager.php</code>

Don't forget to add namespace <code>Bga\Games\YourGameName;</code> at the beginning of your module.

You can even put these classes in sublevels : the class <code>Bga\Games\YourGameName\Cards\StandardCard</code> will be automatically loaded if it is stored in <code>modules/php/Cards/StandardCard.php</code>

[[Category:Studio]]

Main game logic: Game.php

2026-05-08T11:12:20Z

BaronFraser: /* Sending private data to some players */

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

'''Note:''' this file is now named Game.php, located in the modules/php directory. If you see it named yourgamename.game.php in the root dir, it's the legacy usage. In the legacy usage, the namepaces don't exists.

== 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.
getAllDatas accepts a magic parameter <code>int $currentPlayerId</code> (or <code>int $currentPlayerNo</code>) to fetch the information from the point of view of the current player id (or no). It should not have any other parameter.
* '''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!

; getPlayerCount() (or getPlayersNumber() that is an alias )
: 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.

; <nowiki>getActivePlayerId(): string</nowiki>
: 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.
: In general, you shouldn't use this method. It is available as a magic param in getArgs / onEnteringState / act functions, and shouldn't be needed anywhere else.

; 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

; getPlayerNameByNo($playerNo)
: Get the name by no

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

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

; getPlayerIdByNo(int $playerNo) int
: Get the player id by player no.

; 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) string
: 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. It is available as a magic param in act functions, and also in getAllDatas, and shouldn't be needed anywhere.
: '''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). Can be easily replaced by $this->getPlayerNameById($currentPlayerId);

; 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). Can be easily replaced by $this->getPlayerColorById($currentPlayerId);

; 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
: Be careful using this method (see above). Should never be needed, zombie players should behave like real players, and everything specific to zombie should be set in the zombie method only.

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

For player score and tiebreaker, see [[Main game logic: Game.php#Manage player scores and Tie breaker]]

== 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, '''as long as the SQL statement uses single quotes around the string. This is important!'''
''Note: if you using standard types in ajax actions, like AT_alphanum it is sanitized before arrival. This function is only needed if you manage to get an unchecked string, like in the games where user has to enter text as a response.''
''Note: This function does not escape % and _ by default, which are wildcards if used in an SQL "LIKE" statement. The developer must determine if this is desirable behavior.''

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

== Use bga 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.''

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

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

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

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

You can specify the expected class type, if you save a class and don't want it returned as a stdClass.
<pre>
$undo = new Undo($playerId, $moves);
$this->bga->globals->set(UNDO, $undo);

$undo = $this->bga->globals->get(UNDO); // will return an stdClass
$undo = $this->bga->globals->get(UNDO, class: Undo::class); // will return an Undo class
</pre>
Note: your class should be a plain object with no mandatory constructor params. Example:
<pre>
class Undo {
public function __construct(
public ?int $playerId = null,
public ?array $moves = null,
) {}
}
</pre>

'''bga->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->bga->globals->getAll();
...
$diceVariables = $this->bga->globals->getAll(DIE1, DIE2);
</pre>

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

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

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

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

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

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

'''bga->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->bga->globals->inc(PLAYED_ACTIONS_IN_CURRENT_TURN, 1);
...
$totalSpent = $this->bga->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>

'''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 must transition to a state in the action triggering this call, so the change of active player is notified to the front.

; $this->activePrevPlayer()
: Make the previous player active (in the natural player order).
: Note: you must transition to a state in the action triggering this call, so the change of active player is notified to the front.

; $this->gamestate->changeActivePlayer( $player_id )
: You can call this method to make any player active.
: Note: you must transition to a state in the action triggering this call, so the change of active player is notified to the front.

; $this->getActivePlayerId() string
: Return the "active_player" id
: Note: it does NOT mean that this player is active right now, because state type could be GAME or MULTIPLE_ACTIVE_PLAYER
: Note: avoid using this method in a MULTIPLE_ACTIVE_PLAYER state because it does not mean anything.
: In general, you shouldn't use this method. It is available as a magic param in getArgs / onEnteringState / act functions, and shouldn't be needed anywhere else.

=== 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 MULTIPLE_ACTIVE_PLAYER 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 MULTIPLE_ACTIVE_PLAYER 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" => MULTIPLE_ACTIVE_PLAYER,
'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, by transition name or State class name.

; $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, by transition name or State class name, 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, by transition name or State class name, 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 ACTIVE_PLAYER type gamestate, it will return an array with one value (the active player id).
: During a MULTIPLE_ACTIVE_PLAYER 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. Next state param is a transition name or State class name.
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 (or the state class name), and NOT the name of the target game state, see [[Your game state machine: states.inc.php]] for more information about states.
:''with State classes, you should not need it and you can just return the class name of the next state.''

'''$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
:''with State classes, you should not need it and you can just return the class name of the next state.''

; $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.
:''With auto-wired actions, you should not need it.''

; $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 actUnpass(int $currentPlayerId) {
$this->gamestate->checkPossibleAction('actUnpass'); // player changed mind about passing while others were thinking
$this->gamestate->setPlayersMultiactive([$currentPlayerId], 'error', false);
}

; $this->gamestate->getCurrentMainState()
: Returns the current main state, ignoring private parallel states.
: To get the state as an array, use <code>$this->gamestate->getCurrentMainState()->toArray()</code> and it will get a result similar to $this->gamestate->state()
: To get the state name, use <code>$this->gamestate->getCurrentMainState()->name</code>

; $this->gamestate->getCurrentMainStateId()
: Returns the current main state id, ignoring private parallel states. (previously, it was the state_id() function, that returned the state numer as a string).

; $this->gamestate->getCurrentState(int $playerId)
: Returns the current state for a player. If the player is in private parallel state, it means the current private state for this player.
: To get the state as an array, use <code>$this->gamestate->getCurrentState($playerId)->toArray()</code>
: To get the state name, use <code>$this->gamestate->getCurrentState($playerId)->name</code>

; $this->gamestate->getCurrentStateId(int $playerId)
: Returns the current state id for a player. If the player is in private parallel state, it means the current private state for this player.

; $this->gamestate->isMultiactiveState()
: Return true if we are in MULTIPLE_ACTIVE_PLAYER 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, or be a state class name.
: 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, by transition name or State class name.
: 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, by transition name or State class name.
: 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.) NewStateId can also be a state class name.
: 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 MULTIPLE_ACTIVE_PLAYER 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 ensure 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
});
</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>

On client side:

const lala ={a: 2, b: "string", c: [1,2,4]};
this.bgaPerformAction("actPlanComplexStuff", {
answer: JSON.stringify(lala)
});

It's also possible to decode the Json to a PHP class, similar to what is done with $this->globals->get with class parameter.

<pre>
use \Bga\GameFramework\Actions\Types\JsonParam;

...
class Answer {
public function __construct(
public int $a,
public string $b,
public array $c,
) {}
}
public function actPlanComplexStuff(#[JsonParam(class: Answer::class)] $answer) {} // specifying the class to map the json to
public function actPlanComplexStuff(#[JsonParam] Answer $answer) {} // same result, but the class is detected automatically by the framework thanks to the typed param.

public function actPlanMultipleComplexStuff(#[JsonParam(class: Answer::class)] array $answers) {} // can decode an array of Answer::class
</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) { ... }

#[CheckAction(false)]
public function actCancelChooseAction() {
$this->gamestate->checkPossibleAction('actCancelChooseAction');
...
}

</pre>

If you disable <code>checkAction</code>, you probably need to call <code>$this->gamestate->checkPossibleAction</code> instead at the beginning of your function. You likely also want to disable client checkAction calls implied by bgaPerformAction.

=== 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 (act* in State classes or Game.php). It is a MUST actually. At least one notification must be sent (but it includes state transition which sends it)
* game state transition (onEnteringState in State classes)
* 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]

Do not put HTML in the notifications. If you want to have pretty pictures in the log check this [[BGA_Studio_Cookbook#Inject_images_and_styled_html_in_the_log]].

=== Notify ===

'''bga->notify->all(string $notification_type,string | NotificationMessage $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 notify all example (from "Reversi"):

<pre>
$this->bga->notify->all( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),
array(
'player_id' => $player_id,
'player_name' => $this->getPlayerNameById($player_id),
'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 notify->player 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->bga->notify->all( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),
array(
'player_id' => $player_id,
'player_name' => $this->getPlayerNameById($player_id),
'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.

==== 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->bga->notify->all('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'] ]
]
]);

==== Sending private data to 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 to see a different message and get some private data.

You can use the <code>_private</code> arg to send private data to designated players, in a similar fashion of the onEnteringState <code>_private</code> flag. <code>_private</code> is an array that have the player id to send private information to, and the value if the different notification using NotificationMessage to send both the replacing log and the args that will be accessible on front side in args._private.

Example:
<pre>
use Bga\GameFramework\NotificationMessage;

(...)

$this->bga->notify->all('cardPicked', clienttranslate('${player_name} takes a secret card from the deck'), [
'playerId' => $playerId,
'player_name' => $this->getPlayerNameById($playerId),
'_private' => [
$playerId => new NotificationMessage(clienttranslate('You take ${_private.card_name} from the deck'), [
'card' => $card,
'card_name' => $this->getCardName($card),
'i18n' => ['card_name']
]),
],
]);
</pre>
Note that the message uses <code>${_private.card_name}</code> to access the data in the private args.

If you don't need to change the log, but only send private args, you can send an array of args instead of the NotificationMessage object.

If you add <code>_merge_private => true</code> next to <code>_private</code>, the private informations will be accessible in `args` instead of `args._private`. This seems to be required for your interceptFormatStringToken to intercept and alter private args.

If you want all your <code>_private</code> objects to be merged (state args and notif args), call <code>$this->bga->notify->alwaysMergePrivate();</code> in your Game constructor instead of adding the <code>_merge_private</code> flag on each arg.

==== 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->bga->notify->all(
'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 ===

'''bga->notify->player(int $player_id, string $notification_type, string | NotificationMessage $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 should be used only if you send some private information to a player, NOT wanting to send a public notification at the same time for the same reason. See paragraph '''Sending private data to some players''' that should cover most of your need to send a private notif.

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->bga->notify->player($player_id,'message', clienttranslate('You draw ${card_name}'), [ ... ]);
or
$this->bga->notify->player($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 notify->all() for any notification that spectators should get.

=== Notification decorators ===

'''bga->notify->addDecorator(callable $fn)'''

Add a decorator function that will be called on notification args before each call of notify->all and notify->player. ''Note: it won't work with deprecated functions notifyAllPlayers and notifyPlayer.''

To avoid duplicating the code in your notification args, you can register decorators in your Game __construct function.
// in construct :
$this->bga->notify->addDecorator(fn(string $message, array $args) => $this->decoratePlayerNameNotifArg($message, $args));
// could also be written this (ugly) way : $this->bga->notify->addDecorator([$this, 'decoratePlayerNameNotifArg']);

// with the Utils functions
public function decoratePlayerNameNotifArg(string $message, array $args): array {
// if the notif message contains ${player_name} but it isn't set in the args, add it on args from $args['player_id']
if (isset($args['player_id']) && !isset($args['player_name']) && str_contains($message, '${player_name}')) {
$args['player_name'] = $this->getPlayerNameById($args['player_id']);
}
return $args;
}
With this example, you can call <code>$this->bga->notify->all("pass", clienttranslate('${player_name} passes'), [ "player_id" => $player_id ]);</code> and the front will receive the player_name arg along the player_id one.

You can also declare it as an inline function :
// in construct :
this->bga->notify->addDecorator(function(string $message, array $args) {
// if the notif message contains ${card_name} but it isn't set in the args, add it on args from $args['card']
// also set it up for translations by adding it to the i18n array
if (isset($args['card']) && !isset($args['card_name']) && str_contains($message, '${card_name}')) {
$args['card_name'] = $args['card']->name;
$args['i18n'][] = ['card_name'];
}
return $args;
});
With this example, you can call <code>$this->bga->notify->all("playCard", clienttranslate('${player_name} plays ${card_name}'), [ "player_id" => $player_id, card => $card ]);</code> and the front will receive the card_name arg with the flag to translate it.

== 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.json]] to see how you define statistics for your game.

'''bga->tableStats->init(string|array $nameOrNames, int|float|bool $value)'''

'''bga->playerStats->init(string|array $nameOrNames, int|float|bool $value, bool $updateTableStat = false)'''

previously : initStat( $table_or_player, $name, $value)

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 xxxStats->set or xxxStats->inc, 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.

'$nameOrNames' is the name of your statistic, as it has been defined in your stats.inc.php file, or an array of those names.

'$value' is the initial value of the statistic.

'updateTableStat' for playerStats initiates the tableStats of the same name, so if you store for example 'playedTurns' in both 'table' and 'player' call only <code>bga->playerStats->init('playedTurns', 0, true)</code> and it will init for both 'table' and 'player'.

'''bga->tableStats->set(string $name, int|float|bool $value)'''

'''bga->playerStats->set(string $name, int|float|bool $value, int $player_id)'''

'''bga->playerStats->setAll(string $name, int|float|bool $value)''' (same as set, but for all players at once)

previously : setStat( $value, $name, $player_id = null )

Set a statistic $name to $value.

'''bga->tableStats->inc(string $name, int|float $delta)'''

'''bga->playerStats->inc(string $name, int|float $delta, int $player_id, bool $updateTableStat = false)'''

'''bga->playerStats->incAll(string $name, int|float $delta)''' (same as inc, but for all players at once)

previously : incStat( $delta, $name, $player_id = null )

Increment (or decrement) specified statistic value by $delta value. Same behavior as setStat function, except you cannot increment boolean values. 'updateTableStat' will also inc the tableStats of the same name.

'''bga->tableStats->get(string $name): int|float|bool'''

'''bga->playerStats->get(string $name, int $player_id): int|float|bool'''

previously : getStat( $name, $player_id = null )

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

'''bga->playerStats->getAll(string $name): array'''

Returns the values for all players, as an associative array $player_id => $value

== 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 using $this->bga->playerScore. bga->playerScore is a [[PlayerCounter and TableCounter|PlayerCounter]], so it has the same methods.

Examples:
<pre>

// +2 points to active player
$this->bga->playerScore->inc($activePlayerId, 2);

// Set score of active player to 5
$this->bga->playerScore->set($activePlayerId, 5);

</pre>

=== Tie breaker ===

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

Tie breaker is using $this->bga->playerScoreAux. It is updated exactly like $this->bga->playerScore. bga->playerScoreAux is a [[PlayerCounter and TableCounter|PlayerCounter]], so it has the same methods.

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 "playerScoreAux" functionality, you must describe the formula to use in your gameinfos.jsonc file like this:

<pre>
"tie_breaker_description": "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.

Note: if you need to need you score_aux to be reverse (lowest value wins), please contact Studio support to get a solution.

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

=== Reverse scoring and reverse tie-breaker ===

If your game has a reverse scoring (lowest value wins) or reverse tie-breaker (lowest tie-breaker wins), you need to set-up a GameResult object to tell BGA this specificity.

On your last state (usually EndScore.php), instead of returning 99 to go the end game, return a GameResult. returning a GameResult object in a State class will then go the end game.
<pre>
use Bga\GameFramework\GameResult\GameResult;
use Bga\GameFramework\GameResult\Player;

...

public function onEnteringState() {
...

$playersDb = $this->game->getCollectionFromDb("SELECT * FROM `player`");
$players = Player::fromPlayersDb($playersDb);
return GameResult::individualRanking($players, reverseScore: true);
}
</pre>
For reverse tie-breaker, it will be `reverseScoreAux: true`.

If your game has running tables with negative scores to handle reverse scoring and you want to use the reverse scoring, add this just before the return line:
<pre>
if ($this->bga->playerScore->getMin() < 0) {
foreach ($players as &$player) {
$player->score = -$player->score;
}
}
</pre>
So game started before the change will reverse the score (negative to positive) before creating the GameResult object.
And anywhere you change the score, you must continue the way it was started :
<pre>
$addedPoints = 3;
if ($this->bga->playerScore->getMin() < 0) {
$addedPoints = -$addedPoints;
}
$this->bga->playerScore->inc($playerId, $addedPoints);
</pre>
If there are negative score, the game will continue with negative scores, else it will continue with positive scores.

=== Result neutralization ===

when a player quits a running table, the results of the game will be neutralized (everyone has score set to 1, except the first quitter that will be at 0 and will be ranked last in addition to reputation drop). We cannot keep the ranking among the remaining players, as the quitter being replaced by a zombie might unbalance the rest of the game interaction, for example the player playing just after can get advantages with the situation.

For some games where there is almost no interaction between player, like some roll & write games, there is no real reason to neutralize the game results when a player quits. In that case, you can ask the Studio Support to activate the "Keep ranking on player quit" flag for your game. The zombie mode must be fully functional to allow the game to continue with leavers. Note that the BGA team might refuse to activate it, if it is considered the zombie player will unbalance the results of the remaining players.

When this flag is activated, a player quitting a game will still be penalized, but the ranking you set at the end of the game will stay, and the eliminated player(s) will have their score set to -1. It also means if a second player quits the game, he will also be penalized, because he has no reason to quit and can continue the game. If the game ends with 2 remaining players, it's now possible for one of them to concede.

To request this mode, click on "Contact us / Support" at the bottom of the page in Studio and then work through to a "My problem has not been solved" and then enter your request. The flag can be set independently in Studio and Production, so make sure to request it for both (unless you just want to experiment in Studio).

Note: the flag will fully work for games started AFTER activation. It may display incorrect messages for games started before the activation but players left after. For this reason, it's best to request it when going to alpha, else accept some strange bug reports about this situation, that will solve itself when all existing tables are started after the activation.

=== Co-operative game ===

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

Add the following in gameinfos.jsonc :
"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.jsonc:

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

* In your PHP code:
$this->eliminatePlayer( <player_to_eliminate_id> );
* Player to eliminate should NOT be active anymore at the end of the action that triggers the eliminatePlayer function.
* 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:''' If you eliminate the last player, make sure the action will end by going to the end game state. If it doesn't, BGA will jump straight to it, without calling your end score state or anything similar.

=== Player concede ===

It should be rarely needed, but if you absolutely need to run some code when a player concedes, you can create a function called onConcede in the Game class like this :
<pre>
function onConcede() {
$this->bga->notify->all('test', 'Something to do when the player concedes');
}
</pre>
If you want to get the conceder id:
<pre>
function onConcede($concederTeam) {
$this->bga->notify->all('test', 'Something to do when the player concedes '.$concederTeam->players[0]->id);
}
</pre>

Never change state on this function. It should be limited to computing stats or similar small stuff.

To not break the game end, any exception triggered by this function will be catched and simply logged, so make sure your code stay simple and never trigger an exception and it will be hard to detect!

== Reflexion time ==

; function giveExtraTime( $player_id, $specific_time=null )
: Give standard extra time to this player in real time game. It does not affect turn based games.
: Standard extra time (when you don't pass $specific_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 "specific_time" argument (rarely used). Using $specific_time is not recommended as this does not adjust for the game speed.
: Important Note: the total reflection time cannot be more than time allowed for the turn. So you can never make it 10 minutes if turn max is 3 min (the max is determined by game speed). As a consequence there is no point adding this at the begging of the turn of in game setup, it only matters after the action which does not lead to turn end (which is when this player becomes inactive).
: Note: standard extra time is automatically doubled for begginer

function actionBla($args) {
$this->checkAction('actionBla');
$playerId = (int)$this->getActivePlayerId();
$this->giveExtraTime($player_id);
// do some inter-turn action
$this->notifyAll(...);
// no state transition as this player did an action but stayed active
}

; '''$this->bga->tableOptions->isTurnBased(): bool'''
: Returns true if game is turn based
:
; '''$this->bga->tableOptions->isRealTime(): bool'''
: Returns true if game is in real time

== 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 actUndo() {
$this->undoRestorePoint();
return PlayTurn::class; // 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().

=== Manually remove game logs ===
Only use it if you have custom undo and you fully understand how logs and replay works!

; $this->bga->logs->getCurrentMoveId()
: Returns the current move id, when doing an action, that should be stored along informations to undo.

; $this->bga->logs->remove(int $startMoveId)
: Remove all logs from a move id that was stored during an action using `getCurrentMoveId()`. The game should be in the exact same point as it was before the stored action!

Example:
<pre>
// in the action code, do all the action code, notify it, and store the custom undo
$this->bga->globals->set(UNDO_ACTION, new Undo(
movedTiles: $tiles,
moveId: $this->bga->logs->getCurrentMoveId(),
));

return ConfirmAction::class;
</pre>
<pre>
$undo = $this->bga->globals->get(UNDO_ACTION);
// in the undo action code, do all the revert action code, notify it, then remove the logs
$this->bga->logs->remove($undo->moveId);
// don't do any action/notif after removing the logs
return PlayAction::class;
</pre>

== 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 UserException(string|NotificationMessage $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 will be displayed to the player, as it's a UserException, the error message should be translated (with clientranslate(), and if there are args wrap them into a NotificationMessage)
: Throwing such an exception is NOT considered a bug, so it is not traced in BGA error logs.

Note: if your IDE doesn't do it for you, you'll need to add <code>use Bga\GameFramework\UserException;</code> at the top of your file.

Example from Gomoku:
<pre>
throw new UserException(clienttranslate("There is already a stone on this intersection, you can't play there"));
</pre>
Example with translated UserException using args :
<pre>
throw new UserException(new NotificationMessage(clienttranslate('You must play a card bigger than ${min}', [min => $minCardValue])));
</pre>

; throw new SystemException (string|NotificationMessage $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.

; throw new VisibleSystemException (string|NotificationMessage $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.
: it should not be translated, as it's just to bring debug details to you when the player reports the issue.

== Zombie mode ==

When a player leaves a game for any reason (expelled, quit), he becomes a "zombie player". You must implement a Zombie that will handle the role of the leaver player

Read [[Zombie Mode|Zombie mode]] to get all details of the expected code.

== User preferences ==
'''$this->bga->userPreferences->get(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.

''To test it, you can set your preferred color on your BGA Studio account.''

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

On your gameinfos.jsonc 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->bga->legacy->setTeam( $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.

; $this->'''bga->'''legacy->set(string $key, int $playerId, mixed $value, int $ttl = 365)
: ( deprecated alias: $this->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).

; $this->'''bga->'''legacy->get(string $key, int $playerId, mixed $defaultValue = null)
: ( deprecated alias: $this->retrieveLegacyData($player_id, $key) ⚠️ this alias was returning a JSON-encoded value, while the get function returns the real value )
: 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

; $this->'''bga->'''legacy->delete(string $key, int $playerId)
: ( deprecated alias: $this->removeLegacyData($player_id, $key) )
: Remove some legacy data with the given key
: (useful to free some data to avoid going over 64k)

; $this->'''bga->'''legacy->setTeam(mixed $value, int $ttl = 365)
: ( deprecated alias: 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

; $this->'''bga->'''legacy->getTeam(mixed $defaultValue = null)
: ( deprecated alias: $this->retrieveLegacyData() ⚠️ this alias was returning a JSON-encoded value, while the getTeam function returns the real value )
: Same as retrieveLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)

; $this->'''bga->'''legacy->deleteTeam()
: ( deprecated alias: $this->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.

== Tournament API (🚧 Beta) ==

The Tournament API is meant only for tournament encounters. It lets you persist per‑player data within a tournament and access deterministic seeds shared by all encounters of a tournament step.

Do not use this for preferences or long‑term progression: if a table is not linked to a tournament, these requests will fail, and all tournament data is wiped when the tournament ends anyway.

You can use it for:
* enforcing tournament‑wide constraints (ex: keep the same deck across all rounds)
* deterministic setup shared across a tournament step (ex: generate the same map layout for all encounters in a step)
; $this->'''bga->'''tournament->isTournament()
: Returns true if this table is a tournament encounter.
: Use this to guard tournament‑only logic.

; $this->'''bga->'''tournament->getSeedInfo()
: Returns an associative array containing deterministic seeds for tournament encounters.
: Keys:
:* <code>tournament_seed</code>: stable across the whole tournament.
:* <code>step_seed</code>: stable across a tournament step (same for all encounters in that step).
:* <code>parent_tournament_seed</code>: stable across the parent tournament (the reference tournament for sub-tournaments of Groups Stage tournament mode).
:
: Note: This call is already guarded internally, no external call is made unless the table is a tournament encounter.

; $this->'''bga->'''tournament->storePlayerGameData(int $playerId, string $key, mixed $data)
: Store per‑player game data for the current tournament.
: Data is JSON‑encoded automatically.
: The cumulative size of all data stored for a player in a tournament (even over multiple keys) is limited to 64 KiB.
: Keys must be 1–16 characters and letters/numbers only.

; $this->'''bga->'''tournament->retrievePlayerGameData(int $playerId, string $key)
: Retrieve per‑player game data for the current tournament.
: If `$key` contains '%', returns an array of key => value pairs (or [] if no match).
: Otherwise, returns a single value (or null if no match).
: Returned values are JSON‑decoded automatically.

; $this->'''bga->'''tournament->removePlayerGameData(int $playerId, string $key)
: Remove per‑player game data for the current tournament.
: You can use '%' in `$key` to remove multiple entries at once.
: All tournament data is removed automatically when the tournament is finished.

== 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.jsonc 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": { "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.jsonc.

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.

'''getBgaEnvironment(): string'''
:Returns "studio" for studio and "prod" for production environment (i.e. where games current runs). Only useful for debbugging hooks.
Note: alpha server is also "prod"

== Creating other classes ==

You can create other classes in the <code>modules/php</code> dir, next to your <code>Game.php</code> file.

If they are names following the PSR-4, they will be autoloaded by BGA (no require_once needed). This doesn't work for the "legacy way" (=<code>YourGameName.game.php</code> at the game root dir).

For example, writing <code>new ScoreManager()</code> in your Game file will try to load the class <code>ScoreManager</code> of namespace <code>Bga\Games\YourGameName</code> in <code>modules/php/ScoreManager.php</code>

Don't forget to add namespace <code>Bga\Games\YourGameName;</code> at the beginning of your module.

You can even put these classes in sublevels : the class <code>Bga\Games\YourGameName\Cards\StandardCard</code> will be automatically loaded if it is stored in <code>modules/php/Cards/StandardCard.php</code>

[[Category:Studio]]

Main game logic: Game.php

2026-03-16T01:17:11Z

BaronFraser: /* Result neutralization */

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

'''Note:''' this file is now named Game.php, located in the modules/php directory. If you see it named yourgamename.game.php in the root dir, it's the legacy usage. In the legacy usage, the namepaces don't exists.

== 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.
getAllDatas accepts a magic parameter <code>int $currentPlayerId</code> to fetch the information from the point of view of the current player id. It should not have any other parameter
* '''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!

; getPlayerCount() (or getPlayersNumber() that is an alias )
: 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.

; <nowiki>getActivePlayerId(): string</nowiki>
: 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.
: In general, you shouldn't use this method. It is available as a magic param in getArgs / onEnteringState / act functions, and shouldn't be needed anywhere else.

; 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) string
: 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. It is available as a magic param in act functions, and also in getAllDatas, and shouldn't be needed anywhere.
: '''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). Can be easily replaced by $this->getPlayerNameById($currentPlayerId);

; 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). Can be easily replaced by $this->getPlayerColorById($currentPlayerId);

; 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
: Be careful using this method (see above). Should never be needed, zombie players should behave like real players, and everything specific to zombie should be set in the zombie method only.

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

For player score and tiebreaker, see [[Main game logic: Game.php#Manage player scores and Tie breaker]]

== 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, '''as long as the SQL statement uses single quotes around the string. This is important!'''
''Note: if you using standard types in ajax actions, like AT_alphanum it is sanitized before arrival. This function is only needed if you manage to get an unchecked string, like in the games where user has to enter text as a response.''
''Note: This function does not escape % and _ by default, which are wildcards if used in an SQL "LIKE" statement. The developer must determine if this is desirable behavior.''

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

== Use bga 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.''

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

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

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

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

You can specify the expected class type, if you save a class and don't want it returned as a stdClass.
<pre>
$undo = new Undo($playerId, $moves);
$this->bga->globals->set(UNDO, $undo);

$undo = $this->bga->globals->get(UNDO); // will return an stdClass
$undo = $this->bga->globals->get(UNDO, class: Undo::class); // will return an Undo class
</pre>
Note: your class should be a plain object with no mandatory constructor params. Example:
<pre>
class Undo {
public function __construct(
public ?int $playerId = null,
public ?array $moves = null,
) {}
}
</pre>

'''bga->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->bga->globals->getAll();
...
$diceVariables = $this->bga->globals->getAll(DIE1, DIE2);
</pre>

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

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

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

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

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

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

'''bga->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->bga->globals->inc(PLAYED_ACTIONS_IN_CURRENT_TURN, 1);
...
$totalSpent = $this->bga->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>

'''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 ACTIVE_PLAYER or MULTIPLE_ACTIVE_PLAYER 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 ACTIVE_PLAYER or MULTIPLE_ACTIVE_PLAYER 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 ACTIVE_PLAYER or MULTIPLE_ACTIVE_PLAYER state. You must use a GAME type game state for this.

; $this->getActivePlayerId() string
: Return the "active_player" id
: Note: it does NOT mean that this player is active right now, because state type could be GAME or MULTIPLE_ACTIVE_PLAYER
: Note: avoid using this method in a MULTIPLE_ACTIVE_PLAYER state because it does not mean anything.
: In general, you shouldn't use this method. It is available as a magic param in getArgs / onEnteringState / act functions, and shouldn't be needed anywhere else.

=== 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 MULTIPLE_ACTIVE_PLAYER 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 MULTIPLE_ACTIVE_PLAYER 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" => MULTIPLE_ACTIVE_PLAYER,
'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, by transition name or State class name.

; $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, by transition name or State class name, 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, by transition name or State class name, 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 ACTIVE_PLAYER type gamestate, it will return an array with one value (the active player id).
: During a MULTIPLE_ACTIVE_PLAYER 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. Next state param is a transition name or State class name.
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 (or the state class name), and NOT the name of the target game state, see [[Your game state machine: states.inc.php]] for more information about states.
:''with State classes, you should not need it and you can just return the class name of the next state.''

'''$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
:''with State classes, you should not need it and you can just return the class name of the next state.''

; $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.
:''With auto-wired actions, you should not need it.''

; $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 actUnpass(int $currentPlayerId) {
$this->gamestate->checkPossibleAction('actUnpass'); // player changed mind about passing while others were thinking
$this->gamestate->setPlayersMultiactive([$currentPlayerId], 'error', false);
}

; $this->gamestate->getCurrentMainState()
: Returns the current main state, ignoring private parallel states.
: To get the state as an array, use <code>$this->gamestate->getCurrentMainState()->toArray()</code> and it will get a result similar to $this->gamestate->state()
: To get the state name, use <code>$this->gamestate->getCurrentMainState()->name</code>

; $this->gamestate->getCurrentMainStateId()
: Returns the current main state id, ignoring private parallel states. (previously, it was the state_id() function, that returned the state numer as a string).

; $this->gamestate->getCurrentState(int $playerId)
: Returns the current state for a player. If the player is in private parallel state, it means the current private state for this player.
: To get the state as an array, use <code>$this->gamestate->getCurrentState($playerId)->toArray()</code>
: To get the state name, use <code>$this->gamestate->getCurrentState($playerId)->name</code>

; $this->gamestate->getCurrentStateId(int $playerId)
: Returns the current state id for a player. If the player is in private parallel state, it means the current private state for this player.

; $this->gamestate->isMultiactiveState()
: Return true if we are in MULTIPLE_ACTIVE_PLAYER 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, or be a state class name.
: 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, by transition name or State class name.
: 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, by transition name or State class name.
: 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.) NewStateId can also be a state class name.
: 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 MULTIPLE_ACTIVE_PLAYER 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 ensure 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
});
</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>

On client side:

const lala ={a: 2, b: "string", c: [1,2,4]};
this.bgaPerformAction("actPlanComplexStuff", {
answer: JSON.stringify(lala)
});

=== 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) { ... }

#[CheckAction(false)]
public function actCancelChooseAction() {
$this->gamestate->checkPossibleAction('actCancelChooseAction');
...
}

</pre>

If you disable <code>checkAction</code>, you probably need to call <code>$this->gamestate->checkPossibleAction</code> instead at the beginning of your function. You likely also want to disable client checkAction calls implied by bgaPerformAction.

=== 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 (act* in State classes or Game.php). It is a MUST actually. At least one notification must be sent (but it includes state transition which sends it)
* game state transition (onEnteringState in State classes)
* 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]

Do not put HTML in the notifications. If you want to have pretty pictures in the log check this [[BGA_Studio_Cookbook#Inject_images_and_styled_html_in_the_log]].

=== Notify ===

'''bga->notify->all(string $notification_type,string | NotificationMessage $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 notify all example (from "Reversi"):

<pre>
$this->bga->notify->all( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),
array(
'player_id' => $player_id,
'player_name' => $this->getPlayerNameById($player_id),
'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 notify->player 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->bga->notify->all( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),
array(
'player_id' => $player_id,
'player_name' => $this->getPlayerNameById($player_id),
'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.

==== 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->bga->notify->all('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'] ]
]
]);

==== Sending private data to 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 to see a different message and get some private data.

You can use the <code>_private</code> arg to send private data to designated players, in a similar fashion of the onEnteringState <code>_private</code> flag. <code>_private</code> is an array that have the player id to send private information to, and the value if the different notification using NotificationMessage to send both the replacing log and the args that will be accessible on front side in args._private.

Example:
<pre>
use Bga\GameFramework\NotificationMessage;

(...)

$this->bga->notify->all('cardPicked', clienttranslate('${player_name} takes a secret card from the deck'), [
'playerId' => $playerId,
'player_name' => $this->getPlayerNameById($playerId),
'_private' => [
$playerId => new NotificationMessage(clienttranslate('You take ${_private.card_name} from the deck'), [
'card' => $card,
'card_name' => $this->getCardName($card),
'i18n' => ['card_name']
]),
],
]);
</pre>
Note that the message uses <code>${_private.card_name}</code> to access the data in the private args.

If you don't need to change the log, but only send private args, you can send an array of args instead of the NotificationMessage object.

==== 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->bga->notify->all(
'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 ===

'''bga->notify->player(int $player_id, string $notification_type, string | NotificationMessage $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 should be used only if you send some private information to a player, NOT wanting to send a public notification at the same time for the same reason. See paragraph '''Sending private data to some players''' that should cover most of your need to send a private notif.

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->bga->notify->player($player_id,'message', clienttranslate('You draw ${card_name}'), [ ... ]);
or
$this->bga->notify->player($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 notify->all() for any notification that spectators should get.

=== Notification decorators ===

'''bga->notify->addDecorator(callable $fn)'''

Add a decorator function that will be called on notification args before each call of notify->all and notify->player. ''Note: it won't work with deprecated functions notifyAllPlayers and notifyPlayer.''

To avoid duplicating the code in your notification args, you can register decorators in your Game __construct function.
// in construct :
$this->bga->notify->addDecorator(fn(string $message, array $args) => $this->decoratePlayerNameNotifArg($message, $args));
// could also be written this (ugly) way : $this->bga->notify->addDecorator([$this, 'decoratePlayerNameNotifArg']);

// with the Utils functions
public function decoratePlayerNameNotifArg(string $message, array $args): array {
// if the notif message contains ${player_name} but it isn't set in the args, add it on args from $args['player_id']
if (isset($args['player_id']) && !isset($args['player_name']) && str_contains($message, '${player_name}')) {
$args['player_name'] = $this->getPlayerNameById($args['player_id']);
}
return $args;
}
With this example, you can call <code>$this->bga->notify->all("pass", clienttranslate('${player_name} passes'), [ "player_id" => $player_id ]);</code> and the front will receive the player_name arg along the player_id one.

You can also declare it as an inline function :
// in construct :
this->bga->notify->addDecorator(function(string $message, array $args) {
// if the notif message contains ${card_name} but it isn't set in the args, add it on args from $args['card']
// also set it up for translations by adding it to the i18n array
if (isset($args['card']) && !isset($args['card_name']) && str_contains($message, '${card_name}')) {
$args['card_name'] = $args['card']->name;
$args['i18n'][] = ['card_name'];
}
return $args;
});
With this example, you can call <code>$this->bga->notify->all("playCard", clienttranslate('${player_name} plays ${card_name}'), [ "player_id" => $player_id, card => $card ]);</code> and the front will receive the card_name arg with the flag to translate it.

== 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.json]] to see how you define statistics for your game.

'''bga->tableStats->init(string|array $nameOrNames, int|float|bool $value)'''

'''bga->playerStats->init(string|array $nameOrNames, int|float|bool $value, bool $updateTableStat = false)'''

previously : initStat( $table_or_player, $name, $value)

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 xxxStats->set or xxxStats->inc, 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.

'$nameOrNames' is the name of your statistic, as it has been defined in your stats.inc.php file, or an array of those names.

'$value' is the initial value of the statistic.

'updateTableStat' for playerStats initiates the tableStats of the same name, so if you store for example 'playedTurns' in both 'table' and 'player' call only <code>bga->playerStats->init('playedTurns', 0, true)</code> and it will init for both 'table' and 'player'.

'''bga->tableStats->set(string $name, int|float|bool $value)'''

'''bga->playerStats->set(string $name, int|float|bool $value, int $player_id)'''

'''bga->playerStats->setAll(string $name, int|float|bool $value)''' (same as set, but for all players at once)

previously : setStat( $value, $name, $player_id = null )

Set a statistic $name to $value.

'''bga->tableStats->inc(string $name, int|float $delta)'''

'''bga->playerStats->inc(string $name, int|float $delta, int $player_id, bool $updateTableStat = false)'''

'''bga->playerStats->incAll(string $name, int|float $delta)''' (same as inc, but for all players at once)

previously : incStat( $delta, $name, $player_id = null )

Increment (or decrement) specified statistic value by $delta value. Same behavior as setStat function, except you cannot increment boolean values. 'updateTableStat' will also inc the tableStats of the same name.

'''bga->tableStats->get(string $name): int|float|bool'''

'''bga->playerStats->get(string $name, int $player_id): int|float|bool'''

previously : getStat( $name, $player_id = null )

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

'''bga->playerStats->getAll(string $name): array'''

Returns the values for all players, as an associative array $player_id => $value

== 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 using $this->bga->playerScore. bga->playerScore is a [[PlayerCounter and TableCounter|PlayerCounter]], so it has the same methods.

Examples:
<pre>

// +2 points to active player
$this->bga->playerScore->inc($activePlayerId, 2);

// Set score of active player to 5
$this->bga->playerScore->set($activePlayerId, 5);

</pre>

=== Tie breaker ===

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

Tie breaker is using $this->bga->playerScoreAux. It is updated exactly like $this->bga->playerScore. bga->playerScoreAux is a [[PlayerCounter and TableCounter|PlayerCounter]], so it has the same methods.

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

Note: if you need to need you score_aux to be reverse (lowest value wins), please contact Studio support to get a solution.

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

=== Reverse scoring and reverse tie-breaker ===

If your game has a reverse scoring (lowest value wins) or reverse tie-breaker (lowest tie-breaker wins), you need to set-up a GameResult object to tell BGA this specificity.

On your last state (usually EndScore.php), instead of returning 99 to go the end game, return a GameResult. returning a GameResult object in a State class will then go the end game.
<pre>
use Bga\GameFramework\GameResult\GameResult;
use Bga\GameFramework\GameResult\Player;

...

public function onEnteringState() {
...

$playersDb = $this->game->getCollectionFromDb("SELECT * FROM `player`");
$players = Player::fromPlayersDb($playersDb);
return GameResult::individualRanking($players, reverseScore: true);
}
</pre>
For reverse tie-breaker, it will be `reverseScoreAux: true`.

If your game has running tables with negative scores to handle reverse scoring and you want to use the reverse scoring, add this just before the return line:
<pre>
if ($this->bga->playerScore->getMin() < 0) {
foreach ($players as &$player) {
$player->score = -$player->score;
}
}
</pre>
So game started before the change will reverse the score (negative to positive) before creating the GameResult object.
And anywhere you change the score, you must continue the way it was started :
<pre>
$addedPoints = 3;
if ($this->bga->playerScore->getMin() < 0) {
$addedPoints = -$addedPoints;
}
$this->bga->playerScore->inc($playerId, $addedPoints);
</pre>
If there are negative score, the game will continue with negative scores, else it will continue with positive scores.

=== Result neutralization ===

when a player quits a running table, the results of the game will be neutralized (everyone has score set to 1, except the first quitter that will be at 0 and will be ranked last in addition to reputation drop). We cannot keep the ranking among the remaining players, as the quitter being replaced by a zombie might unbalance the rest of the game interaction, for example the player playing just after can get advantages with the situation.

For some games where there is almost no interaction between player, like some roll & write games, there is no real reason to neutralize the game results when a player quits. In that case, you can ask the Studio Support to activate the "Keep ranking on player quit" flag for your game. The zombie mode must be fully functional to allow the game to continue with leavers. Note that the BGA team might refuse to activate it, if it is considered the zombie player will unbalance the results of the remaining players.

When this flag is activated, a player quitting a game will still be penalized, but the ranking you set at the end of the game will stay, and the eliminated player(s) will have their score set to -1. It also means if a second player quits the game, he will also be penalized, because he has no reason to quit and can continue the game. If the game ends with 2 remaining players, it's now possible for one of them to concede.

To request this mode, click on "Contact us / Support" at the bottom of the page in Studio and then work through to a "My problem has not been solved" and then enter your request. The flag can be set independently in Studio and Production, so make sure to request it for both (unless you just want to experiment in Studio).

Note: the flag will fully work for games started AFTER activation. It may display incorrect messages for games started before the activation but players left after. For this reason, it's best to request it when going to alpha, else accept some strange bug reports about this situation, that will solve itself when all existing tables are started after the activation.

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

* In your PHP code:
$this->eliminatePlayer( <player_to_eliminate_id> );
* Player to eliminate should NOT be active anymore at the end of the action that triggers the eliminatePlayer function.
* 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:''' If you eliminate the last player, make sure the action will end by going to the end game state. If it doesn't, BGA will jump straight to it, without calling your end score state or anything similar.

=== Player concede ===

It should be rarely needed, but if you absolutely need to run some code when a player concedes, you can create a function called onConcede in the Game class like this :
<pre>
function onConcede() {
$this->bga->notify->all('test', 'Something to do when the player concedes');
}
</pre>
If you want to get the conceder id:
<pre>
function onConcede($concederTeam) {
$this->bga->notify->all('test', 'Something to do when the player concedes '.$concederTeam->players[0]->id);
}
</pre>

Never change state on this function. It should be limited to computing stats or similar small stuff.

To not break the game end, any exception triggered by this function will be catched and simply logged, so make sure your code stay simple and never trigger an exception and it will be hard to detect!

== Reflexion time ==

; function giveExtraTime( $player_id, $specific_time=null )
: Give standard extra time to this player in real time game. It does not affect turn based games.
: Standard extra time (when you don't pass $specific_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 "specific_time" argument (rarely used). Using $specific_time is not recommended as this does not adjust for the game speed.
: Important Note: the total reflection time cannot be more than time allowed for the turn. So you can never make it 10 minutes if turn max is 3 min (the max is determined by game speed). As a consequence there is no point adding this at the begging of the turn of in game setup, it only matters after the action which does not lead to turn end (which is when this player becomes inactive).
: Note: standard extra time is automatically doubled for begginer

function actionBla($args) {
$this->checkAction('actionBla');
$playerId = (int)$this->getActivePlayerId();
$this->giveExtraTime($player_id);
// do some inter-turn action
$this->notifyAll(...);
// no state transition as this player did an action but stayed active
}

; '''$this->bga->tableOptions->isTurnBased(): bool'''
: Returns true if game is turn based
:
; '''$this->bga->tableOptions->isRealTime(): bool'''
: Returns true if game is in real time

== 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 actUndo() {
$this->undoRestorePoint();
return PlayTurn::class; // 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().

=== Manually remove game logs ===
Only use it if you have custom undo and you fully understand how logs and replay works!

; $this->bga->logs->getCurrentMoveId()
: Returns the current move id, when doing an action, that should be stored along informations to undo.

; $this->bga->logs->remove(int $startMoveId)
: Remove all logs from a move id that was stored during an action using `getCurrentMoveId()`. The game should be in the exact same point as it was before the stored action!

Example:
<pre>
// in the action code, do all the action code, notify it, and store the custom undo
$this->bga->globals->set(UNDO_ACTION, new Undo(
movedTiles: $tiles,
moveId: $this->bga->logs->getCurrentMoveId(),
));

return ConfirmAction::class;
</pre>
<pre>
$undo = $this->bga->globals->get(UNDO_ACTION);
// in the undo action code, do all the revert action code, notify it, then remove the logs
$this->bga->logs->remove($undo->moveId);
// don't do any action/notif after removing the logs
return PlayAction::class;
</pre>

== 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 UserException(string|NotificationMessage $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 will be displayed to the player, as it's a UserException, the error message should be translated (with clientranslate(), and if there are args wrap them into a NotificationMessage)
: Throwing such an exception is NOT considered a bug, so it is not traced in BGA error logs.

Note: if your IDE doesn't do it for you, you'll need to add <code>use Bga\GameFramework\UserException;</code> at the top of your file.

Example from Gomoku:
<pre>
throw new UserException(clienttranslate("There is already a stone on this intersection, you can't play there"));
</pre>
Example with translated UserException using args :
<pre>
throw new UserException(new NotificationMessage(clienttranslate('You must play a card bigger than ${min}', [min => $minCardValue])));
</pre>

; throw new SystemException (string|NotificationMessage $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.

; throw new VisibleSystemException (string|NotificationMessage $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.
: it should not be translated, as it's just to bring debug details to you when the player reports the issue.

== Zombie mode ==

When a player leaves a game for any reason (expelled, quit), he becomes a "zombie player". You must implement a Zombie that will handle the role of the leaver player

Read [[Zombie Mode|Zombie mode]] to get all details of the expected code.

== User preferences ==
'''$this->bga->userPreferences->get(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.

''To test it, you can set your preferred color on your BGA Studio account.''

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->bga->legacy->setTeam( $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.

; $this->'''bga->'''legacy->set(string $key, int $playerId, mixed $value, int $ttl = 365)
: ( deprecated alias: $this->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).

; $this->'''bga->'''legacy->get(string $key, int $playerId, mixed $defaultValue = null)
: ( deprecated alias: $this->retrieveLegacyData($player_id, $key) ⚠️ this alias was returning a JSON-encoded value, while the get function returns the real value )
: 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

; $this->'''bga->'''legacy->delete(string $key, int $playerId)
: ( deprecated alias: $this->removeLegacyData($player_id, $key) )
: Remove some legacy data with the given key
: (useful to free some data to avoid going over 64k)

; $this->'''bga->'''legacy->setTeam(mixed $value, int $ttl = 365)
: ( deprecated alias: 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

; $this->'''bga->'''legacy->getTeam(mixed $defaultValue = null)
: ( deprecated alias: $this->retrieveLegacyData() ⚠️ this alias was returning a JSON-encoded value, while the getTeam function returns the real value )
: Same as retrieveLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)

; $this->'''bga->'''legacy->deleteTeam()
: ( deprecated alias: $this->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.

== Tournament API (🚧 Beta) ==

The Tournament API is meant only for tournament encounters. It lets you persist per‑player data within a tournament and access deterministic seeds shared by all encounters of a tournament step.

Do not use this for preferences or long‑term progression: if a table is not linked to a tournament, these requests will fail, and all tournament data is wiped when the tournament ends anyway.

You can use it for:
* enforcing tournament‑wide constraints (ex: keep the same deck across all rounds)
* deterministic setup shared across a tournament step (ex: generate the same map layout for all encounters in a step)
; $this->'''bga->'''tournament->isTournament()
: Returns true if this table is a tournament encounter.
: Use this to guard tournament‑only logic.

; $this->'''bga->'''tournament->getSeedInfo()
: Returns an associative array containing deterministic seeds for tournament encounters.
: Keys:
:* <code>tournament_seed</code>: stable across the whole tournament.
:* <code>step_seed</code>: stable across a tournament step (same for all encounters in that step).
:* <code>parent_tournament_seed</code>: stable across the parent tournament (the reference tournament for sub-tournaments of Groups Stage tournament mode).
:
: Note: This call is already guarded internally, no external call is made unless the table is a tournament encounter.

; $this->'''bga->'''tournament->storePlayerGameData(int $playerId, string $key, mixed $data)
: Store per‑player game data for the current tournament.
: Data is JSON‑encoded automatically.
: The cumulative size of all data stored for a player in a tournament (even over multiple keys) is limited to 64 KiB.
: Keys must be 1–16 characters and letters/numbers only.

; $this->'''bga->'''tournament->retrievePlayerGameData(int $playerId, string $key)
: Retrieve per‑player game data for the current tournament.
: If `$key` contains '%', returns an array of key => value pairs (or [] if no match).
: Otherwise, returns a single value (or null if no match).
: Returned values are JSON‑decoded automatically.

; $this->'''bga->'''tournament->removePlayerGameData(int $playerId, string $key)
: Remove per‑player game data for the current tournament.
: You can use '%' in `$key` to remove multiple entries at once.
: All tournament data is removed automatically when the tournament is finished.

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

'''getBgaEnvironment(): string'''
:Returns "studio" for studio and "prod" for production environment (i.e. where games current runs). Only useful for debbugging hooks.
Note: alpha server is also "prod"

== Creating other classes ==

You can create other classes in the <code>modules/php</code> dir, next to your <code>Game.php</code> file.

If they are names following the PSR-4, they will be autoloaded by BGA (no require_once needed). This doesn't work for the "legacy way" (=<code>YourGameName.game.php</code> at the game root dir).

For example, writing <code>new ScoreManager()</code> in your Game file will try to load the class <code>ScoreManager</code> of namespace <code>Bga\Games\YourGameName</code> in <code>modules/php/ScoreManager.php</code>

Don't forget to add namespace <code>Bga\Games\YourGameName;</code> at the beginning of your module.

You can even put these classes in sublevels : the class <code>Bga\Games\YourGameName\Cards\StandardCard</code> will be automatically loaded if it is stored in <code>modules/php/Cards/StandardCard.php</code>

[[Category:Studio]]

Gamehelpnuclearwar

2026-03-16T01:08:53Z

BaronFraser: /* Nuclear Destruction */

== Introduction ==

The atomic bomb has been invented. Nations are building up their stockpiles of atomic bombs while vying for the hearts and minds of their rivals’ populace. Welcome to the world of Nuclear War!

The game begins with an uneasy cold war between all the players, each representing a nuclear power. Once the first player launches a nuclear warhead, the war turns hot as populations decrease in huge balls of nuclear fire. Will there be any nation left when the last bomb has fallen?

== Object ==

In Nuclear War players seek world domination by eliminating the other major powers. This can be accomplished in two ways:

* The peaceful way is to persuade the populations of opposing countries to join your superior form of government through the use of propaganda cards.
* The warlike way is to destroy the enemy’s population by using nuclear weapons.

Population is the measure of success or failure in the game. A player who loses their entire population is eliminated. The last player with population wins the game, but sometimes everyone is engulfed in flames and there are only losers.

== Set Up ==

# Shuffle the population cards. Based on the player count, deal each player the following number of cards: 2 players: 15 cards; 3 players: 10 cards; 4 players: 8 cards; 5 players: 7 cards; 6+ players: 6 cards. Deal these cards face down. Only you may look at your population cards.
# Place the remaining population cards in a face up stack in the middle of the table forming a bank. Players may use the bank to make ‘change’ only when they are forced to lose population.
# Shuffle the Nuclear War cards and deal 9 face-down to each player. You may examine your cards but not other player’s.
# Place the remaining Nuclear War cards in a face-down stack in the middle of the table. This is a draw deck.
# The first player is randomly chosen. Play will proceed clockwise around the table from the first player.
# The first player examines their cards for any secrets and top secrets. If they have any, they play them. Once the first player has a hand with no secrets, the next player in turn declares and plays secrets. Continue this around the table until no one has any secrets left!

'''NOTE''': '''Spies!''' To play a '''secret''' you announce that you have a secret, then give each other player a moment to decide if they want to play a spy. If no one plays a '''spy''', reveal and resolve the secret. Repeat this process every time you play a secret.

7: All players, at the same time, choose and place 1 card facedown in each of the two face-down slots on their playmat. These are the cards that will be played on your first and second turn respectively!
8: Now you are ready to play! The first player takes the first turn.

== Overview of Gameplay ==

On your turn you will:

* Draw cards until you have 8 in your hand.
* Play secrets and draw replacement cards until no secrets are in hand.
* Move the cards on your launch track forward to the next box
* Place a card into the 2nd face-down slot
* Reveal the card in the face-up slot and play it.

== War and Peace ==

Nuclear War has two game states - '''Peacetime''' and '''War'''. The game state affects how some cards work.

The game starts in Peacetime. Once there is a successful launch of a delivery system with a warhead, whether or not the launch results in population loss, the game state changes to War.

The game state remains in War until one player is eliminated and has performed their final strike (see page 7). At that point, Peacetime begins again… until the next warhead is launched.

Whenever Peacetime begins all players pick up the face-down cards on their launch track (see below). They then replace those cards with any cards from their hand, including the cards they just picked up. Active delivery systems remain active.

== Launch Track ==

In Nuclear War, you must plan your moves two turns in advance using the Launch Track.

Your Launch track is three spaces. The face-up space is for the card you are using this turn. The first face-down card is the card you will use next turn, and the second face-down space is the card you will play two turns from now.

'''2nd Face Down Card''' -> '''1st Face Down Card''' -> '''FACE UP CARD'''

You may look at facedown cards on your Launch Track whenever you want. You cannot change the order, or discard cards. Once you play a card to your Launch Track it is locked in!

Your Launch Track may only have delivery systems, warheads, and propaganda cards on it. If you ever reveal a card that is not a delivery system, warhead, or propaganda card, it is discarded without effect. This counts as your turn!

If your launch track is ever empty you must fill it immediately, if you don’t have enough eligible cards in your hand you must fill it on your next turn during the Play a Card step

== Card Types ==

=== Propagandas ===

During Peacetime, propaganda cards are used to steal population from other players (ie, the population defects to your nation). During Wartime, some propaganda cards allow you to draw new cards from the deck.

Whenever you steal population with a propaganda card, if the player doesn’t have enough population to give you, they give all their remaining population, and then they are eliminated from the game.

=== Delivery Systems ===

In order to launch a warhead in Nuclear Destruction, you need to have an appropriate delivery system.

Delivery systems are played in your launch track before a warhead. To launch a warhead, first, you must reveal a delivery system, and in the subsequent turn, reveal a warhead to go with that delivery system. If any card follows a delivery system that isn’t compatible with that delivery system, the delivery system will be discarded.

There are two main types of delivery systems: bombers and missiles. The two types of delivery systems work slightly differently when they are launched. For resolving a launch, see the Attacking the Enemy section.

The '''evasion rating''' on delivery systems determines how vulnerable they are to Anti-Missile cards. The Evasion rating has a letter, either M(Missile) or B(Bomber), and a number. See Anti-Missile cards (below) for details on evading a launch.

'''NOTE:''' If you shoot down a delivery system with an anti-missile, you play next, skipping all the players between.

==== Missiles ====

Missile delivery systems can carry one warhead up to a maximum megatonnage listed on the card.

'''''Example:''' An East Wind-DS31 Missile may carry a single warhead of up to 25 Megatons.''

Launching a missile requires playing the missile, and on the next turn, following it with a warhead of an appropriate size. After launching a missile it, and the warhead it carried, are discarded.

==== Bombers ====

Bombers are launched just like missiles: you reveal one and on the next turn reveal a warhead with low enough tonnage to be carried by it. Unlike missiles, a bomber is not discarded after delivering a payload. Instead, a bomber may deliver multiple warheads, each on its own turn, until the total megatonnage of war-heads delivered equals the bomber rating.

Bombers may bomb different enemy powers on different turns, flying over to the offending country. You do not discard a warhead delivered by a bomber. Instead, place the warhead under the bomber with its megatonnage showing so you can keep track of the megatonnage that the bomber has used. You only discard the warheads delivered by a bomber when the bomber is discarded. If you reveal a warhead that doesn’t fit the bomber, the warhead, the bomber, and all warheads under the bomber, are immediately discarded.

'''''Example:''' On The first turn, Ed launches the B-58 Bomber, which carries up to 60 mega-tons of warheads. On the next turn, Ed reveals a 20-megaton warhead. After resolving the strike, the 20-megaton warhead is kept with the B-58 Bomber. On the following turn, Ed reveals a 10-megaton warhead, this again is stacked with the bomber after resolving. In the next turn Ed reveals a 40-megaton warhead, this exceeds the bombers max-imum tonnage, and so the bomber along with all three warheads are discarded. The 40-megaton warhead would have no effect.''

=== Warheads ===

Warhead cards are played after a delivery system on the launch track. Warhead cards are rated by megatonnage, and how much population they destroy. The megatonnage is a limit to certain delivery systems, A larger megaton warhead that follows a delivery system not capable of carrying it is discarded along with the delivery system without effect. If the warhead fits on the delivery system played before it, the warhead has successfully launched and can target any other player. See Attacking a Player.

=== Anti Missiles ===

Anti-Missiles are reactive cards. They are played directly out of your hand when another player targets you with a warhead. When a delivery system targets you, you may discard an anti-missile to shoot down the delivery system. All anti-missiles are rated for what they will shoot down. Anti-Missiles have two ratings, one for Bombers (B) and one for Missiles (M). If the rating of the anti-missile is equal to or higher than the evasion rating of the incoming delivery system, the anti-missile can shoot it down.

If you cannot shoot down the incoming delivery system, you may not play an anti-missile. You may not use an anti-missile to help another player. You may only shoot down delivery systems targeting you.

When you successfully use an anti-missile, it becomes your turn, skipping all other players. Play continues clockwise after you have finished your turn.

=== Secrets and Top Secrets ===

Secrets are resolved, one at a time, when drawn, and do not go through the launch track. When drawn, announce you have a secret, as it may be stolen by a Spy. If it isn't stolen, play it. Each secret is a random event that has an effect on the game. Resolve the text, and then draw a replacement card. If the replacement is also a secret, resolve that one, and draw another replacement, continue to resolve secrets until a non-secret is drawn. If you have more than one secret in your hand, you choose which secret or top secret to resolve first. Top Secrets are resolved the same way as secrets, with the exception you have to announce it is a Top Secret. Top Secrets tend to be more powerful.

'''SECRETS!''' Secrets can be good or bad. When you draw a secret it is played before you begin your turn. Remember to give your opponents a chance to steal it before revealing the secret and resolving it!

=== Specials ===

Special cards are cards that are played out of your hand. Each Special explains when it may be played and what it does when you play it.

=== Hybrid Cards ===

Hybrid cards show both a warhead and a delivery system. When a hybrid card is revealed the revealing player decides which option to use. After choosing which option, the card is considered to be that type until discarded.

== Game Turn in Detail ==

=== Draw Cards ===

At the start of your turn, draw cards until you have 8 cards in hand.

If you have a secret in your hand you must announce you have a secret, and if no Spy steals it, then read it aloud and resolve the effects of the secret. If you draw more than one secret, you must play all of them, but you choose the order you play them. Whenever you play a secret or have it stolen from you, you draw a replacement card.

=== Play a Card ===

After drawing, slide your cards along the launch track pushing the first face-down card to the face-up card space, and the second face-down card to the first face-down card space. After sliding your cards over, place another card from your hand, face-down, onto the second face-down space.

=== Reveal a Card ===

Reveal and resolve the card in the face-up space. If the card is a propaganda card use the appropriate effect depending on whether it is Peacetime or War.

If it is a delivery system, place it in your active delivery system space, discarding any delivery system already there.

If it is a warhead, and there is a delivery system in your active delivery system space that can hold the warhead, congratulations, you’ve launched a nuke! Place the warhead on the active delivery system and Attack an Enemy! If the game state is Peacetime, it is now War!

If you did not launch a nuke, the next player in turn order takes their turn starting from step 1. If you did, once the attack is resolved – as long as no anti-missiles change whose turn it is – the next player in turn order takes their turn starting from step 1.

=== Attacking the Enemy ===

If you have launched a warhead, choose a target player. Then follow the steps below to resolve the strike:

# The target may use an anti-missile or a Saboteur to shoot down the delivery system or foil the launch. If they do, discard your delivery system and any of your warhead(s) that are face-up.
# If a launch is stopped by an anti-missile (not a Saboteur) the player that used the anti-missile immediately takes their turn, skipping all the players between the launching player and the target.
# If the target does not stop the attack, spin the spinner to find out the extra effects of the nuclear strike.
# You may roll the Nuclear Escalation die. If you do, add the amount rolled to the total population loss. If a Nuclear Cloud is rolled, roll on the malfunction chart.

The target then discards the amount of population equal to the damage dealt by the warhead. The target player may make change from unused population cards if needed. If the target does not have enough population, they are eliminated and they may make a final strike!

'''''Example:''' Trent takes 22 Million damage from a warhead, and discards a 25 Million population card, taking a 2 million and a 1 million population card from the unused population cards.''

# If the delivery system is a missile, discard the missile and warhead. If it is a bomber, only discard the bomber and warhead(s) if the total megatonnage of warheads on the bomber equals or exceeds its maximum tonnage.

==== Spinner Results ====

'''Radioactive Beta Rays Kill another 5 million.''' Add 5 million to the population loss on the warhead.

'''An additional 1 million are engulfed in the fireball.''' Add 1 million to the population loss on the warhead.

'''Dirty Bomb! Double the Yield.''' Double the population loss listed on the warhead. If the warhead is a 200 megaton warhead or larger, the world blows up, spreading nuclear fallout throughout the solar system and everyone loses. Smooth move!

'''No Appreciable Radiation Fallout.''' No extra effect, use the amount of population loss listed on the warhead.

'''Explodes a Nuclear Stockpile Triple the Yield.''' Triple the population loss listed on the warhead. If the warhead is 100 Megatons or more the world blows up in a massive chain reaction, spreading radioactive fallout throughout the solar system and everyone loses! Welcome to the new asteroid belt.

'''Bomb Shelters Save 2 Million.''' Reduce the amount of population loss by 2 million on the warhead. If this results in less than zero loss, treat it as a zero loss.

'''Lethal Doses of Radioactive Gamma Rays Kill Another 10 Million.''' Add 10 million to the population loss on the warhead.

'''Dud Warhead! (No Effect).''' Place the warhead on the delivery system without effect. Your attack ends, it is now the next player’s turn.

'''Radioactive Fallout Kills Another 2 Million.''' Add 2 Million to the population loss on the warhead.

'''Missile Booster Explodes on Launch (or Bomber Runs Out of Fuel)''' Discard the delivery system and the warhead(s). Your attack ends, it is now the next player’s turn.

==== Nuclear Escalation Die Roll Results ====

'''Cloud: Disaster!''' You have somehow directed this warhead at one of your own cities. You lose the population rather than your target.

'''2: Orbital Burst!''' The warhead goes off in the atmosphere over your country! Discard your delivery system and all face-up warheads on your player mat. You skip your next turn!

'''3: Missile Booster Explodes on Launch''' (or a Bomber Runs out of fuel) Discard the Delivery system and the warhead(s). Your attack ends and it is now the next player's turn.

'''4: This Warhead is a dud.''' Place the warhead on its delivery system without effect. Your attack ends and it is the next player's turn.

'''5: Neutron Bomb! Double the yield.''' Double the population loss listed on the warhead.

'''6: You hit a nuclear power plant.''' You do double damage, and your opponent misses one turn! Double the population loss listed on the warhead. Remind your opponent to skip their next turn.

=== Player Elimination and Final Strike ===

If you lose all of your population, you have been eliminated from the game.

If you’ve been eliminated through propaganda, you are out of the game, and the other players continue playing the game until there is a winner, or everyone loses.

If you are eliminated through any other means (i.e. secrets, or nuclear attack) you have the option to launch a final strike. You may play all the cards in your hand and on your launch mat. Combining any eligible warhead with your delivery systems in any way you wish. Once you have combined all of your eligible delivery systems and warheads, you may launch them at any targets you wish. Resolve them one at a time, just as above.

Anti-missiles will shoot down a final strike target, but it will not stop the rest of your final strike. The same is true for any dud or failed launch from the spinner.

The player to last play an anti-missile during the final strike will become the next player, otherwise, play continues clockwise. The exception is if another player is eliminated during a final strike, in which case they perform their final strike immediately after the first final strike is finished.

It is possible that a chain reaction of final strikes will '''eliminate all''' remaining players. If this happens, everyone loses the game, just like a real nuclear war! Once a player is eliminated and has played their final strike, it becomes Peacetime.

'''''Example:''' Trent has been eliminated and is planning out his final strike. He has 3 missiles and a bomber loaded with megatonnage. He looses his bomber on Brittany, who had eliminated him, but Brittany shoots it down with an anti-missile. Trent sighs and decides to send the rest of his missiles against Ed. Ed is eliminated and immediately begins his final strike, ignoring Brittanyâ€™s use of the anti-missile. If everyone left survives Ed's final strike, then Brittany will begin her turn, unless another player had played an anti-missile.''

==== When Peace is Declared... ====

When it becomes Peacetime, you may pick up all your cards on the launch track and replace them with cards from your hand.

==== Winning the Ultimate Victory ====

If, after all final strikes, you are the only remaining player with population, You have “won” the game! Your remaining population will enjoy the nuclear winter that follows and begin to slowly rebuild civilization.

=== Deterrent Force ===

If you have a powerful weapon in your hand you may wish to display it in order to discourage an enemy attack. You may, as part of your turn, place one or two cards face up in the deterrent force area as shown on the launch mat. A Saturn missile and a 100-megaton warhead, for example, may cause an enemy to think twice before beginning a nuclear exchange.

Cards in your deterrent force area remain part of your hand and must be put into play in the same way as any other cards. Any specials or secrets that affect your hand also affect any cards in the deterrent force. You should pick up your deterrents before resolving a secret that affects your hand.

== Optional Rules ==

=== Use Escalation Die ===

The Escalation Die may be optionally rolled for all attacks.

=== Track Revealed Population ===

The game automatically tracks which population cards for each player have been revealed (such as by being taken from other players or received from the population bank as change), giving their opponents an idea of what their population might be.

=== More people! ===

Before dealing starting populations, give each player one 25 million population card. Then deal one less population card to all the players.

=== All Propaganda cards allow discarding in War ===

No matter which card sets you use, all Propaganda cards may be played during war to draw and then discard 2 cards.

=== Not so secretive! ===

If a player has more than two secrets dealt to them at the beginning, randomly choose two of them, return the rest to the bottom of the deck and draw replacements. If more secrets are drawn they are also put at the bottom of the deck and replaced.

=== Bombers aren’t quite as fast as Missiles! ===

When launching a Bomber you must target a player sitting next to you. After targeting that player you may fly to the player sitting next to the current target or stay on the current target with the next warhead the bomber carries. During a Final Strike, a bomber must target only one player.

=== Everyone loses if everyone dies! ===

This is the normal way to play Nuclear War and is recommended, but if you're playing tournaments then you can turn this off so that players are ranked by how long they last.

== Card Sets ==

You may choose which Nuclear War card sets to use from the many expansions that have been released over the years. When playing with multiple sets you can choose to just combine all the cards into a single large deck or the system can create a '''Constructed''' deck which balances a deck for the number of players, drawing cards from the options you choose. Here's a quick overview.

=== Nuclear War ===

Just the basics. Propaganda, Missiles, Bombers, Warheads, a few Secrets and Spies. Nothing fancy.

=== Nuclear Escalation ===

More basics plus the likes of Space Platforms (deploy missiles to space and drop them on your opponents from there), Killer Satellites (the natural enemy of the Space Platform), MX Missiles (splits large warheads into smaller ones), Cruise Missiles (a missile with a built-in warhead that flies around the board until it drops) and Saboteurs (who can sabotage any launch).

=== Nuclear Proliferation ===

More basics plus Stealth Bombers (play straight from your hand after revealing a warhead as your Face Up Card), Stealth Fighters (the natural enemy of the Stealth Bomber), Atomic Cannons (deploy once for a permanent 10 megaton delivery system against a neighbor), Submarines (allows you to load warheads straight from your hand), Space Shuttles (a bomber that can be used to restock a Space Platform), and Saboteurs (who can sabotage any launch).

=== Nuclear Destruction ===

More basics with a greater variety of megatonnage. Plenty of Hybrid cards and Propaganda cards that will let you draw and discard during Wartime.

=== Booster Pack ===

An add-on pack with some new numbers for Propaganda cards and warheads (including the 200 megaton warhead). Dirty warheads (spin twice), Shipboard missiles (play straight from your hand after revealing a warhead as your Face Up Card), DCX-Delta Clippers (a bomber that you can keep after using). When the Booster Pack is used, only some of the cards are randomly added to your deck.

Gamehelpnuclearwar

2026-03-16T00:59:01Z

BaronFraser: /* Card Sets */

== Introduction ==

The atomic bomb has been invented. Nations are building up their stockpiles of atomic bombs while vying for the hearts and minds of their rivals’ populace. Welcome to the world of Nuclear War!

The game begins with an uneasy cold war between all the players, each representing a nuclear power. Once the first player launches a nuclear warhead, the war turns hot as populations decrease in huge balls of nuclear fire. Will there be any nation left when the last bomb has fallen?

== Object ==

In Nuclear War players seek world domination by eliminating the other major powers. This can be accomplished in two ways:

* The peaceful way is to persuade the populations of opposing countries to join your superior form of government through the use of propaganda cards.
* The warlike way is to destroy the enemy’s population by using nuclear weapons.

Population is the measure of success or failure in the game. A player who loses their entire population is eliminated. The last player with population wins the game, but sometimes everyone is engulfed in flames and there are only losers.

== Set Up ==

# Shuffle the population cards. Based on the player count, deal each player the following number of cards: 2 players: 15 cards; 3 players: 10 cards; 4 players: 8 cards; 5 players: 7 cards; 6+ players: 6 cards. Deal these cards face down. Only you may look at your population cards.
# Place the remaining population cards in a face up stack in the middle of the table forming a bank. Players may use the bank to make ‘change’ only when they are forced to lose population.
# Shuffle the Nuclear War cards and deal 9 face-down to each player. You may examine your cards but not other player’s.
# Place the remaining Nuclear War cards in a face-down stack in the middle of the table. This is a draw deck.
# The first player is randomly chosen. Play will proceed clockwise around the table from the first player.
# The first player examines their cards for any secrets and top secrets. If they have any, they play them. Once the first player has a hand with no secrets, the next player in turn declares and plays secrets. Continue this around the table until no one has any secrets left!

'''NOTE''': '''Spies!''' To play a '''secret''' you announce that you have a secret, then give each other player a moment to decide if they want to play a spy. If no one plays a '''spy''', reveal and resolve the secret. Repeat this process every time you play a secret.

7: All players, at the same time, choose and place 1 card facedown in each of the two face-down slots on their playmat. These are the cards that will be played on your first and second turn respectively!
8: Now you are ready to play! The first player takes the first turn.

== Overview of Gameplay ==

On your turn you will:

* Draw cards until you have 8 in your hand.
* Play secrets and draw replacement cards until no secrets are in hand.
* Move the cards on your launch track forward to the next box
* Place a card into the 2nd face-down slot
* Reveal the card in the face-up slot and play it.

== War and Peace ==

Nuclear War has two game states - '''Peacetime''' and '''War'''. The game state affects how some cards work.

The game starts in Peacetime. Once there is a successful launch of a delivery system with a warhead, whether or not the launch results in population loss, the game state changes to War.

The game state remains in War until one player is eliminated and has performed their final strike (see page 7). At that point, Peacetime begins again… until the next warhead is launched.

Whenever Peacetime begins all players pick up the face-down cards on their launch track (see below). They then replace those cards with any cards from their hand, including the cards they just picked up. Active delivery systems remain active.

== Launch Track ==

In Nuclear War, you must plan your moves two turns in advance using the Launch Track.

Your Launch track is three spaces. The face-up space is for the card you are using this turn. The first face-down card is the card you will use next turn, and the second face-down space is the card you will play two turns from now.

'''2nd Face Down Card''' -> '''1st Face Down Card''' -> '''FACE UP CARD'''

You may look at facedown cards on your Launch Track whenever you want. You cannot change the order, or discard cards. Once you play a card to your Launch Track it is locked in!

Your Launch Track may only have delivery systems, warheads, and propaganda cards on it. If you ever reveal a card that is not a delivery system, warhead, or propaganda card, it is discarded without effect. This counts as your turn!

If your launch track is ever empty you must fill it immediately, if you don’t have enough eligible cards in your hand you must fill it on your next turn during the Play a Card step

== Card Types ==

=== Propagandas ===

During Peacetime, propaganda cards are used to steal population from other players (ie, the population defects to your nation). During Wartime, some propaganda cards allow you to draw new cards from the deck.

Whenever you steal population with a propaganda card, if the player doesn’t have enough population to give you, they give all their remaining population, and then they are eliminated from the game.

=== Delivery Systems ===

In order to launch a warhead in Nuclear Destruction, you need to have an appropriate delivery system.

Delivery systems are played in your launch track before a warhead. To launch a warhead, first, you must reveal a delivery system, and in the subsequent turn, reveal a warhead to go with that delivery system. If any card follows a delivery system that isn’t compatible with that delivery system, the delivery system will be discarded.

There are two main types of delivery systems: bombers and missiles. The two types of delivery systems work slightly differently when they are launched. For resolving a launch, see the Attacking the Enemy section.

The '''evasion rating''' on delivery systems determines how vulnerable they are to Anti-Missile cards. The Evasion rating has a letter, either M(Missile) or B(Bomber), and a number. See Anti-Missile cards (below) for details on evading a launch.

'''NOTE:''' If you shoot down a delivery system with an anti-missile, you play next, skipping all the players between.

==== Missiles ====

Missile delivery systems can carry one warhead up to a maximum megatonnage listed on the card.

'''''Example:''' An East Wind-DS31 Missile may carry a single warhead of up to 25 Megatons.''

Launching a missile requires playing the missile, and on the next turn, following it with a warhead of an appropriate size. After launching a missile it, and the warhead it carried, are discarded.

==== Bombers ====

Bombers are launched just like missiles: you reveal one and on the next turn reveal a warhead with low enough tonnage to be carried by it. Unlike missiles, a bomber is not discarded after delivering a payload. Instead, a bomber may deliver multiple warheads, each on its own turn, until the total megatonnage of war-heads delivered equals the bomber rating.

Bombers may bomb different enemy powers on different turns, flying over to the offending country. You do not discard a warhead delivered by a bomber. Instead, place the warhead under the bomber with its megatonnage showing so you can keep track of the megatonnage that the bomber has used. You only discard the warheads delivered by a bomber when the bomber is discarded. If you reveal a warhead that doesn’t fit the bomber, the warhead, the bomber, and all warheads under the bomber, are immediately discarded.

'''''Example:''' On The first turn, Ed launches the B-58 Bomber, which carries up to 60 mega-tons of warheads. On the next turn, Ed reveals a 20-megaton warhead. After resolving the strike, the 20-megaton warhead is kept with the B-58 Bomber. On the following turn, Ed reveals a 10-megaton warhead, this again is stacked with the bomber after resolving. In the next turn Ed reveals a 40-megaton warhead, this exceeds the bombers max-imum tonnage, and so the bomber along with all three warheads are discarded. The 40-megaton warhead would have no effect.''

=== Warheads ===

Warhead cards are played after a delivery system on the launch track. Warhead cards are rated by megatonnage, and how much population they destroy. The megatonnage is a limit to certain delivery systems, A larger megaton warhead that follows a delivery system not capable of carrying it is discarded along with the delivery system without effect. If the warhead fits on the delivery system played before it, the warhead has successfully launched and can target any other player. See Attacking a Player.

=== Anti Missiles ===

Anti-Missiles are reactive cards. They are played directly out of your hand when another player targets you with a warhead. When a delivery system targets you, you may discard an anti-missile to shoot down the delivery system. All anti-missiles are rated for what they will shoot down. Anti-Missiles have two ratings, one for Bombers (B) and one for Missiles (M). If the rating of the anti-missile is equal to or higher than the evasion rating of the incoming delivery system, the anti-missile can shoot it down.

If you cannot shoot down the incoming delivery system, you may not play an anti-missile. You may not use an anti-missile to help another player. You may only shoot down delivery systems targeting you.

When you successfully use an anti-missile, it becomes your turn, skipping all other players. Play continues clockwise after you have finished your turn.

=== Secrets and Top Secrets ===

Secrets are resolved, one at a time, when drawn, and do not go through the launch track. When drawn, announce you have a secret, as it may be stolen by a Spy. If it isn't stolen, play it. Each secret is a random event that has an effect on the game. Resolve the text, and then draw a replacement card. If the replacement is also a secret, resolve that one, and draw another replacement, continue to resolve secrets until a non-secret is drawn. If you have more than one secret in your hand, you choose which secret or top secret to resolve first. Top Secrets are resolved the same way as secrets, with the exception you have to announce it is a Top Secret. Top Secrets tend to be more powerful.

'''SECRETS!''' Secrets can be good or bad. When you draw a secret it is played before you begin your turn. Remember to give your opponents a chance to steal it before revealing the secret and resolving it!

=== Specials ===

Special cards are cards that are played out of your hand. Each Special explains when it may be played and what it does when you play it.

=== Hybrid Cards ===

Hybrid cards show both a warhead and a delivery system. When a hybrid card is revealed the revealing player decides which option to use. After choosing which option, the card is considered to be that type until discarded.

== Game Turn in Detail ==

=== Draw Cards ===

At the start of your turn, draw cards until you have 8 cards in hand.

If you have a secret in your hand you must announce you have a secret, and if no Spy steals it, then read it aloud and resolve the effects of the secret. If you draw more than one secret, you must play all of them, but you choose the order you play them. Whenever you play a secret or have it stolen from you, you draw a replacement card.

=== Play a Card ===

After drawing, slide your cards along the launch track pushing the first face-down card to the face-up card space, and the second face-down card to the first face-down card space. After sliding your cards over, place another card from your hand, face-down, onto the second face-down space.

=== Reveal a Card ===

Reveal and resolve the card in the face-up space. If the card is a propaganda card use the appropriate effect depending on whether it is Peacetime or War.

If it is a delivery system, place it in your active delivery system space, discarding any delivery system already there.

If it is a warhead, and there is a delivery system in your active delivery system space that can hold the warhead, congratulations, you’ve launched a nuke! Place the warhead on the active delivery system and Attack an Enemy! If the game state is Peacetime, it is now War!

If you did not launch a nuke, the next player in turn order takes their turn starting from step 1. If you did, once the attack is resolved – as long as no anti-missiles change whose turn it is – the next player in turn order takes their turn starting from step 1.

=== Attacking the Enemy ===

If you have launched a warhead, choose a target player. Then follow the steps below to resolve the strike:

# The target may use an anti-missile or a Saboteur to shoot down the delivery system or foil the launch. If they do, discard your delivery system and any of your warhead(s) that are face-up.
# If a launch is stopped by an anti-missile (not a Saboteur) the player that used the anti-missile immediately takes their turn, skipping all the players between the launching player and the target.
# If the target does not stop the attack, spin the spinner to find out the extra effects of the nuclear strike.
# You may roll the Nuclear Escalation die. If you do, add the amount rolled to the total population loss. If a Nuclear Cloud is rolled, roll on the malfunction chart.

The target then discards the amount of population equal to the damage dealt by the warhead. The target player may make change from unused population cards if needed. If the target does not have enough population, they are eliminated and they may make a final strike!

'''''Example:''' Trent takes 22 Million damage from a warhead, and discards a 25 Million population card, taking a 2 million and a 1 million population card from the unused population cards.''

# If the delivery system is a missile, discard the missile and warhead. If it is a bomber, only discard the bomber and warhead(s) if the total megatonnage of warheads on the bomber equals or exceeds its maximum tonnage.

==== Spinner Results ====

'''Radioactive Beta Rays Kill another 5 million.''' Add 5 million to the population loss on the warhead.

'''An additional 1 million are engulfed in the fireball.''' Add 1 million to the population loss on the warhead.

'''Dirty Bomb! Double the Yield.''' Double the population loss listed on the warhead. If the warhead is a 200 megaton warhead or larger, the world blows up, spreading nuclear fallout throughout the solar system and everyone loses. Smooth move!

'''No Appreciable Radiation Fallout.''' No extra effect, use the amount of population loss listed on the warhead.

'''Explodes a Nuclear Stockpile Triple the Yield.''' Triple the population loss listed on the warhead. If the warhead is 100 Megatons or more the world blows up in a massive chain reaction, spreading radioactive fallout throughout the solar system and everyone loses! Welcome to the new asteroid belt.

'''Bomb Shelters Save 2 Million.''' Reduce the amount of population loss by 2 million on the warhead. If this results in less than zero loss, treat it as a zero loss.

'''Lethal Doses of Radioactive Gamma Rays Kill Another 10 Million.''' Add 10 million to the population loss on the warhead.

'''Dud Warhead! (No Effect).''' Place the warhead on the delivery system without effect. Your attack ends, it is now the next player’s turn.

'''Radioactive Fallout Kills Another 2 Million.''' Add 2 Million to the population loss on the warhead.

'''Missile Booster Explodes on Launch (or Bomber Runs Out of Fuel)''' Discard the delivery system and the warhead(s). Your attack ends, it is now the next player’s turn.

==== Nuclear Escalation Die Roll Results ====

'''Cloud: Disaster!''' You have somehow directed this warhead at one of your own cities. You lose the population rather than your target.

'''2: Orbital Burst!''' The warhead goes off in the atmosphere over your country! Discard your delivery system and all face-up warheads on your player mat. You skip your next turn!

'''3: Missile Booster Explodes on Launch''' (or a Bomber Runs out of fuel) Discard the Delivery system and the warhead(s). Your attack ends and it is now the next player's turn.

'''4: This Warhead is a dud.''' Place the warhead on its delivery system without effect. Your attack ends and it is the next player's turn.

'''5: Neutron Bomb! Double the yield.''' Double the population loss listed on the warhead.

'''6: You hit a nuclear power plant.''' You do double damage, and your opponent misses one turn! Double the population loss listed on the warhead. Remind your opponent to skip their next turn.

=== Player Elimination and Final Strike ===

If you lose all of your population, you have been eliminated from the game.

If you’ve been eliminated through propaganda, you are out of the game, and the other players continue playing the game until there is a winner, or everyone loses.

If you are eliminated through any other means (i.e. secrets, or nuclear attack) you have the option to launch a final strike. You may play all the cards in your hand and on your launch mat. Combining any eligible warhead with your delivery systems in any way you wish. Once you have combined all of your eligible delivery systems and warheads, you may launch them at any targets you wish. Resolve them one at a time, just as above.

Anti-missiles will shoot down a final strike target, but it will not stop the rest of your final strike. The same is true for any dud or failed launch from the spinner.

The player to last play an anti-missile during the final strike will become the next player, otherwise, play continues clockwise. The exception is if another player is eliminated during a final strike, in which case they perform their final strike immediately after the first final strike is finished.

It is possible that a chain reaction of final strikes will '''eliminate all''' remaining players. If this happens, everyone loses the game, just like a real nuclear war! Once a player is eliminated and has played their final strike, it becomes Peacetime.

'''''Example:''' Trent has been eliminated and is planning out his final strike. He has 3 missiles and a bomber loaded with megatonnage. He looses his bomber on Brittany, who had eliminated him, but Brittany shoots it down with an anti-missile. Trent sighs and decides to send the rest of his missiles against Ed. Ed is eliminated and immediately begins his final strike, ignoring Brittanyâ€™s use of the anti-missile. If everyone left survives Ed's final strike, then Brittany will begin her turn, unless another player had played an anti-missile.''

==== When Peace is Declared... ====

When it becomes Peacetime, you may pick up all your cards on the launch track and replace them with cards from your hand.

==== Winning the Ultimate Victory ====

If, after all final strikes, you are the only remaining player with population, You have “won” the game! Your remaining population will enjoy the nuclear winter that follows and begin to slowly rebuild civilization.

=== Deterrent Force ===

If you have a powerful weapon in your hand you may wish to display it in order to discourage an enemy attack. You may, as part of your turn, place one or two cards face up in the deterrent force area as shown on the launch mat. A Saturn missile and a 100-megaton warhead, for example, may cause an enemy to think twice before beginning a nuclear exchange.

Cards in your deterrent force area remain part of your hand and must be put into play in the same way as any other cards. Any specials or secrets that affect your hand also affect any cards in the deterrent force. You should pick up your deterrents before resolving a secret that affects your hand.

== Optional Rules ==

=== Use Escalation Die ===

The Escalation Die may be optionally rolled for all attacks.

=== Track Revealed Population ===

The game automatically tracks which population cards for each player have been revealed (such as by being taken from other players or received from the population bank as change), giving their opponents an idea of what their population might be.

=== More people! ===

Before dealing starting populations, give each player one 25 million population card. Then deal one less population card to all the players.

=== All Propaganda cards allow discarding in War ===

No matter which card sets you use, all Propaganda cards may be played during war to draw and then discard 2 cards.

=== Not so secretive! ===

If a player has more than two secrets dealt to them at the beginning, randomly choose two of them, return the rest to the bottom of the deck and draw replacements. If more secrets are drawn they are also put at the bottom of the deck and replaced.

=== Bombers aren’t quite as fast as Missiles! ===

When launching a Bomber you must target a player sitting next to you. After targeting that player you may fly to the player sitting next to the current target or stay on the current target with the next warhead the bomber carries. During a Final Strike, a bomber must target only one player.

=== Everyone loses if everyone dies! ===

This is the normal way to play Nuclear War and is recommended, but if you're playing tournaments then you can turn this off so that players are ranked by how long they last.

== Card Sets ==

You may choose which Nuclear War card sets to use from the many expansions that have been released over the years. When playing with multiple sets you can choose to just combine all the cards into a single large deck or the system can create a '''Constructed''' deck which balances a deck for the number of players, drawing cards from the options you choose. Here's a quick overview.

=== Nuclear War ===

Just the basics. Propaganda, Missiles, Bombers, Warheads, a few Secrets and Spies. Nothing fancy.

=== Nuclear Escalation ===

More basics plus the likes of Space Platforms (deploy missiles to space and drop them on your opponents from there), Killer Satellites (the natural enemy of the Space Platform), MX Missiles (splits large warheads into smaller ones), Cruise Missiles (a missile with a built-in warhead that flies around the board until it drops) and Saboteurs (who can sabotage any launch).

=== Nuclear Proliferation ===

More basics plus Stealth Bombers (play straight from your hand after revealing a warhead as your Face Up Card), Stealth Fighters (the natural enemy of the Stealth Bomber), Atomic Cannons (deploy once for a permanent 10 megaton delivery system against a neighbor), Submarines (allows you to load warheads straight from your hand), Space Shuttles (a bomber that can be used to restock a Space Platform), and Saboteurs (who can sabotage any launch).

=== Nuclear Destruction ===

More basics with great variety of megatonnage. Plenty of Hybrid cards and Propaganda cards that will let you draw and discard during Wartime.

=== Booster Pack ===

An add-on pack with some new numbers for Propaganda cards and warheads (including the 200 megaton warhead). Dirty warheads (spin twice), Shipboard missiles (play straight from your hand after revealing a warhead as your Face Up Card), DCX-Delta Clippers (a bomber that you can keep after using). When the Booster Pack is used, only some of the cards are randomly added to your deck.

Gamehelpnuclearwar

2026-03-16T00:55:37Z

BaronFraser: /* Nuclear War Cards */

== Introduction ==

The atomic bomb has been invented. Nations are building up their stockpiles of atomic bombs while vying for the hearts and minds of their rivals’ populace. Welcome to the world of Nuclear War!

The game begins with an uneasy cold war between all the players, each representing a nuclear power. Once the first player launches a nuclear warhead, the war turns hot as populations decrease in huge balls of nuclear fire. Will there be any nation left when the last bomb has fallen?

== Object ==

In Nuclear War players seek world domination by eliminating the other major powers. This can be accomplished in two ways:

* The peaceful way is to persuade the populations of opposing countries to join your superior form of government through the use of propaganda cards.
* The warlike way is to destroy the enemy’s population by using nuclear weapons.

Population is the measure of success or failure in the game. A player who loses their entire population is eliminated. The last player with population wins the game, but sometimes everyone is engulfed in flames and there are only losers.

== Set Up ==

# Shuffle the population cards. Based on the player count, deal each player the following number of cards: 2 players: 15 cards; 3 players: 10 cards; 4 players: 8 cards; 5 players: 7 cards; 6+ players: 6 cards. Deal these cards face down. Only you may look at your population cards.
# Place the remaining population cards in a face up stack in the middle of the table forming a bank. Players may use the bank to make ‘change’ only when they are forced to lose population.
# Shuffle the Nuclear War cards and deal 9 face-down to each player. You may examine your cards but not other player’s.
# Place the remaining Nuclear War cards in a face-down stack in the middle of the table. This is a draw deck.
# The first player is randomly chosen. Play will proceed clockwise around the table from the first player.
# The first player examines their cards for any secrets and top secrets. If they have any, they play them. Once the first player has a hand with no secrets, the next player in turn declares and plays secrets. Continue this around the table until no one has any secrets left!

'''NOTE''': '''Spies!''' To play a '''secret''' you announce that you have a secret, then give each other player a moment to decide if they want to play a spy. If no one plays a '''spy''', reveal and resolve the secret. Repeat this process every time you play a secret.

7: All players, at the same time, choose and place 1 card facedown in each of the two face-down slots on their playmat. These are the cards that will be played on your first and second turn respectively!
8: Now you are ready to play! The first player takes the first turn.

== Overview of Gameplay ==

On your turn you will:

* Draw cards until you have 8 in your hand.
* Play secrets and draw replacement cards until no secrets are in hand.
* Move the cards on your launch track forward to the next box
* Place a card into the 2nd face-down slot
* Reveal the card in the face-up slot and play it.

== War and Peace ==

Nuclear War has two game states - '''Peacetime''' and '''War'''. The game state affects how some cards work.

The game starts in Peacetime. Once there is a successful launch of a delivery system with a warhead, whether or not the launch results in population loss, the game state changes to War.

The game state remains in War until one player is eliminated and has performed their final strike (see page 7). At that point, Peacetime begins again… until the next warhead is launched.

Whenever Peacetime begins all players pick up the face-down cards on their launch track (see below). They then replace those cards with any cards from their hand, including the cards they just picked up. Active delivery systems remain active.

== Launch Track ==

In Nuclear War, you must plan your moves two turns in advance using the Launch Track.

Your Launch track is three spaces. The face-up space is for the card you are using this turn. The first face-down card is the card you will use next turn, and the second face-down space is the card you will play two turns from now.

'''2nd Face Down Card''' -> '''1st Face Down Card''' -> '''FACE UP CARD'''

You may look at facedown cards on your Launch Track whenever you want. You cannot change the order, or discard cards. Once you play a card to your Launch Track it is locked in!

Your Launch Track may only have delivery systems, warheads, and propaganda cards on it. If you ever reveal a card that is not a delivery system, warhead, or propaganda card, it is discarded without effect. This counts as your turn!

If your launch track is ever empty you must fill it immediately, if you don’t have enough eligible cards in your hand you must fill it on your next turn during the Play a Card step

== Card Types ==

=== Propagandas ===

During Peacetime, propaganda cards are used to steal population from other players (ie, the population defects to your nation). During Wartime, some propaganda cards allow you to draw new cards from the deck.

Whenever you steal population with a propaganda card, if the player doesn’t have enough population to give you, they give all their remaining population, and then they are eliminated from the game.

=== Delivery Systems ===

In order to launch a warhead in Nuclear Destruction, you need to have an appropriate delivery system.

Delivery systems are played in your launch track before a warhead. To launch a warhead, first, you must reveal a delivery system, and in the subsequent turn, reveal a warhead to go with that delivery system. If any card follows a delivery system that isn’t compatible with that delivery system, the delivery system will be discarded.

There are two main types of delivery systems: bombers and missiles. The two types of delivery systems work slightly differently when they are launched. For resolving a launch, see the Attacking the Enemy section.

The '''evasion rating''' on delivery systems determines how vulnerable they are to Anti-Missile cards. The Evasion rating has a letter, either M(Missile) or B(Bomber), and a number. See Anti-Missile cards (below) for details on evading a launch.

'''NOTE:''' If you shoot down a delivery system with an anti-missile, you play next, skipping all the players between.

==== Missiles ====

Missile delivery systems can carry one warhead up to a maximum megatonnage listed on the card.

'''''Example:''' An East Wind-DS31 Missile may carry a single warhead of up to 25 Megatons.''

Launching a missile requires playing the missile, and on the next turn, following it with a warhead of an appropriate size. After launching a missile it, and the warhead it carried, are discarded.

==== Bombers ====

Bombers are launched just like missiles: you reveal one and on the next turn reveal a warhead with low enough tonnage to be carried by it. Unlike missiles, a bomber is not discarded after delivering a payload. Instead, a bomber may deliver multiple warheads, each on its own turn, until the total megatonnage of war-heads delivered equals the bomber rating.

Bombers may bomb different enemy powers on different turns, flying over to the offending country. You do not discard a warhead delivered by a bomber. Instead, place the warhead under the bomber with its megatonnage showing so you can keep track of the megatonnage that the bomber has used. You only discard the warheads delivered by a bomber when the bomber is discarded. If you reveal a warhead that doesn’t fit the bomber, the warhead, the bomber, and all warheads under the bomber, are immediately discarded.

'''''Example:''' On The first turn, Ed launches the B-58 Bomber, which carries up to 60 mega-tons of warheads. On the next turn, Ed reveals a 20-megaton warhead. After resolving the strike, the 20-megaton warhead is kept with the B-58 Bomber. On the following turn, Ed reveals a 10-megaton warhead, this again is stacked with the bomber after resolving. In the next turn Ed reveals a 40-megaton warhead, this exceeds the bombers max-imum tonnage, and so the bomber along with all three warheads are discarded. The 40-megaton warhead would have no effect.''

=== Warheads ===

Warhead cards are played after a delivery system on the launch track. Warhead cards are rated by megatonnage, and how much population they destroy. The megatonnage is a limit to certain delivery systems, A larger megaton warhead that follows a delivery system not capable of carrying it is discarded along with the delivery system without effect. If the warhead fits on the delivery system played before it, the warhead has successfully launched and can target any other player. See Attacking a Player.

=== Anti Missiles ===

Anti-Missiles are reactive cards. They are played directly out of your hand when another player targets you with a warhead. When a delivery system targets you, you may discard an anti-missile to shoot down the delivery system. All anti-missiles are rated for what they will shoot down. Anti-Missiles have two ratings, one for Bombers (B) and one for Missiles (M). If the rating of the anti-missile is equal to or higher than the evasion rating of the incoming delivery system, the anti-missile can shoot it down.

If you cannot shoot down the incoming delivery system, you may not play an anti-missile. You may not use an anti-missile to help another player. You may only shoot down delivery systems targeting you.

When you successfully use an anti-missile, it becomes your turn, skipping all other players. Play continues clockwise after you have finished your turn.

=== Secrets and Top Secrets ===

Secrets are resolved, one at a time, when drawn, and do not go through the launch track. When drawn, announce you have a secret, as it may be stolen by a Spy. If it isn't stolen, play it. Each secret is a random event that has an effect on the game. Resolve the text, and then draw a replacement card. If the replacement is also a secret, resolve that one, and draw another replacement, continue to resolve secrets until a non-secret is drawn. If you have more than one secret in your hand, you choose which secret or top secret to resolve first. Top Secrets are resolved the same way as secrets, with the exception you have to announce it is a Top Secret. Top Secrets tend to be more powerful.

'''SECRETS!''' Secrets can be good or bad. When you draw a secret it is played before you begin your turn. Remember to give your opponents a chance to steal it before revealing the secret and resolving it!

=== Specials ===

Special cards are cards that are played out of your hand. Each Special explains when it may be played and what it does when you play it.

=== Hybrid Cards ===

Hybrid cards show both a warhead and a delivery system. When a hybrid card is revealed the revealing player decides which option to use. After choosing which option, the card is considered to be that type until discarded.

== Game Turn in Detail ==

=== Draw Cards ===

At the start of your turn, draw cards until you have 8 cards in hand.

If you have a secret in your hand you must announce you have a secret, and if no Spy steals it, then read it aloud and resolve the effects of the secret. If you draw more than one secret, you must play all of them, but you choose the order you play them. Whenever you play a secret or have it stolen from you, you draw a replacement card.

=== Play a Card ===

After drawing, slide your cards along the launch track pushing the first face-down card to the face-up card space, and the second face-down card to the first face-down card space. After sliding your cards over, place another card from your hand, face-down, onto the second face-down space.

=== Reveal a Card ===

Reveal and resolve the card in the face-up space. If the card is a propaganda card use the appropriate effect depending on whether it is Peacetime or War.

If it is a delivery system, place it in your active delivery system space, discarding any delivery system already there.

If it is a warhead, and there is a delivery system in your active delivery system space that can hold the warhead, congratulations, you’ve launched a nuke! Place the warhead on the active delivery system and Attack an Enemy! If the game state is Peacetime, it is now War!

If you did not launch a nuke, the next player in turn order takes their turn starting from step 1. If you did, once the attack is resolved – as long as no anti-missiles change whose turn it is – the next player in turn order takes their turn starting from step 1.

=== Attacking the Enemy ===

If you have launched a warhead, choose a target player. Then follow the steps below to resolve the strike:

# The target may use an anti-missile or a Saboteur to shoot down the delivery system or foil the launch. If they do, discard your delivery system and any of your warhead(s) that are face-up.
# If a launch is stopped by an anti-missile (not a Saboteur) the player that used the anti-missile immediately takes their turn, skipping all the players between the launching player and the target.
# If the target does not stop the attack, spin the spinner to find out the extra effects of the nuclear strike.
# You may roll the Nuclear Escalation die. If you do, add the amount rolled to the total population loss. If a Nuclear Cloud is rolled, roll on the malfunction chart.

The target then discards the amount of population equal to the damage dealt by the warhead. The target player may make change from unused population cards if needed. If the target does not have enough population, they are eliminated and they may make a final strike!

'''''Example:''' Trent takes 22 Million damage from a warhead, and discards a 25 Million population card, taking a 2 million and a 1 million population card from the unused population cards.''

# If the delivery system is a missile, discard the missile and warhead. If it is a bomber, only discard the bomber and warhead(s) if the total megatonnage of warheads on the bomber equals or exceeds its maximum tonnage.

==== Spinner Results ====

'''Radioactive Beta Rays Kill another 5 million.''' Add 5 million to the population loss on the warhead.

'''An additional 1 million are engulfed in the fireball.''' Add 1 million to the population loss on the warhead.

'''Dirty Bomb! Double the Yield.''' Double the population loss listed on the warhead. If the warhead is a 200 megaton warhead or larger, the world blows up, spreading nuclear fallout throughout the solar system and everyone loses. Smooth move!

'''No Appreciable Radiation Fallout.''' No extra effect, use the amount of population loss listed on the warhead.

'''Explodes a Nuclear Stockpile Triple the Yield.''' Triple the population loss listed on the warhead. If the warhead is 100 Megatons or more the world blows up in a massive chain reaction, spreading radioactive fallout throughout the solar system and everyone loses! Welcome to the new asteroid belt.

'''Bomb Shelters Save 2 Million.''' Reduce the amount of population loss by 2 million on the warhead. If this results in less than zero loss, treat it as a zero loss.

'''Lethal Doses of Radioactive Gamma Rays Kill Another 10 Million.''' Add 10 million to the population loss on the warhead.

'''Dud Warhead! (No Effect).''' Place the warhead on the delivery system without effect. Your attack ends, it is now the next player’s turn.

'''Radioactive Fallout Kills Another 2 Million.''' Add 2 Million to the population loss on the warhead.

'''Missile Booster Explodes on Launch (or Bomber Runs Out of Fuel)''' Discard the delivery system and the warhead(s). Your attack ends, it is now the next player’s turn.

==== Nuclear Escalation Die Roll Results ====

'''Cloud: Disaster!''' You have somehow directed this warhead at one of your own cities. You lose the population rather than your target.

'''2: Orbital Burst!''' The warhead goes off in the atmosphere over your country! Discard your delivery system and all face-up warheads on your player mat. You skip your next turn!

'''3: Missile Booster Explodes on Launch''' (or a Bomber Runs out of fuel) Discard the Delivery system and the warhead(s). Your attack ends and it is now the next player's turn.

'''4: This Warhead is a dud.''' Place the warhead on its delivery system without effect. Your attack ends and it is the next player's turn.

'''5: Neutron Bomb! Double the yield.''' Double the population loss listed on the warhead.

'''6: You hit a nuclear power plant.''' You do double damage, and your opponent misses one turn! Double the population loss listed on the warhead. Remind your opponent to skip their next turn.

=== Player Elimination and Final Strike ===

If you lose all of your population, you have been eliminated from the game.

If you’ve been eliminated through propaganda, you are out of the game, and the other players continue playing the game until there is a winner, or everyone loses.

If you are eliminated through any other means (i.e. secrets, or nuclear attack) you have the option to launch a final strike. You may play all the cards in your hand and on your launch mat. Combining any eligible warhead with your delivery systems in any way you wish. Once you have combined all of your eligible delivery systems and warheads, you may launch them at any targets you wish. Resolve them one at a time, just as above.

Anti-missiles will shoot down a final strike target, but it will not stop the rest of your final strike. The same is true for any dud or failed launch from the spinner.

The player to last play an anti-missile during the final strike will become the next player, otherwise, play continues clockwise. The exception is if another player is eliminated during a final strike, in which case they perform their final strike immediately after the first final strike is finished.

It is possible that a chain reaction of final strikes will '''eliminate all''' remaining players. If this happens, everyone loses the game, just like a real nuclear war! Once a player is eliminated and has played their final strike, it becomes Peacetime.

'''''Example:''' Trent has been eliminated and is planning out his final strike. He has 3 missiles and a bomber loaded with megatonnage. He looses his bomber on Brittany, who had eliminated him, but Brittany shoots it down with an anti-missile. Trent sighs and decides to send the rest of his missiles against Ed. Ed is eliminated and immediately begins his final strike, ignoring Brittanyâ€™s use of the anti-missile. If everyone left survives Ed's final strike, then Brittany will begin her turn, unless another player had played an anti-missile.''

==== When Peace is Declared... ====

When it becomes Peacetime, you may pick up all your cards on the launch track and replace them with cards from your hand.

==== Winning the Ultimate Victory ====

If, after all final strikes, you are the only remaining player with population, You have “won” the game! Your remaining population will enjoy the nuclear winter that follows and begin to slowly rebuild civilization.

=== Deterrent Force ===

If you have a powerful weapon in your hand you may wish to display it in order to discourage an enemy attack. You may, as part of your turn, place one or two cards face up in the deterrent force area as shown on the launch mat. A Saturn missile and a 100-megaton warhead, for example, may cause an enemy to think twice before beginning a nuclear exchange.

Cards in your deterrent force area remain part of your hand and must be put into play in the same way as any other cards. Any specials or secrets that affect your hand also affect any cards in the deterrent force. You should pick up your deterrents before resolving a secret that affects your hand.

== Optional Rules ==

=== Use Escalation Die ===

The Escalation Die may be optionally rolled for all attacks.

=== Track Revealed Population ===

The game automatically tracks which population cards for each player have been revealed (such as by being taken from other players or received from the population bank as change), giving their opponents an idea of what their population might be.

=== More people! ===

Before dealing starting populations, give each player one 25 million population card. Then deal one less population card to all the players.

=== All Propaganda cards allow discarding in War ===

No matter which card sets you use, all Propaganda cards may be played during war to draw and then discard 2 cards.

=== Not so secretive! ===

If a player has more than two secrets dealt to them at the beginning, randomly choose two of them, return the rest to the bottom of the deck and draw replacements. If more secrets are drawn they are also put at the bottom of the deck and replaced.

=== Bombers aren’t quite as fast as Missiles! ===

When launching a Bomber you must target a player sitting next to you. After targeting that player you may fly to the player sitting next to the current target or stay on the current target with the next warhead the bomber carries. During a Final Strike, a bomber must target only one player.

=== Everyone loses if everyone dies! ===

This is the normal way to play Nuclear War and is recommended, but if you're playing tournaments then you can turn this off so that players are ranked by how long they last.

== Card Sets ==

You may choose which Nuclear War card sets to use from the many expansions that have been released over the years. Here's a quick overview.

=== Nuclear War ===

Just the basics. Propaganda, Missiles, Bombers, Warheads, a few Secrets and Spies. Nothing fancy.

=== Nuclear Escalation ===

More basics plus the likes of Space Platforms (deploy missiles to space and drop them on your opponents from there), Killer Satellites (the natural enemy of the Space Platform), MX Missiles (splits large warheads into smaller ones), Cruise Missiles (a missile with a built-in warhead that flies around the board until it drops) and Saboteurs (who can sabotage any launch).

=== Nuclear Proliferation ===

More basics plus Stealth Bombers (play straight from your hand after revealing a warhead as your Face Up Card), Stealth Fighters (the natural enemy of the Stealth Bomber), Atomic Cannons (deploy once for a permanent 10 megaton delivery system against a neighbor), Submarines (allows you to load warheads straight from your hand), Space Shuttles (a bomber that can be used to restock a Space Platform), and Saboteurs (who can sabotage any launch).

=== Nuclear Destruction ===

More basics with great variety of megatonnage. Plenty of Hybrid cards and Propaganda cards that will let you draw and discard during Wartime.

=== Booster Pack ===

An add-on pack with some new numbers for Propaganda cards and warheads (including the 200 megaton warhead). Dirty warheads (spin twice), Shipboard missiles (play straight from your hand after revealing a warhead as your Face Up Card), DCX-Delta Clippers (a bomber that you can keep after using). When the Booster Pack is used, only some of the cards are randomly added to your deck.

Gamehelpnuclearwar

2026-03-16T00:55:06Z

BaronFraser: /* Optional Rules */

== Introduction ==

The atomic bomb has been invented. Nations are building up their stockpiles of atomic bombs while vying for the hearts and minds of their rivals’ populace. Welcome to the world of Nuclear War!

The game begins with an uneasy cold war between all the players, each representing a nuclear power. Once the first player launches a nuclear warhead, the war turns hot as populations decrease in huge balls of nuclear fire. Will there be any nation left when the last bomb has fallen?

== Object ==

In Nuclear War players seek world domination by eliminating the other major powers. This can be accomplished in two ways:

* The peaceful way is to persuade the populations of opposing countries to join your superior form of government through the use of propaganda cards.
* The warlike way is to destroy the enemy’s population by using nuclear weapons.

Population is the measure of success or failure in the game. A player who loses their entire population is eliminated. The last player with population wins the game, but sometimes everyone is engulfed in flames and there are only losers.

== Set Up ==

# Shuffle the population cards. Based on the player count, deal each player the following number of cards: 2 players: 15 cards; 3 players: 10 cards; 4 players: 8 cards; 5 players: 7 cards; 6+ players: 6 cards. Deal these cards face down. Only you may look at your population cards.
# Place the remaining population cards in a face up stack in the middle of the table forming a bank. Players may use the bank to make ‘change’ only when they are forced to lose population.
# Shuffle the Nuclear War cards and deal 9 face-down to each player. You may examine your cards but not other player’s.
# Place the remaining Nuclear War cards in a face-down stack in the middle of the table. This is a draw deck.
# The first player is randomly chosen. Play will proceed clockwise around the table from the first player.
# The first player examines their cards for any secrets and top secrets. If they have any, they play them. Once the first player has a hand with no secrets, the next player in turn declares and plays secrets. Continue this around the table until no one has any secrets left!

'''NOTE''': '''Spies!''' To play a '''secret''' you announce that you have a secret, then give each other player a moment to decide if they want to play a spy. If no one plays a '''spy''', reveal and resolve the secret. Repeat this process every time you play a secret.

7: All players, at the same time, choose and place 1 card facedown in each of the two face-down slots on their playmat. These are the cards that will be played on your first and second turn respectively!
8: Now you are ready to play! The first player takes the first turn.

== Overview of Gameplay ==

On your turn you will:

* Draw cards until you have 8 in your hand.
* Play secrets and draw replacement cards until no secrets are in hand.
* Move the cards on your launch track forward to the next box
* Place a card into the 2nd face-down slot
* Reveal the card in the face-up slot and play it.

== War and Peace ==

Nuclear War has two game states - '''Peacetime''' and '''War'''. The game state affects how some cards work.

The game starts in Peacetime. Once there is a successful launch of a delivery system with a warhead, whether or not the launch results in population loss, the game state changes to War.

The game state remains in War until one player is eliminated and has performed their final strike (see page 7). At that point, Peacetime begins again… until the next warhead is launched.

Whenever Peacetime begins all players pick up the face-down cards on their launch track (see below). They then replace those cards with any cards from their hand, including the cards they just picked up. Active delivery systems remain active.

== Launch Track ==

In Nuclear War, you must plan your moves two turns in advance using the Launch Track.

Your Launch track is three spaces. The face-up space is for the card you are using this turn. The first face-down card is the card you will use next turn, and the second face-down space is the card you will play two turns from now.

'''2nd Face Down Card''' -> '''1st Face Down Card''' -> '''FACE UP CARD'''

You may look at facedown cards on your Launch Track whenever you want. You cannot change the order, or discard cards. Once you play a card to your Launch Track it is locked in!

Your Launch Track may only have delivery systems, warheads, and propaganda cards on it. If you ever reveal a card that is not a delivery system, warhead, or propaganda card, it is discarded without effect. This counts as your turn!

If your launch track is ever empty you must fill it immediately, if you don’t have enough eligible cards in your hand you must fill it on your next turn during the Play a Card step

== Card Types ==

=== Propagandas ===

During Peacetime, propaganda cards are used to steal population from other players (ie, the population defects to your nation). During Wartime, some propaganda cards allow you to draw new cards from the deck.

Whenever you steal population with a propaganda card, if the player doesn’t have enough population to give you, they give all their remaining population, and then they are eliminated from the game.

=== Delivery Systems ===

In order to launch a warhead in Nuclear Destruction, you need to have an appropriate delivery system.

Delivery systems are played in your launch track before a warhead. To launch a warhead, first, you must reveal a delivery system, and in the subsequent turn, reveal a warhead to go with that delivery system. If any card follows a delivery system that isn’t compatible with that delivery system, the delivery system will be discarded.

There are two main types of delivery systems: bombers and missiles. The two types of delivery systems work slightly differently when they are launched. For resolving a launch, see the Attacking the Enemy section.

The '''evasion rating''' on delivery systems determines how vulnerable they are to Anti-Missile cards. The Evasion rating has a letter, either M(Missile) or B(Bomber), and a number. See Anti-Missile cards (below) for details on evading a launch.

'''NOTE:''' If you shoot down a delivery system with an anti-missile, you play next, skipping all the players between.

==== Missiles ====

Missile delivery systems can carry one warhead up to a maximum megatonnage listed on the card.

'''''Example:''' An East Wind-DS31 Missile may carry a single warhead of up to 25 Megatons.''

Launching a missile requires playing the missile, and on the next turn, following it with a warhead of an appropriate size. After launching a missile it, and the warhead it carried, are discarded.

==== Bombers ====

Bombers are launched just like missiles: you reveal one and on the next turn reveal a warhead with low enough tonnage to be carried by it. Unlike missiles, a bomber is not discarded after delivering a payload. Instead, a bomber may deliver multiple warheads, each on its own turn, until the total megatonnage of war-heads delivered equals the bomber rating.

Bombers may bomb different enemy powers on different turns, flying over to the offending country. You do not discard a warhead delivered by a bomber. Instead, place the warhead under the bomber with its megatonnage showing so you can keep track of the megatonnage that the bomber has used. You only discard the warheads delivered by a bomber when the bomber is discarded. If you reveal a warhead that doesn’t fit the bomber, the warhead, the bomber, and all warheads under the bomber, are immediately discarded.

'''''Example:''' On The first turn, Ed launches the B-58 Bomber, which carries up to 60 mega-tons of warheads. On the next turn, Ed reveals a 20-megaton warhead. After resolving the strike, the 20-megaton warhead is kept with the B-58 Bomber. On the following turn, Ed reveals a 10-megaton warhead, this again is stacked with the bomber after resolving. In the next turn Ed reveals a 40-megaton warhead, this exceeds the bombers max-imum tonnage, and so the bomber along with all three warheads are discarded. The 40-megaton warhead would have no effect.''

=== Warheads ===

Warhead cards are played after a delivery system on the launch track. Warhead cards are rated by megatonnage, and how much population they destroy. The megatonnage is a limit to certain delivery systems, A larger megaton warhead that follows a delivery system not capable of carrying it is discarded along with the delivery system without effect. If the warhead fits on the delivery system played before it, the warhead has successfully launched and can target any other player. See Attacking a Player.

=== Anti Missiles ===

Anti-Missiles are reactive cards. They are played directly out of your hand when another player targets you with a warhead. When a delivery system targets you, you may discard an anti-missile to shoot down the delivery system. All anti-missiles are rated for what they will shoot down. Anti-Missiles have two ratings, one for Bombers (B) and one for Missiles (M). If the rating of the anti-missile is equal to or higher than the evasion rating of the incoming delivery system, the anti-missile can shoot it down.

If you cannot shoot down the incoming delivery system, you may not play an anti-missile. You may not use an anti-missile to help another player. You may only shoot down delivery systems targeting you.

When you successfully use an anti-missile, it becomes your turn, skipping all other players. Play continues clockwise after you have finished your turn.

=== Secrets and Top Secrets ===

Secrets are resolved, one at a time, when drawn, and do not go through the launch track. When drawn, announce you have a secret, as it may be stolen by a Spy. If it isn't stolen, play it. Each secret is a random event that has an effect on the game. Resolve the text, and then draw a replacement card. If the replacement is also a secret, resolve that one, and draw another replacement, continue to resolve secrets until a non-secret is drawn. If you have more than one secret in your hand, you choose which secret or top secret to resolve first. Top Secrets are resolved the same way as secrets, with the exception you have to announce it is a Top Secret. Top Secrets tend to be more powerful.

'''SECRETS!''' Secrets can be good or bad. When you draw a secret it is played before you begin your turn. Remember to give your opponents a chance to steal it before revealing the secret and resolving it!

=== Specials ===

Special cards are cards that are played out of your hand. Each Special explains when it may be played and what it does when you play it.

=== Hybrid Cards ===

Hybrid cards show both a warhead and a delivery system. When a hybrid card is revealed the revealing player decides which option to use. After choosing which option, the card is considered to be that type until discarded.

== Game Turn in Detail ==

=== Draw Cards ===

At the start of your turn, draw cards until you have 8 cards in hand.

If you have a secret in your hand you must announce you have a secret, and if no Spy steals it, then read it aloud and resolve the effects of the secret. If you draw more than one secret, you must play all of them, but you choose the order you play them. Whenever you play a secret or have it stolen from you, you draw a replacement card.

=== Play a Card ===

After drawing, slide your cards along the launch track pushing the first face-down card to the face-up card space, and the second face-down card to the first face-down card space. After sliding your cards over, place another card from your hand, face-down, onto the second face-down space.

=== Reveal a Card ===

Reveal and resolve the card in the face-up space. If the card is a propaganda card use the appropriate effect depending on whether it is Peacetime or War.

If it is a delivery system, place it in your active delivery system space, discarding any delivery system already there.

If it is a warhead, and there is a delivery system in your active delivery system space that can hold the warhead, congratulations, you’ve launched a nuke! Place the warhead on the active delivery system and Attack an Enemy! If the game state is Peacetime, it is now War!

If you did not launch a nuke, the next player in turn order takes their turn starting from step 1. If you did, once the attack is resolved – as long as no anti-missiles change whose turn it is – the next player in turn order takes their turn starting from step 1.

=== Attacking the Enemy ===

If you have launched a warhead, choose a target player. Then follow the steps below to resolve the strike:

# The target may use an anti-missile or a Saboteur to shoot down the delivery system or foil the launch. If they do, discard your delivery system and any of your warhead(s) that are face-up.
# If a launch is stopped by an anti-missile (not a Saboteur) the player that used the anti-missile immediately takes their turn, skipping all the players between the launching player and the target.
# If the target does not stop the attack, spin the spinner to find out the extra effects of the nuclear strike.
# You may roll the Nuclear Escalation die. If you do, add the amount rolled to the total population loss. If a Nuclear Cloud is rolled, roll on the malfunction chart.

The target then discards the amount of population equal to the damage dealt by the warhead. The target player may make change from unused population cards if needed. If the target does not have enough population, they are eliminated and they may make a final strike!

'''''Example:''' Trent takes 22 Million damage from a warhead, and discards a 25 Million population card, taking a 2 million and a 1 million population card from the unused population cards.''

# If the delivery system is a missile, discard the missile and warhead. If it is a bomber, only discard the bomber and warhead(s) if the total megatonnage of warheads on the bomber equals or exceeds its maximum tonnage.

==== Spinner Results ====

'''Radioactive Beta Rays Kill another 5 million.''' Add 5 million to the population loss on the warhead.

'''An additional 1 million are engulfed in the fireball.''' Add 1 million to the population loss on the warhead.

'''Dirty Bomb! Double the Yield.''' Double the population loss listed on the warhead. If the warhead is a 200 megaton warhead or larger, the world blows up, spreading nuclear fallout throughout the solar system and everyone loses. Smooth move!

'''No Appreciable Radiation Fallout.''' No extra effect, use the amount of population loss listed on the warhead.

'''Explodes a Nuclear Stockpile Triple the Yield.''' Triple the population loss listed on the warhead. If the warhead is 100 Megatons or more the world blows up in a massive chain reaction, spreading radioactive fallout throughout the solar system and everyone loses! Welcome to the new asteroid belt.

'''Bomb Shelters Save 2 Million.''' Reduce the amount of population loss by 2 million on the warhead. If this results in less than zero loss, treat it as a zero loss.

'''Lethal Doses of Radioactive Gamma Rays Kill Another 10 Million.''' Add 10 million to the population loss on the warhead.

'''Dud Warhead! (No Effect).''' Place the warhead on the delivery system without effect. Your attack ends, it is now the next player’s turn.

'''Radioactive Fallout Kills Another 2 Million.''' Add 2 Million to the population loss on the warhead.

'''Missile Booster Explodes on Launch (or Bomber Runs Out of Fuel)''' Discard the delivery system and the warhead(s). Your attack ends, it is now the next player’s turn.

==== Nuclear Escalation Die Roll Results ====

'''Cloud: Disaster!''' You have somehow directed this warhead at one of your own cities. You lose the population rather than your target.

'''2: Orbital Burst!''' The warhead goes off in the atmosphere over your country! Discard your delivery system and all face-up warheads on your player mat. You skip your next turn!

'''3: Missile Booster Explodes on Launch''' (or a Bomber Runs out of fuel) Discard the Delivery system and the warhead(s). Your attack ends and it is now the next player's turn.

'''4: This Warhead is a dud.''' Place the warhead on its delivery system without effect. Your attack ends and it is the next player's turn.

'''5: Neutron Bomb! Double the yield.''' Double the population loss listed on the warhead.

'''6: You hit a nuclear power plant.''' You do double damage, and your opponent misses one turn! Double the population loss listed on the warhead. Remind your opponent to skip their next turn.

=== Player Elimination and Final Strike ===

If you lose all of your population, you have been eliminated from the game.

If you’ve been eliminated through propaganda, you are out of the game, and the other players continue playing the game until there is a winner, or everyone loses.

If you are eliminated through any other means (i.e. secrets, or nuclear attack) you have the option to launch a final strike. You may play all the cards in your hand and on your launch mat. Combining any eligible warhead with your delivery systems in any way you wish. Once you have combined all of your eligible delivery systems and warheads, you may launch them at any targets you wish. Resolve them one at a time, just as above.

Anti-missiles will shoot down a final strike target, but it will not stop the rest of your final strike. The same is true for any dud or failed launch from the spinner.

The player to last play an anti-missile during the final strike will become the next player, otherwise, play continues clockwise. The exception is if another player is eliminated during a final strike, in which case they perform their final strike immediately after the first final strike is finished.

It is possible that a chain reaction of final strikes will '''eliminate all''' remaining players. If this happens, everyone loses the game, just like a real nuclear war! Once a player is eliminated and has played their final strike, it becomes Peacetime.

'''''Example:''' Trent has been eliminated and is planning out his final strike. He has 3 missiles and a bomber loaded with megatonnage. He looses his bomber on Brittany, who had eliminated him, but Brittany shoots it down with an anti-missile. Trent sighs and decides to send the rest of his missiles against Ed. Ed is eliminated and immediately begins his final strike, ignoring Brittanyâ€™s use of the anti-missile. If everyone left survives Ed's final strike, then Brittany will begin her turn, unless another player had played an anti-missile.''

==== When Peace is Declared... ====

When it becomes Peacetime, you may pick up all your cards on the launch track and replace them with cards from your hand.

==== Winning the Ultimate Victory ====

If, after all final strikes, you are the only remaining player with population, You have “won” the game! Your remaining population will enjoy the nuclear winter that follows and begin to slowly rebuild civilization.

=== Deterrent Force ===

If you have a powerful weapon in your hand you may wish to display it in order to discourage an enemy attack. You may, as part of your turn, place one or two cards face up in the deterrent force area as shown on the launch mat. A Saturn missile and a 100-megaton warhead, for example, may cause an enemy to think twice before beginning a nuclear exchange.

Cards in your deterrent force area remain part of your hand and must be put into play in the same way as any other cards. Any specials or secrets that affect your hand also affect any cards in the deterrent force. You should pick up your deterrents before resolving a secret that affects your hand.

== Optional Rules ==

=== Use Escalation Die ===

The Escalation Die may be optionally rolled for all attacks.

=== Track Revealed Population ===

The game automatically tracks which population cards for each player have been revealed (such as by being taken from other players or received from the population bank as change), giving their opponents an idea of what their population might be.

=== More people! ===

Before dealing starting populations, give each player one 25 million population card. Then deal one less population card to all the players.

=== All Propaganda cards allow discarding in War ===

No matter which card sets you use, all Propaganda cards may be played during war to draw and then discard 2 cards.

=== Not so secretive! ===

If a player has more than two secrets dealt to them at the beginning, randomly choose two of them, return the rest to the bottom of the deck and draw replacements. If more secrets are drawn they are also put at the bottom of the deck and replaced.

=== Bombers aren’t quite as fast as Missiles! ===

When launching a Bomber you must target a player sitting next to you. After targeting that player you may fly to the player sitting next to the current target or stay on the current target with the next warhead the bomber carries. During a Final Strike, a bomber must target only one player.

=== Everyone loses if everyone dies! ===

This is the normal way to play Nuclear War and is recommended, but if you're playing tournaments then you can turn this off so that players are ranked by how long they last.

== Card Sets ==

You may choose which Nuclear War card sets to use from the many expansions that have been released over the years. Here's a quick overview.

=== Nuclear War Cards ===

Just the basics. Propaganda, Missiles, Bombers, Warheads, a few Secrets and Spies. Nothing fancy.

=== Nuclear Escalation ===

More basics plus the likes of Space Platforms (deploy missiles to space and drop them on your opponents from there), Killer Satellites (the natural enemy of the Space Platform), MX Missiles (splits large warheads into smaller ones), Cruise Missiles (a missile with a built-in warhead that flies around the board until it drops) and Saboteurs (who can sabotage any launch).

=== Nuclear Proliferation ===

More basics plus Stealth Bombers (play straight from your hand after revealing a warhead as your Face Up Card), Stealth Fighters (the natural enemy of the Stealth Bomber), Atomic Cannons (deploy once for a permanent 10 megaton delivery system against a neighbor), Submarines (allows you to load warheads straight from your hand), Space Shuttles (a bomber that can be used to restock a Space Platform), and Saboteurs (who can sabotage any launch).

=== Nuclear Destruction ===

More basics with great variety of megatonnage. Plenty of Hybrid cards and Propaganda cards that will let you draw and discard during Wartime.

=== Booster Pack ===

An add-on pack with some new numbers for Propaganda cards and warheads (including the 200 megaton warhead). Dirty warheads (spin twice), Shipboard missiles (play straight from your hand after revealing a warhead as your Face Up Card), DCX-Delta Clippers (a bomber that you can keep after using). When the Booster Pack is used, only some of the cards are randomly added to your deck.

Gamehelpnuclearwar

2026-03-16T00:40:34Z

BaronFraser: /* Optional Rules */

Gamehelpnuclearwar

2026-03-16T00:28:48Z

BaronFraser: /* Components Overview */

== Introduction ==

The atomic bomb has been invented. Nations are building up their stockpiles of atomic bombs while vying for the hearts and minds of their rivals’ populace. Welcome to the world of Nuclear War!

The game begins with an uneasy cold war between all the players, each representing a nuclear power. Once the first player launches a nuclear warhead, the war turns hot as populations decrease in huge balls of nuclear fire. Will there be any nation left when the last bomb has fallen?

== Object ==

In Nuclear War players seek world domination by eliminating the other major powers. This can be accomplished in two ways:

* The peaceful way is to persuade the populations of opposing countries to join your superior form of government through the use of propaganda cards.
* The warlike way is to destroy the enemy’s population by using nuclear weapons.

Population is the measure of success or failure in the game. A player who loses their entire population is eliminated. The last player with population wins the game, but sometimes everyone is engulfed in flames and there are only losers.

== Set Up ==

# Shuffle the population cards. Based on the player count, deal each player the following number of cards: 2 players: 15 cards; 3 players: 10 cards; 4 players: 8 cards; 5 players: 7 cards; 6+ players: 6 cards. Deal these cards face down. Only you may look at your population cards.
# Place the remaining population cards in a face up stack in the middle of the table forming a bank. Players may use the bank to make ‘change’ only when they are forced to lose population.
# Shuffle the Nuclear War cards and deal 9 face-down to each player. You may examine your cards but not other player’s.
# Place the remaining Nuclear War cards in a face-down stack in the middle of the table. This is a draw deck.
# The first player is randomly chosen. Play will proceed clockwise around the table from the first player.
# The first player examines their cards for any secrets and top secrets. If they have any, they play them. Once the first player has a hand with no secrets, the next player in turn declares and plays secrets. Continue this around the table until no one has any secrets left!

'''NOTE''': '''Spies!''' To play a '''secret''' you announce that you have a secret, then give each other player a moment to decide if they want to play a spy. If no one plays a '''spy''', reveal and resolve the secret. Repeat this process every time you play a secret.

7: All players, at the same time, choose and place 1 card facedown in each of the two face-down slots on their playmat. These are the cards that will be played on your first and second turn respectively!
8: Now you are ready to play! The first player takes the first turn.

== Overview of Gameplay ==

On your turn you will:

* Draw cards until you have 8 in your hand.
* Play secrets and draw replacement cards until no secrets are in hand.
* Move the cards on your launch track forward to the next box
* Place a card into the 2nd face-down slot
* Reveal the card in the face-up slot and play it.

== War and Peace ==

Nuclear War has two game states - '''Peacetime''' and '''War'''. The game state affects how some cards work.

The game starts in Peacetime. Once there is a successful launch of a delivery system with a warhead, whether or not the launch results in population loss, the game state changes to War.

The game state remains in War until one player is eliminated and has performed their final strike (see page 7). At that point, Peacetime begins again… until the next warhead is launched.

Whenever Peacetime begins all players pick up the face-down cards on their launch track (see below). They then replace those cards with any cards from their hand, including the cards they just picked up. Active delivery systems remain active.

== Launch Track ==

In Nuclear War, you must plan your moves two turns in advance using the Launch Track.

Your Launch track is three spaces. The face-up space is for the card you are using this turn. The first face-down card is the card you will use next turn, and the second face-down space is the card you will play two turns from now.

'''2nd Face Down Card''' -> '''1st Face Down Card''' -> '''FACE UP CARD'''

You may look at facedown cards on your Launch Track whenever you want. You cannot change the order, or discard cards. Once you play a card to your Launch Track it is locked in!

Your Launch Track may only have delivery systems, warheads, and propaganda cards on it. If you ever reveal a card that is not a delivery system, warhead, or propaganda card, it is discarded without effect. This counts as your turn!

If your launch track is ever empty you must fill it immediately, if you don’t have enough eligible cards in your hand you must fill it on your next turn during the Play a Card step

== Card Types ==

=== Propagandas ===

During Peacetime, propaganda cards are used to steal population from other players (ie, the population defects to your nation). During Wartime, some propaganda cards allow you to draw new cards from the deck.

Whenever you steal population with a propaganda card, if the player doesn’t have enough population to give you, they give all their remaining population, and then they are eliminated from the game.

=== Delivery Systems ===

In order to launch a warhead in Nuclear Destruction, you need to have an appropriate delivery system.

Delivery systems are played in your launch track before a warhead. To launch a warhead, first, you must reveal a delivery system, and in the subsequent turn, reveal a warhead to go with that delivery system. If any card follows a delivery system that isn’t compatible with that delivery system, the delivery system will be discarded.

There are two main types of delivery systems: bombers and missiles. The two types of delivery systems work slightly differently when they are launched. For resolving a launch, see the Attacking the Enemy section.

The '''evasion rating''' on delivery systems determines how vulnerable they are to Anti-Missile cards. The Evasion rating has a letter, either M(Missile) or B(Bomber), and a number. See Anti-Missile cards (below) for details on evading a launch.

'''NOTE:''' If you shoot down a delivery system with an anti-missile, you play next, skipping all the players between.

==== Missiles ====

Missile delivery systems can carry one warhead up to a maximum megatonnage listed on the card.

'''''Example:''' An East Wind-DS31 Missile may carry a single warhead of up to 25 Megatons.''

Launching a missile requires playing the missile, and on the next turn, following it with a warhead of an appropriate size. After launching a missile it, and the warhead it carried, are discarded.

==== Bombers ====

Bombers are launched just like missiles: you reveal one and on the next turn reveal a warhead with low enough tonnage to be carried by it. Unlike missiles, a bomber is not discarded after delivering a payload. Instead, a bomber may deliver multiple warheads, each on its own turn, until the total megatonnage of war-heads delivered equals the bomber rating.

Bombers may bomb different enemy powers on different turns, flying over to the offending country. You do not discard a warhead delivered by a bomber. Instead, place the warhead under the bomber with its megatonnage showing so you can keep track of the megatonnage that the bomber has used. You only discard the warheads delivered by a bomber when the bomber is discarded. If you reveal a warhead that doesn’t fit the bomber, the warhead, the bomber, and all warheads under the bomber, are immediately discarded.

'''''Example:''' On The first turn, Ed launches the B-58 Bomber, which carries up to 60 mega-tons of warheads. On the next turn, Ed reveals a 20-megaton warhead. After resolving the strike, the 20-megaton warhead is kept with the B-58 Bomber. On the following turn, Ed reveals a 10-megaton warhead, this again is stacked with the bomber after resolving. In the next turn Ed reveals a 40-megaton warhead, this exceeds the bombers max-imum tonnage, and so the bomber along with all three warheads are discarded. The 40-megaton warhead would have no effect.''

=== Warheads ===

Warhead cards are played after a delivery system on the launch track. Warhead cards are rated by megatonnage, and how much population they destroy. The megatonnage is a limit to certain delivery systems, A larger megaton warhead that follows a delivery system not capable of carrying it is discarded along with the delivery system without effect. If the warhead fits on the delivery system played before it, the warhead has successfully launched and can target any other player. See Attacking a Player.

=== Anti Missiles ===

Anti-Missiles are reactive cards. They are played directly out of your hand when another player targets you with a warhead. When a delivery system targets you, you may discard an anti-missile to shoot down the delivery system. All anti-missiles are rated for what they will shoot down. Anti-Missiles have two ratings, one for Bombers (B) and one for Missiles (M). If the rating of the anti-missile is equal to or higher than the evasion rating of the incoming delivery system, the anti-missile can shoot it down.

If you cannot shoot down the incoming delivery system, you may not play an anti-missile. You may not use an anti-missile to help another player. You may only shoot down delivery systems targeting you.

When you successfully use an anti-missile, it becomes your turn, skipping all other players. Play continues clockwise after you have finished your turn.

=== Secrets and Top Secrets ===

Secrets are resolved, one at a time, when drawn, and do not go through the launch track. When drawn, announce you have a secret, as it may be stolen by a Spy. If it isn't stolen, play it. Each secret is a random event that has an effect on the game. Resolve the text, and then draw a replacement card. If the replacement is also a secret, resolve that one, and draw another replacement, continue to resolve secrets until a non-secret is drawn. If you have more than one secret in your hand, you choose which secret or top secret to resolve first. Top Secrets are resolved the same way as secrets, with the exception you have to announce it is a Top Secret. Top Secrets tend to be more powerful.

'''SECRETS!''' Secrets can be good or bad. When you draw a secret it is played before you begin your turn. Remember to give your opponents a chance to steal it before revealing the secret and resolving it!

=== Specials ===

Special cards are cards that are played out of your hand. Each Special explains when it may be played and what it does when you play it.

=== Hybrid Cards ===

Hybrid cards show both a warhead and a delivery system. When a hybrid card is revealed the revealing player decides which option to use. After choosing which option, the card is considered to be that type until discarded.

== Game Turn in Detail ==

=== Draw Cards ===

At the start of your turn, draw cards until you have 8 cards in hand.

If you have a secret in your hand you must announce you have a secret, and if no Spy steals it, then read it aloud and resolve the effects of the secret. If you draw more than one secret, you must play all of them, but you choose the order you play them. Whenever you play a secret or have it stolen from you, you draw a replacement card.

=== Play a Card ===

After drawing, slide your cards along the launch track pushing the first face-down card to the face-up card space, and the second face-down card to the first face-down card space. After sliding your cards over, place another card from your hand, face-down, onto the second face-down space.

=== Reveal a Card ===

Reveal and resolve the card in the face-up space. If the card is a propaganda card use the appropriate effect depending on whether it is Peacetime or War.

If it is a delivery system, place it in your active delivery system space, discarding any delivery system already there.

If it is a warhead, and there is a delivery system in your active delivery system space that can hold the warhead, congratulations, you’ve launched a nuke! Place the warhead on the active delivery system and Attack an Enemy! If the game state is Peacetime, it is now War!

If you did not launch a nuke, the next player in turn order takes their turn starting from step 1. If you did, once the attack is resolved – as long as no anti-missiles change whose turn it is – the next player in turn order takes their turn starting from step 1.

=== Attacking the Enemy ===

If you have launched a warhead, choose a target player. Then follow the steps below to resolve the strike:

# The target may use an anti-missile or a Saboteur to shoot down the delivery system or foil the launch. If they do, discard your delivery system and any of your warhead(s) that are face-up.
# If a launch is stopped by an anti-missile (not a Saboteur) the player that used the anti-missile immediately takes their turn, skipping all the players between the launching player and the target.
# If the target does not stop the attack, spin the spinner to find out the extra effects of the nuclear strike.
# You may roll the Nuclear Escalation die. If you do, add the amount rolled to the total population loss. If a Nuclear Cloud is rolled, roll on the malfunction chart.

The target then discards the amount of population equal to the damage dealt by the warhead. The target player may make change from unused population cards if needed. If the target does not have enough population, they are eliminated and they may make a final strike!

'''''Example:''' Trent takes 22 Million damage from a warhead, and discards a 25 Million population card, taking a 2 million and a 1 million population card from the unused population cards.''

# If the delivery system is a missile, discard the missile and warhead. If it is a bomber, only discard the bomber and warhead(s) if the total megatonnage of warheads on the bomber equals or exceeds its maximum tonnage.

==== Spinner Results ====

'''Radioactive Beta Rays Kill another 5 million.''' Add 5 million to the population loss on the warhead.

'''An additional 1 million are engulfed in the fireball.''' Add 1 million to the population loss on the warhead.

'''Dirty Bomb! Double the Yield.''' Double the population loss listed on the warhead. If the warhead is a 200 megaton warhead or larger, the world blows up, spreading nuclear fallout throughout the solar system and everyone loses. Smooth move!

'''No Appreciable Radiation Fallout.''' No extra effect, use the amount of population loss listed on the warhead.

'''Explodes a Nuclear Stockpile Triple the Yield.''' Triple the population loss listed on the warhead. If the warhead is 100 Megatons or more the world blows up in a massive chain reaction, spreading radioactive fallout throughout the solar system and everyone loses! Welcome to the new asteroid belt.

'''Bomb Shelters Save 2 Million.''' Reduce the amount of population loss by 2 million on the warhead. If this results in less than zero loss, treat it as a zero loss.

'''Lethal Doses of Radioactive Gamma Rays Kill Another 10 Million.''' Add 10 million to the population loss on the warhead.

'''Dud Warhead! (No Effect).''' Place the warhead on the delivery system without effect. Your attack ends, it is now the next player’s turn.

'''Radioactive Fallout Kills Another 2 Million.''' Add 2 Million to the population loss on the warhead.

'''Missile Booster Explodes on Launch (or Bomber Runs Out of Fuel)''' Discard the delivery system and the warhead(s). Your attack ends, it is now the next player’s turn.

==== Nuclear Escalation Die Roll Results ====

'''Cloud: Disaster!''' You have somehow directed this warhead at one of your own cities. You lose the population rather than your target.

'''2: Orbital Burst!''' The warhead goes off in the atmosphere over your country! Discard your delivery system and all face-up warheads on your player mat. You skip your next turn!

'''3: Missile Booster Explodes on Launch''' (or a Bomber Runs out of fuel) Discard the Delivery system and the warhead(s). Your attack ends and it is now the next player's turn.

'''4: This Warhead is a dud.''' Place the warhead on its delivery system without effect. Your attack ends and it is the next player's turn.

'''5: Neutron Bomb! Double the yield.''' Double the population loss listed on the warhead.

'''6: You hit a nuclear power plant.''' You do double damage, and your opponent misses one turn! Double the population loss listed on the warhead. Remind your opponent to skip their next turn.

=== Player Elimination and Final Strike ===

If you lose all of your population, you have been eliminated from the game.

If you’ve been eliminated through propaganda, you are out of the game, and the other players continue playing the game until there is a winner, or everyone loses.

If you are eliminated through any other means (i.e. secrets, or nuclear attack) you have the option to launch a final strike. You may play all the cards in your hand and on your launch mat. Combining any eligible warhead with your delivery systems in any way you wish. Once you have combined all of your eligible delivery systems and warheads, you may launch them at any targets you wish. Resolve them one at a time, just as above.

Anti-missiles will shoot down a final strike target, but it will not stop the rest of your final strike. The same is true for any dud or failed launch from the spinner.

The player to last play an anti-missile during the final strike will become the next player, otherwise, play continues clockwise. The exception is if another player is eliminated during a final strike, in which case they perform their final strike immediately after the first final strike is finished.

It is possible that a chain reaction of final strikes will '''eliminate all''' remaining players. If this happens, everyone loses the game, just like a real nuclear war! Once a player is eliminated and has played their final strike, it becomes Peacetime.

'''''Example:''' Trent has been eliminated and is planning out his final strike. He has 3 missiles and a bomber loaded with megatonnage. He looses his bomber on Brittany, who had eliminated him, but Brittany shoots it down with an anti-missile. Trent sighs and decides to send the rest of his missiles against Ed. Ed is eliminated and immediately begins his final strike, ignoring Brittanyâ€™s use of the anti-missile. If everyone left survives Ed's final strike, then Brittany will begin her turn, unless another player had played an anti-missile.''

==== When Peace is Declared... ====

When it becomes Peacetime, you may pick up all your cards on the launch track and replace them with cards from your hand.

==== Winning the Ultimate Victory ====

If, after all final strikes, you are the only remaining player with population, You have “won” the game! Your remaining population will enjoy the nuclear winter that follows and begin to slowly rebuild civilization.

=== Deterrent Force ===

If you have a powerful weapon in your hand you may wish to display it in order to discourage an enemy attack. You may, as part of your turn, place one or two cards face up in the deterrent force area as shown on the launch mat. A Saturn missile and a 100-megaton warhead, for example, may cause an enemy to think twice before beginning a nuclear exchange.

Cards in your deterrent force area remain part of your hand and must be put into play in the same way as any other cards. Any specials or secrets that affect your hand also affect any cards in the deterrent force. You should pick up your deterrents before resolving a secret that affects your hand.

== Optional Rules ==

=== More people! ===

Before dealing starting populations, give each player one 25 million population card. Then deal one less population card to all the players.

=== Not so secretive! ===

If a player has more than two secrets dealt to them at the beginning, randomly choose two of them, return the rest to the bottom of the deck and draw replacements. If more secrets are drawn they are also put at the bottom of the deck and replaced.

=== Bombers aren’t quite as fast as Missiles! ===

When launching a Bomber you must target a player sitting next to you. After targeting that player you may fly to the player sitting next to the current target or stay on the current target with the next warhead the bomber carries. During a Final Strike, a bomber must target only one player.

Gamehelpnuclearwar

2026-03-16T00:27:53Z

BaronFraser: /* Winning the Ultimate Victory */

== Introduction ==

The atomic bomb has been invented. Nations are building up their stockpiles of atomic bombs while vying for the hearts and minds of their rivals’ populace. Welcome to the world of Nuclear War!

The game begins with an uneasy cold war between all the players, each representing a nuclear power. Once the first player launches a nuclear warhead, the war turns hot as populations decrease in huge balls of nuclear fire. Will there be any nation left when the last bomb has fallen?

== Object ==

In Nuclear War players seek world domination by eliminating the other major powers. This can be accomplished in two ways:

* The peaceful way is to persuade the populations of opposing countries to join your superior form of government through the use of propaganda cards.
* The warlike way is to destroy the enemy’s population by using nuclear weapons.

Population is the measure of success or failure in the game. A player who loses their entire population is eliminated. The last player with population wins the game, but sometimes everyone is engulfed in flames and there are only losers.

== Set Up ==

# Shuffle the population cards. Based on the player count, deal each player the following number of cards: 2 players: 15 cards; 3 players: 10 cards; 4 players: 8 cards; 5 players: 7 cards; 6+ players: 6 cards. Deal these cards face down. Only you may look at your population cards.
# Place the remaining population cards in a face up stack in the middle of the table forming a bank. Players may use the bank to make ‘change’ only when they are forced to lose population.
# Shuffle the Nuclear War cards and deal 9 face-down to each player. You may examine your cards but not other player’s.
# Place the remaining Nuclear War cards in a face-down stack in the middle of the table. This is a draw deck.
# The first player is randomly chosen. Play will proceed clockwise around the table from the first player.
# The first player examines their cards for any secrets and top secrets. If they have any, they play them. Once the first player has a hand with no secrets, the next player in turn declares and plays secrets. Continue this around the table until no one has any secrets left!

'''NOTE''': '''Spies!''' To play a '''secret''' you announce that you have a secret, then give each other player a moment to decide if they want to play a spy. If no one plays a '''spy''', reveal and resolve the secret. Repeat this process every time you play a secret.

7: All players, at the same time, choose and place 1 card facedown in each of the two face-down slots on their playmat. These are the cards that will be played on your first and second turn respectively!
8: Now you are ready to play! The first player takes the first turn.

== Overview of Gameplay ==

On your turn you will:

* Draw cards until you have 8 in your hand.
* Play secrets and draw replacement cards until no secrets are in hand.
* Move the cards on your launch track forward to the next box
* Place a card into the 2nd face-down slot
* Reveal the card in the face-up slot and play it.

== War and Peace ==

Nuclear War has two game states - '''Peacetime''' and '''War'''. The game state affects how some cards work.

The game starts in Peacetime. Once there is a successful launch of a delivery system with a warhead, whether or not the launch results in population loss, the game state changes to War.

The game state remains in War until one player is eliminated and has performed their final strike (see page 7). At that point, Peacetime begins again… until the next warhead is launched.

Whenever Peacetime begins all players pick up the face-down cards on their launch track (see below). They then replace those cards with any cards from their hand, including the cards they just picked up. Active delivery systems remain active.

== Components Overview ==

=== Launch Track ===

In Nuclear War, you must plan your moves two turns in advance using the Launch Track.

Your Launch track is three spaces. The face-up space is for the card you are using this turn. The first face-down card is the card you will use next turn, and the second face-down space is the card you will play two turns from now.

'''2nd Face Down Card''' -> '''1st Face Down Card''' -> '''FACE UP CARD'''

You may look at facedown cards on your Launch Track whenever you want. You cannot change the order, or discard cards. Once you play a card to your Launch Track it is locked in!

Your Launch Track may only have delivery systems, warheads, and propaganda cards on it. If you ever reveal a card that is not a delivery system, warhead, or propaganda card, it is discarded without effect. This counts as your turn!

If your launch track is ever empty you must fill it immediately, if you don’t have enough eligible cards in your hand you must fill it on your next turn during the Play a Card step

== Card Types ==

=== Propagandas ===

During Peacetime, propaganda cards are used to steal population from other players (ie, the population defects to your nation). During Wartime, some propaganda cards allow you to draw new cards from the deck.

Whenever you steal population with a propaganda card, if the player doesn’t have enough population to give you, they give all their remaining population, and then they are eliminated from the game.

=== Delivery Systems ===

In order to launch a warhead in Nuclear Destruction, you need to have an appropriate delivery system.

Delivery systems are played in your launch track before a warhead. To launch a warhead, first, you must reveal a delivery system, and in the subsequent turn, reveal a warhead to go with that delivery system. If any card follows a delivery system that isn’t compatible with that delivery system, the delivery system will be discarded.

There are two main types of delivery systems: bombers and missiles. The two types of delivery systems work slightly differently when they are launched. For resolving a launch, see the Attacking the Enemy section.

The '''evasion rating''' on delivery systems determines how vulnerable they are to Anti-Missile cards. The Evasion rating has a letter, either M(Missile) or B(Bomber), and a number. See Anti-Missile cards (below) for details on evading a launch.

'''NOTE:''' If you shoot down a delivery system with an anti-missile, you play next, skipping all the players between.

==== Missiles ====

Missile delivery systems can carry one warhead up to a maximum megatonnage listed on the card.

'''''Example:''' An East Wind-DS31 Missile may carry a single warhead of up to 25 Megatons.''

Launching a missile requires playing the missile, and on the next turn, following it with a warhead of an appropriate size. After launching a missile it, and the warhead it carried, are discarded.

==== Bombers ====

Bombers are launched just like missiles: you reveal one and on the next turn reveal a warhead with low enough tonnage to be carried by it. Unlike missiles, a bomber is not discarded after delivering a payload. Instead, a bomber may deliver multiple warheads, each on its own turn, until the total megatonnage of war-heads delivered equals the bomber rating.

Bombers may bomb different enemy powers on different turns, flying over to the offending country. You do not discard a warhead delivered by a bomber. Instead, place the warhead under the bomber with its megatonnage showing so you can keep track of the megatonnage that the bomber has used. You only discard the warheads delivered by a bomber when the bomber is discarded. If you reveal a warhead that doesn’t fit the bomber, the warhead, the bomber, and all warheads under the bomber, are immediately discarded.

'''''Example:''' On The first turn, Ed launches the B-58 Bomber, which carries up to 60 mega-tons of warheads. On the next turn, Ed reveals a 20-megaton warhead. After resolving the strike, the 20-megaton warhead is kept with the B-58 Bomber. On the following turn, Ed reveals a 10-megaton warhead, this again is stacked with the bomber after resolving. In the next turn Ed reveals a 40-megaton warhead, this exceeds the bombers max-imum tonnage, and so the bomber along with all three warheads are discarded. The 40-megaton warhead would have no effect.''

=== Warheads ===

Warhead cards are played after a delivery system on the launch track. Warhead cards are rated by megatonnage, and how much population they destroy. The megatonnage is a limit to certain delivery systems, A larger megaton warhead that follows a delivery system not capable of carrying it is discarded along with the delivery system without effect. If the warhead fits on the delivery system played before it, the warhead has successfully launched and can target any other player. See Attacking a Player.

=== Anti Missiles ===

Anti-Missiles are reactive cards. They are played directly out of your hand when another player targets you with a warhead. When a delivery system targets you, you may discard an anti-missile to shoot down the delivery system. All anti-missiles are rated for what they will shoot down. Anti-Missiles have two ratings, one for Bombers (B) and one for Missiles (M). If the rating of the anti-missile is equal to or higher than the evasion rating of the incoming delivery system, the anti-missile can shoot it down.

If you cannot shoot down the incoming delivery system, you may not play an anti-missile. You may not use an anti-missile to help another player. You may only shoot down delivery systems targeting you.

When you successfully use an anti-missile, it becomes your turn, skipping all other players. Play continues clockwise after you have finished your turn.

=== Secrets and Top Secrets ===

Secrets are resolved, one at a time, when drawn, and do not go through the launch track. When drawn, announce you have a secret, as it may be stolen by a Spy. If it isn't stolen, play it. Each secret is a random event that has an effect on the game. Resolve the text, and then draw a replacement card. If the replacement is also a secret, resolve that one, and draw another replacement, continue to resolve secrets until a non-secret is drawn. If you have more than one secret in your hand, you choose which secret or top secret to resolve first. Top Secrets are resolved the same way as secrets, with the exception you have to announce it is a Top Secret. Top Secrets tend to be more powerful.

'''SECRETS!''' Secrets can be good or bad. When you draw a secret it is played before you begin your turn. Remember to give your opponents a chance to steal it before revealing the secret and resolving it!

=== Specials ===

Special cards are cards that are played out of your hand. Each Special explains when it may be played and what it does when you play it.

=== Hybrid Cards ===

Hybrid cards show both a warhead and a delivery system. When a hybrid card is revealed the revealing player decides which option to use. After choosing which option, the card is considered to be that type until discarded.

== Game Turn in Detail ==

=== Draw Cards ===

At the start of your turn, draw cards until you have 8 cards in hand.

If you have a secret in your hand you must announce you have a secret, and if no Spy steals it, then read it aloud and resolve the effects of the secret. If you draw more than one secret, you must play all of them, but you choose the order you play them. Whenever you play a secret or have it stolen from you, you draw a replacement card.

=== Play a Card ===

After drawing, slide your cards along the launch track pushing the first face-down card to the face-up card space, and the second face-down card to the first face-down card space. After sliding your cards over, place another card from your hand, face-down, onto the second face-down space.

=== Reveal a Card ===

Reveal and resolve the card in the face-up space. If the card is a propaganda card use the appropriate effect depending on whether it is Peacetime or War.

If it is a delivery system, place it in your active delivery system space, discarding any delivery system already there.

If it is a warhead, and there is a delivery system in your active delivery system space that can hold the warhead, congratulations, you’ve launched a nuke! Place the warhead on the active delivery system and Attack an Enemy! If the game state is Peacetime, it is now War!

If you did not launch a nuke, the next player in turn order takes their turn starting from step 1. If you did, once the attack is resolved – as long as no anti-missiles change whose turn it is – the next player in turn order takes their turn starting from step 1.

=== Attacking the Enemy ===

If you have launched a warhead, choose a target player. Then follow the steps below to resolve the strike:

# The target may use an anti-missile or a Saboteur to shoot down the delivery system or foil the launch. If they do, discard your delivery system and any of your warhead(s) that are face-up.
# If a launch is stopped by an anti-missile (not a Saboteur) the player that used the anti-missile immediately takes their turn, skipping all the players between the launching player and the target.
# If the target does not stop the attack, spin the spinner to find out the extra effects of the nuclear strike.
# You may roll the Nuclear Escalation die. If you do, add the amount rolled to the total population loss. If a Nuclear Cloud is rolled, roll on the malfunction chart.

The target then discards the amount of population equal to the damage dealt by the warhead. The target player may make change from unused population cards if needed. If the target does not have enough population, they are eliminated and they may make a final strike!

'''''Example:''' Trent takes 22 Million damage from a warhead, and discards a 25 Million population card, taking a 2 million and a 1 million population card from the unused population cards.''

# If the delivery system is a missile, discard the missile and warhead. If it is a bomber, only discard the bomber and warhead(s) if the total megatonnage of warheads on the bomber equals or exceeds its maximum tonnage.

==== Spinner Results ====

'''Radioactive Beta Rays Kill another 5 million.''' Add 5 million to the population loss on the warhead.

'''An additional 1 million are engulfed in the fireball.''' Add 1 million to the population loss on the warhead.

'''Dirty Bomb! Double the Yield.''' Double the population loss listed on the warhead. If the warhead is a 200 megaton warhead or larger, the world blows up, spreading nuclear fallout throughout the solar system and everyone loses. Smooth move!

'''No Appreciable Radiation Fallout.''' No extra effect, use the amount of population loss listed on the warhead.

'''Explodes a Nuclear Stockpile Triple the Yield.''' Triple the population loss listed on the warhead. If the warhead is 100 Megatons or more the world blows up in a massive chain reaction, spreading radioactive fallout throughout the solar system and everyone loses! Welcome to the new asteroid belt.

'''Bomb Shelters Save 2 Million.''' Reduce the amount of population loss by 2 million on the warhead. If this results in less than zero loss, treat it as a zero loss.

'''Lethal Doses of Radioactive Gamma Rays Kill Another 10 Million.''' Add 10 million to the population loss on the warhead.

'''Dud Warhead! (No Effect).''' Place the warhead on the delivery system without effect. Your attack ends, it is now the next player’s turn.

'''Radioactive Fallout Kills Another 2 Million.''' Add 2 Million to the population loss on the warhead.

'''Missile Booster Explodes on Launch (or Bomber Runs Out of Fuel)''' Discard the delivery system and the warhead(s). Your attack ends, it is now the next player’s turn.

==== Nuclear Escalation Die Roll Results ====

'''Cloud: Disaster!''' You have somehow directed this warhead at one of your own cities. You lose the population rather than your target.

'''2: Orbital Burst!''' The warhead goes off in the atmosphere over your country! Discard your delivery system and all face-up warheads on your player mat. You skip your next turn!

'''3: Missile Booster Explodes on Launch''' (or a Bomber Runs out of fuel) Discard the Delivery system and the warhead(s). Your attack ends and it is now the next player's turn.

'''4: This Warhead is a dud.''' Place the warhead on its delivery system without effect. Your attack ends and it is the next player's turn.

'''5: Neutron Bomb! Double the yield.''' Double the population loss listed on the warhead.

'''6: You hit a nuclear power plant.''' You do double damage, and your opponent misses one turn! Double the population loss listed on the warhead. Remind your opponent to skip their next turn.

=== Player Elimination and Final Strike ===

If you lose all of your population, you have been eliminated from the game.

If you’ve been eliminated through propaganda, you are out of the game, and the other players continue playing the game until there is a winner, or everyone loses.

If you are eliminated through any other means (i.e. secrets, or nuclear attack) you have the option to launch a final strike. You may play all the cards in your hand and on your launch mat. Combining any eligible warhead with your delivery systems in any way you wish. Once you have combined all of your eligible delivery systems and warheads, you may launch them at any targets you wish. Resolve them one at a time, just as above.

Anti-missiles will shoot down a final strike target, but it will not stop the rest of your final strike. The same is true for any dud or failed launch from the spinner.

The player to last play an anti-missile during the final strike will become the next player, otherwise, play continues clockwise. The exception is if another player is eliminated during a final strike, in which case they perform their final strike immediately after the first final strike is finished.

It is possible that a chain reaction of final strikes will '''eliminate all''' remaining players. If this happens, everyone loses the game, just like a real nuclear war! Once a player is eliminated and has played their final strike, it becomes Peacetime.

'''''Example:''' Trent has been eliminated and is planning out his final strike. He has 3 missiles and a bomber loaded with megatonnage. He looses his bomber on Brittany, who had eliminated him, but Brittany shoots it down with an anti-missile. Trent sighs and decides to send the rest of his missiles against Ed. Ed is eliminated and immediately begins his final strike, ignoring Brittanyâ€™s use of the anti-missile. If everyone left survives Ed's final strike, then Brittany will begin her turn, unless another player had played an anti-missile.''

==== When Peace is Declared... ====

When it becomes Peacetime, you may pick up all your cards on the launch track and replace them with cards from your hand.

==== Winning the Ultimate Victory ====

If, after all final strikes, you are the only remaining player with population, You have “won” the game! Your remaining population will enjoy the nuclear winter that follows and begin to slowly rebuild civilization.

=== Deterrent Force ===

If you have a powerful weapon in your hand you may wish to display it in order to discourage an enemy attack. You may, as part of your turn, place one or two cards face up in the deterrent force area as shown on the launch mat. A Saturn missile and a 100-megaton warhead, for example, may cause an enemy to think twice before beginning a nuclear exchange.

Cards in your deterrent force area remain part of your hand and must be put into play in the same way as any other cards. Any specials or secrets that affect your hand also affect any cards in the deterrent force. You should pick up your deterrents before resolving a secret that affects your hand.

== Optional Rules ==

=== More people! ===

Before dealing starting populations, give each player one 25 million population card. Then deal one less population card to all the players.

=== Not so secretive! ===

If a player has more than two secrets dealt to them at the beginning, randomly choose two of them, return the rest to the bottom of the deck and draw replacements. If more secrets are drawn they are also put at the bottom of the deck and replaced.

=== Bombers aren’t quite as fast as Missiles! ===

When launching a Bomber you must target a player sitting next to you. After targeting that player you may fly to the player sitting next to the current target or stay on the current target with the next warhead the bomber carries. During a Final Strike, a bomber must target only one player.

Gamehelpnuclearwar

2026-03-16T00:27:01Z

BaronFraser: /* Delivery Systems */

== Introduction ==

The atomic bomb has been invented. Nations are building up their stockpiles of atomic bombs while vying for the hearts and minds of their rivals’ populace. Welcome to the world of Nuclear War!

The game begins with an uneasy cold war between all the players, each representing a nuclear power. Once the first player launches a nuclear warhead, the war turns hot as populations decrease in huge balls of nuclear fire. Will there be any nation left when the last bomb has fallen?

== Object ==

In Nuclear War players seek world domination by eliminating the other major powers. This can be accomplished in two ways:

* The peaceful way is to persuade the populations of opposing countries to join your superior form of government through the use of propaganda cards.
* The warlike way is to destroy the enemy’s population by using nuclear weapons.

Population is the measure of success or failure in the game. A player who loses their entire population is eliminated. The last player with population wins the game, but sometimes everyone is engulfed in flames and there are only losers.

== Set Up ==

# Shuffle the population cards. Based on the player count, deal each player the following number of cards: 2 players: 15 cards; 3 players: 10 cards; 4 players: 8 cards; 5 players: 7 cards; 6+ players: 6 cards. Deal these cards face down. Only you may look at your population cards.
# Place the remaining population cards in a face up stack in the middle of the table forming a bank. Players may use the bank to make ‘change’ only when they are forced to lose population.
# Shuffle the Nuclear War cards and deal 9 face-down to each player. You may examine your cards but not other player’s.
# Place the remaining Nuclear War cards in a face-down stack in the middle of the table. This is a draw deck.
# The first player is randomly chosen. Play will proceed clockwise around the table from the first player.
# The first player examines their cards for any secrets and top secrets. If they have any, they play them. Once the first player has a hand with no secrets, the next player in turn declares and plays secrets. Continue this around the table until no one has any secrets left!

'''NOTE''': '''Spies!''' To play a '''secret''' you announce that you have a secret, then give each other player a moment to decide if they want to play a spy. If no one plays a '''spy''', reveal and resolve the secret. Repeat this process every time you play a secret.

7: All players, at the same time, choose and place 1 card facedown in each of the two face-down slots on their playmat. These are the cards that will be played on your first and second turn respectively!
8: Now you are ready to play! The first player takes the first turn.

== Overview of Gameplay ==

On your turn you will:

* Draw cards until you have 8 in your hand.
* Play secrets and draw replacement cards until no secrets are in hand.
* Move the cards on your launch track forward to the next box
* Place a card into the 2nd face-down slot
* Reveal the card in the face-up slot and play it.

== War and Peace ==

Nuclear War has two game states - '''Peacetime''' and '''War'''. The game state affects how some cards work.

The game starts in Peacetime. Once there is a successful launch of a delivery system with a warhead, whether or not the launch results in population loss, the game state changes to War.

The game state remains in War until one player is eliminated and has performed their final strike (see page 7). At that point, Peacetime begins again… until the next warhead is launched.

Whenever Peacetime begins all players pick up the face-down cards on their launch track (see below). They then replace those cards with any cards from their hand, including the cards they just picked up. Active delivery systems remain active.

== Components Overview ==

=== Launch Track ===

In Nuclear War, you must plan your moves two turns in advance using the Launch Track.

Your Launch track is three spaces. The face-up space is for the card you are using this turn. The first face-down card is the card you will use next turn, and the second face-down space is the card you will play two turns from now.

'''2nd Face Down Card''' -> '''1st Face Down Card''' -> '''FACE UP CARD'''

You may look at facedown cards on your Launch Track whenever you want. You cannot change the order, or discard cards. Once you play a card to your Launch Track it is locked in!

Your Launch Track may only have delivery systems, warheads, and propaganda cards on it. If you ever reveal a card that is not a delivery system, warhead, or propaganda card, it is discarded without effect. This counts as your turn!

If your launch track is ever empty you must fill it immediately, if you don’t have enough eligible cards in your hand you must fill it on your next turn during the Play a Card step

== Card Types ==

=== Propagandas ===

During Peacetime, propaganda cards are used to steal population from other players (ie, the population defects to your nation). During Wartime, some propaganda cards allow you to draw new cards from the deck.

Whenever you steal population with a propaganda card, if the player doesn’t have enough population to give you, they give all their remaining population, and then they are eliminated from the game.

=== Delivery Systems ===

In order to launch a warhead in Nuclear Destruction, you need to have an appropriate delivery system.

Delivery systems are played in your launch track before a warhead. To launch a warhead, first, you must reveal a delivery system, and in the subsequent turn, reveal a warhead to go with that delivery system. If any card follows a delivery system that isn’t compatible with that delivery system, the delivery system will be discarded.

There are two main types of delivery systems: bombers and missiles. The two types of delivery systems work slightly differently when they are launched. For resolving a launch, see the Attacking the Enemy section.

The '''evasion rating''' on delivery systems determines how vulnerable they are to Anti-Missile cards. The Evasion rating has a letter, either M(Missile) or B(Bomber), and a number. See Anti-Missile cards (below) for details on evading a launch.

'''NOTE:''' If you shoot down a delivery system with an anti-missile, you play next, skipping all the players between.

==== Missiles ====

Missile delivery systems can carry one warhead up to a maximum megatonnage listed on the card.

'''''Example:''' An East Wind-DS31 Missile may carry a single warhead of up to 25 Megatons.''

Launching a missile requires playing the missile, and on the next turn, following it with a warhead of an appropriate size. After launching a missile it, and the warhead it carried, are discarded.

==== Bombers ====

Bombers are launched just like missiles: you reveal one and on the next turn reveal a warhead with low enough tonnage to be carried by it. Unlike missiles, a bomber is not discarded after delivering a payload. Instead, a bomber may deliver multiple warheads, each on its own turn, until the total megatonnage of war-heads delivered equals the bomber rating.

Bombers may bomb different enemy powers on different turns, flying over to the offending country. You do not discard a warhead delivered by a bomber. Instead, place the warhead under the bomber with its megatonnage showing so you can keep track of the megatonnage that the bomber has used. You only discard the warheads delivered by a bomber when the bomber is discarded. If you reveal a warhead that doesn’t fit the bomber, the warhead, the bomber, and all warheads under the bomber, are immediately discarded.

'''''Example:''' On The first turn, Ed launches the B-58 Bomber, which carries up to 60 mega-tons of warheads. On the next turn, Ed reveals a 20-megaton warhead. After resolving the strike, the 20-megaton warhead is kept with the B-58 Bomber. On the following turn, Ed reveals a 10-megaton warhead, this again is stacked with the bomber after resolving. In the next turn Ed reveals a 40-megaton warhead, this exceeds the bombers max-imum tonnage, and so the bomber along with all three warheads are discarded. The 40-megaton warhead would have no effect.''

=== Warheads ===

Warhead cards are played after a delivery system on the launch track. Warhead cards are rated by megatonnage, and how much population they destroy. The megatonnage is a limit to certain delivery systems, A larger megaton warhead that follows a delivery system not capable of carrying it is discarded along with the delivery system without effect. If the warhead fits on the delivery system played before it, the warhead has successfully launched and can target any other player. See Attacking a Player.

=== Anti Missiles ===

Anti-Missiles are reactive cards. They are played directly out of your hand when another player targets you with a warhead. When a delivery system targets you, you may discard an anti-missile to shoot down the delivery system. All anti-missiles are rated for what they will shoot down. Anti-Missiles have two ratings, one for Bombers (B) and one for Missiles (M). If the rating of the anti-missile is equal to or higher than the evasion rating of the incoming delivery system, the anti-missile can shoot it down.

If you cannot shoot down the incoming delivery system, you may not play an anti-missile. You may not use an anti-missile to help another player. You may only shoot down delivery systems targeting you.

When you successfully use an anti-missile, it becomes your turn, skipping all other players. Play continues clockwise after you have finished your turn.

=== Secrets and Top Secrets ===

Secrets are resolved, one at a time, when drawn, and do not go through the launch track. When drawn, announce you have a secret, as it may be stolen by a Spy. If it isn't stolen, play it. Each secret is a random event that has an effect on the game. Resolve the text, and then draw a replacement card. If the replacement is also a secret, resolve that one, and draw another replacement, continue to resolve secrets until a non-secret is drawn. If you have more than one secret in your hand, you choose which secret or top secret to resolve first. Top Secrets are resolved the same way as secrets, with the exception you have to announce it is a Top Secret. Top Secrets tend to be more powerful.

'''SECRETS!''' Secrets can be good or bad. When you draw a secret it is played before you begin your turn. Remember to give your opponents a chance to steal it before revealing the secret and resolving it!

=== Specials ===

Special cards are cards that are played out of your hand. Each Special explains when it may be played and what it does when you play it.

=== Hybrid Cards ===

Hybrid cards show both a warhead and a delivery system. When a hybrid card is revealed the revealing player decides which option to use. After choosing which option, the card is considered to be that type until discarded.

== Game Turn in Detail ==

=== Draw Cards ===

At the start of your turn, draw cards until you have 8 cards in hand.

If you have a secret in your hand you must announce you have a secret, and if no Spy steals it, then read it aloud and resolve the effects of the secret. If you draw more than one secret, you must play all of them, but you choose the order you play them. Whenever you play a secret or have it stolen from you, you draw a replacement card.

=== Play a Card ===

After drawing, slide your cards along the launch track pushing the first face-down card to the face-up card space, and the second face-down card to the first face-down card space. After sliding your cards over, place another card from your hand, face-down, onto the second face-down space.

=== Reveal a Card ===

Reveal and resolve the card in the face-up space. If the card is a propaganda card use the appropriate effect depending on whether it is Peacetime or War.

If it is a delivery system, place it in your active delivery system space, discarding any delivery system already there.

If it is a warhead, and there is a delivery system in your active delivery system space that can hold the warhead, congratulations, you’ve launched a nuke! Place the warhead on the active delivery system and Attack an Enemy! If the game state is Peacetime, it is now War!

If you did not launch a nuke, the next player in turn order takes their turn starting from step 1. If you did, once the attack is resolved – as long as no anti-missiles change whose turn it is – the next player in turn order takes their turn starting from step 1.

=== Attacking the Enemy ===

If you have launched a warhead, choose a target player. Then follow the steps below to resolve the strike:

# The target may use an anti-missile or a Saboteur to shoot down the delivery system or foil the launch. If they do, discard your delivery system and any of your warhead(s) that are face-up.
# If a launch is stopped by an anti-missile (not a Saboteur) the player that used the anti-missile immediately takes their turn, skipping all the players between the launching player and the target.
# If the target does not stop the attack, spin the spinner to find out the extra effects of the nuclear strike.
# You may roll the Nuclear Escalation die. If you do, add the amount rolled to the total population loss. If a Nuclear Cloud is rolled, roll on the malfunction chart.

The target then discards the amount of population equal to the damage dealt by the warhead. The target player may make change from unused population cards if needed. If the target does not have enough population, they are eliminated and they may make a final strike!

'''''Example:''' Trent takes 22 Million damage from a warhead, and discards a 25 Million population card, taking a 2 million and a 1 million population card from the unused population cards.''

# If the delivery system is a missile, discard the missile and warhead. If it is a bomber, only discard the bomber and warhead(s) if the total megatonnage of warheads on the bomber equals or exceeds its maximum tonnage.

==== Spinner Results ====

'''Radioactive Beta Rays Kill another 5 million.''' Add 5 million to the population loss on the warhead.

'''An additional 1 million are engulfed in the fireball.''' Add 1 million to the population loss on the warhead.

'''Dirty Bomb! Double the Yield.''' Double the population loss listed on the warhead. If the warhead is a 200 megaton warhead or larger, the world blows up, spreading nuclear fallout throughout the solar system and everyone loses. Smooth move!

'''No Appreciable Radiation Fallout.''' No extra effect, use the amount of population loss listed on the warhead.

'''Explodes a Nuclear Stockpile Triple the Yield.''' Triple the population loss listed on the warhead. If the warhead is 100 Megatons or more the world blows up in a massive chain reaction, spreading radioactive fallout throughout the solar system and everyone loses! Welcome to the new asteroid belt.

'''Bomb Shelters Save 2 Million.''' Reduce the amount of population loss by 2 million on the warhead. If this results in less than zero loss, treat it as a zero loss.

'''Lethal Doses of Radioactive Gamma Rays Kill Another 10 Million.''' Add 10 million to the population loss on the warhead.

'''Dud Warhead! (No Effect).''' Place the warhead on the delivery system without effect. Your attack ends, it is now the next player’s turn.

'''Radioactive Fallout Kills Another 2 Million.''' Add 2 Million to the population loss on the warhead.

'''Missile Booster Explodes on Launch (or Bomber Runs Out of Fuel)''' Discard the delivery system and the warhead(s). Your attack ends, it is now the next player’s turn.

==== Nuclear Escalation Die Roll Results ====

'''Cloud: Disaster!''' You have somehow directed this warhead at one of your own cities. You lose the population rather than your target.

'''2: Orbital Burst!''' The warhead goes off in the atmosphere over your country! Discard your delivery system and all face-up warheads on your player mat. You skip your next turn!

'''3: Missile Booster Explodes on Launch''' (or a Bomber Runs out of fuel) Discard the Delivery system and the warhead(s). Your attack ends and it is now the next player's turn.

'''4: This Warhead is a dud.''' Place the warhead on its delivery system without effect. Your attack ends and it is the next player's turn.

'''5: Neutron Bomb! Double the yield.''' Double the population loss listed on the warhead.

'''6: You hit a nuclear power plant.''' You do double damage, and your opponent misses one turn! Double the population loss listed on the warhead. Remind your opponent to skip their next turn.

=== Player Elimination and Final Strike ===

If you lose all of your population, you have been eliminated from the game.

If you’ve been eliminated through propaganda, you are out of the game, and the other players continue playing the game until there is a winner, or everyone loses.

If you are eliminated through any other means (i.e. secrets, or nuclear attack) you have the option to launch a final strike. You may play all the cards in your hand and on your launch mat. Combining any eligible warhead with your delivery systems in any way you wish. Once you have combined all of your eligible delivery systems and warheads, you may launch them at any targets you wish. Resolve them one at a time, just as above.

Anti-missiles will shoot down a final strike target, but it will not stop the rest of your final strike. The same is true for any dud or failed launch from the spinner.

The player to last play an anti-missile during the final strike will become the next player, otherwise, play continues clockwise. The exception is if another player is eliminated during a final strike, in which case they perform their final strike immediately after the first final strike is finished.

It is possible that a chain reaction of final strikes will '''eliminate all''' remaining players. If this happens, everyone loses the game, just like a real nuclear war! Once a player is eliminated and has played their final strike, it becomes Peacetime.

'''''Example:''' Trent has been eliminated and is planning out his final strike. He has 3 missiles and a bomber loaded with megatonnage. He looses his bomber on Brittany, who had eliminated him, but Brittany shoots it down with an anti-missile. Trent sighs and decides to send the rest of his missiles against Ed. Ed is eliminated and immediately begins his final strike, ignoring Brittanyâ€™s use of the anti-missile. If everyone left survives Ed's final strike, then Brittany will begin her turn, unless another player had played an anti-missile.''

==== When Peace is Declared... ====

When it becomes Peacetime, you may pick up all your cards on the launch track and replace them with cards from your hand.

=== Winning the Ultimate Victory ===

If, after all final strikes, you are the only remaining player with population, You have “won” the game! Your remaining population will enjoy the nuclear winter that follows and begin to slowly rebuild civilization.

=== Deterrent Force ===

If you have a powerful weapon in your hand you may wish to display it in order to discourage an enemy attack. You may, as part of your turn, place one or two cards face up in the deterrent force area as shown on the launch mat. A Saturn missile and a 100-megaton warhead, for example, may cause an enemy to think twice before beginning a nuclear exchange.

Cards in your deterrent force area remain part of your hand and must be put into play in the same way as any other cards. Any specials or secrets that affect your hand also affect any cards in the deterrent force. You should pick up your deterrents before resolving a secret that affects your hand.

== Optional Rules ==

=== More people! ===

Before dealing starting populations, give each player one 25 million population card. Then deal one less population card to all the players.

=== Not so secretive! ===

If a player has more than two secrets dealt to them at the beginning, randomly choose two of them, return the rest to the bottom of the deck and draw replacements. If more secrets are drawn they are also put at the bottom of the deck and replaced.

=== Bombers aren’t quite as fast as Missiles! ===

When launching a Bomber you must target a player sitting next to you. After targeting that player you may fly to the player sitting next to the current target or stay on the current target with the next warhead the bomber carries. During a Final Strike, a bomber must target only one player.

Gamehelpnuclearwar

2026-03-16T00:26:25Z

BaronFraser: /* Winning the Ultimate Victory */

== Introduction ==

The atomic bomb has been invented. Nations are building up their stockpiles of atomic bombs while vying for the hearts and minds of their rivals’ populace. Welcome to the world of Nuclear War!

The game begins with an uneasy cold war between all the players, each representing a nuclear power. Once the first player launches a nuclear warhead, the war turns hot as populations decrease in huge balls of nuclear fire. Will there be any nation left when the last bomb has fallen?

== Object ==

In Nuclear War players seek world domination by eliminating the other major powers. This can be accomplished in two ways:

* The peaceful way is to persuade the populations of opposing countries to join your superior form of government through the use of propaganda cards.
* The warlike way is to destroy the enemy’s population by using nuclear weapons.

Population is the measure of success or failure in the game. A player who loses their entire population is eliminated. The last player with population wins the game, but sometimes everyone is engulfed in flames and there are only losers.

== Set Up ==

# Shuffle the population cards. Based on the player count, deal each player the following number of cards: 2 players: 15 cards; 3 players: 10 cards; 4 players: 8 cards; 5 players: 7 cards; 6+ players: 6 cards. Deal these cards face down. Only you may look at your population cards.
# Place the remaining population cards in a face up stack in the middle of the table forming a bank. Players may use the bank to make ‘change’ only when they are forced to lose population.
# Shuffle the Nuclear War cards and deal 9 face-down to each player. You may examine your cards but not other player’s.
# Place the remaining Nuclear War cards in a face-down stack in the middle of the table. This is a draw deck.
# The first player is randomly chosen. Play will proceed clockwise around the table from the first player.
# The first player examines their cards for any secrets and top secrets. If they have any, they play them. Once the first player has a hand with no secrets, the next player in turn declares and plays secrets. Continue this around the table until no one has any secrets left!

'''NOTE''': '''Spies!''' To play a '''secret''' you announce that you have a secret, then give each other player a moment to decide if they want to play a spy. If no one plays a '''spy''', reveal and resolve the secret. Repeat this process every time you play a secret.

7: All players, at the same time, choose and place 1 card facedown in each of the two face-down slots on their playmat. These are the cards that will be played on your first and second turn respectively!
8: Now you are ready to play! The first player takes the first turn.

== Overview of Gameplay ==

On your turn you will:

* Draw cards until you have 8 in your hand.
* Play secrets and draw replacement cards until no secrets are in hand.
* Move the cards on your launch track forward to the next box
* Place a card into the 2nd face-down slot
* Reveal the card in the face-up slot and play it.

== War and Peace ==

Nuclear War has two game states - '''Peacetime''' and '''War'''. The game state affects how some cards work.

The game starts in Peacetime. Once there is a successful launch of a delivery system with a warhead, whether or not the launch results in population loss, the game state changes to War.

The game state remains in War until one player is eliminated and has performed their final strike (see page 7). At that point, Peacetime begins again… until the next warhead is launched.

Whenever Peacetime begins all players pick up the face-down cards on their launch track (see below). They then replace those cards with any cards from their hand, including the cards they just picked up. Active delivery systems remain active.

== Components Overview ==

=== Launch Track ===

In Nuclear War, you must plan your moves two turns in advance using the Launch Track.

Your Launch track is three spaces. The face-up space is for the card you are using this turn. The first face-down card is the card you will use next turn, and the second face-down space is the card you will play two turns from now.

'''2nd Face Down Card''' -> '''1st Face Down Card''' -> '''FACE UP CARD'''

You may look at facedown cards on your Launch Track whenever you want. You cannot change the order, or discard cards. Once you play a card to your Launch Track it is locked in!

Your Launch Track may only have delivery systems, warheads, and propaganda cards on it. If you ever reveal a card that is not a delivery system, warhead, or propaganda card, it is discarded without effect. This counts as your turn!

If your launch track is ever empty you must fill it immediately, if you don’t have enough eligible cards in your hand you must fill it on your next turn during the Play a Card step

== Card Types ==

=== Propagandas ===

During Peacetime, propaganda cards are used to steal population from other players (ie, the population defects to your nation). During Wartime, some propaganda cards allow you to draw new cards from the deck.

Whenever you steal population with a propaganda card, if the player doesn’t have enough population to give you, they give all their remaining population, and then they are eliminated from the game.

=== Delivery Systems ===

In order to launch a warhead in Nuclear Destruction, you need to have an appropriate delivery system.

Delivery systems are played in your launch track before a warhead. To launch a warhead, first, you must reveal a delivery system, and in the subsequent turn, reveal a warhead to go with that delivery system. If any card follows a delivery system that isn’t compatible with that delivery system, the delivery system will be discarded.

There are two main types of delivery systems: bombers and missiles. The two types of delivery systems work slightly differently when they are launched. For resolving a launch, see the Attacking the Enemy section.

The '''evasion rating''' on delivery systems determines how vulnerable they are to Anti-Missile cards. The Evasion rating has a letter, either M(Missile) or B(Bomber), and a number. See Anti-Missile cards (below) for details on evading a launch.

'''NOTE:''' If you shoot down a delivery system with an anti-missile, you play next, skipping all the players between.

==== Missiles ====

Missile delivery systems can carry one warhead up to a maximum megatonnage listed on the card.

'''''Example:''' An East Wind-DS31 Missile may carry a single warhead of up to 25 Megatons.''

Launching a missile requires playing the missile, and on the next turn, following it with a warhead of an appropriate size. After launching a missile it, and the warhead it carried, are discarded.

==== Bombers ====

Bombers are launched just like missiles: you reveal one and on the next turn reveal a warhead with low enough tonnage to be carried by it. Unlike missiles, a bomber is not discarded after delivering a payload. Instead, a bomber may deliver multiple warheads, each on its own turn, until the total megatonnage of war-heads delivered equals the bomber rating.

Bombers may bomb different enemy powers on different turns, flying over to the offending country. You do not discard a warhead delivered by a bomber. Instead, place the warhead under the bomber with its megatonnage showing so you can keep track of the megatonnage that the bomber has used. You only discard the warheads delivered by a bomber when the bomber is discarded. If you reveal a warhead that doesn’t fit the bomber, the warhead, the bomber, and all warheads under the bomber, are immediately discarded.

'''''Example:''' On The first turn, Ed launches the B-58 Bomber, which carries up to 60 mega-tons of warheads. On the next turn, Ed reveals a 20-megaton warhead. After resolving the strike, the 20-megaton warhead is kept with the B-58 Bomber. On the following turn, Ed reveals a 10-megaton warhead, this again is stacked with the bomber after resolving. In the next turn Ed reveals a 40-megaton warhead, this exceeds the bombers max-imum tonnage, and so the bomber along with all three warheads are discarded. The 40-megaton warhead would have no effect.''

==== Warheads ====

Warhead cards are played after a delivery system on the launch track. Warhead cards are rated by megatonnage, and how much population they destroy. The megatonnage is a limit to certain delivery systems, A larger megaton warhead that follows a delivery system not capable of carrying it is discarded along with the delivery system without effect. If the warhead fits on the delivery system played before it, the warhead has successfully launched and can target any other player. See Attacking a Player.

==== Anti Missiles ====

Anti-Missiles are reactive cards. They are played directly out of your hand when another player targets you with a warhead. When a delivery system targets you, you may discard an anti-missile to shoot down the delivery system. All anti-missiles are rated for what they will shoot down. Anti-Missiles have two ratings, one for Bombers (B) and one for Missiles (M). If the rating of the anti-missile is equal to or higher than the evasion rating of the incoming delivery system, the anti-missile can shoot it down.

If you cannot shoot down the incoming delivery system, you may not play an anti-missile. You may not use an anti-missile to help another player. You may only shoot down delivery systems targeting you.

When you successfully use an anti-missile, it becomes your turn, skipping all other players. Play continues clockwise after you have finished your turn.

==== Secrets and Top Secrets ====

Secrets are resolved, one at a time, when drawn, and do not go through the launch track. When drawn, announce you have a secret, as it may be stolen by a Spy. If it isn't stolen, play it. Each secret is a random event that has an effect on the game. Resolve the text, and then draw a replacement card. If the replacement is also a secret, resolve that one, and draw another replacement, continue to resolve secrets until a non-secret is drawn. If you have more than one secret in your hand, you choose which secret or top secret to resolve first. Top Secrets are resolved the same way as secrets, with the exception you have to announce it is a Top Secret. Top Secrets tend to be more powerful.

'''SECRETS!''' Secrets can be good or bad. When you draw a secret it is played before you begin your turn. Remember to give your opponents a chance to steal it before revealing the secret and resolving it!

==== Specials ====

Special cards are cards that are played out of your hand. Each Special explains when it may be played and what it does when you play it.

==== Hybrid Cards ====

Hybrid cards show both a warhead and a delivery system. When a hybrid card is revealed the revealing player decides which option to use. After choosing which option, the card is considered to be that type until discarded.

== Game Turn in Detail ==

=== Draw Cards ===

At the start of your turn, draw cards until you have 8 cards in hand.

If you have a secret in your hand you must announce you have a secret, and if no Spy steals it, then read it aloud and resolve the effects of the secret. If you draw more than one secret, you must play all of them, but you choose the order you play them. Whenever you play a secret or have it stolen from you, you draw a replacement card.

=== Play a Card ===

After drawing, slide your cards along the launch track pushing the first face-down card to the face-up card space, and the second face-down card to the first face-down card space. After sliding your cards over, place another card from your hand, face-down, onto the second face-down space.

=== Reveal a Card ===

Reveal and resolve the card in the face-up space. If the card is a propaganda card use the appropriate effect depending on whether it is Peacetime or War.

If it is a delivery system, place it in your active delivery system space, discarding any delivery system already there.

If it is a warhead, and there is a delivery system in your active delivery system space that can hold the warhead, congratulations, you’ve launched a nuke! Place the warhead on the active delivery system and Attack an Enemy! If the game state is Peacetime, it is now War!

If you did not launch a nuke, the next player in turn order takes their turn starting from step 1. If you did, once the attack is resolved – as long as no anti-missiles change whose turn it is – the next player in turn order takes their turn starting from step 1.

=== Attacking the Enemy ===

If you have launched a warhead, choose a target player. Then follow the steps below to resolve the strike:

# The target may use an anti-missile or a Saboteur to shoot down the delivery system or foil the launch. If they do, discard your delivery system and any of your warhead(s) that are face-up.
# If a launch is stopped by an anti-missile (not a Saboteur) the player that used the anti-missile immediately takes their turn, skipping all the players between the launching player and the target.
# If the target does not stop the attack, spin the spinner to find out the extra effects of the nuclear strike.
# You may roll the Nuclear Escalation die. If you do, add the amount rolled to the total population loss. If a Nuclear Cloud is rolled, roll on the malfunction chart.

The target then discards the amount of population equal to the damage dealt by the warhead. The target player may make change from unused population cards if needed. If the target does not have enough population, they are eliminated and they may make a final strike!

'''''Example:''' Trent takes 22 Million damage from a warhead, and discards a 25 Million population card, taking a 2 million and a 1 million population card from the unused population cards.''

# If the delivery system is a missile, discard the missile and warhead. If it is a bomber, only discard the bomber and warhead(s) if the total megatonnage of warheads on the bomber equals or exceeds its maximum tonnage.

==== Spinner Results ====

'''Radioactive Beta Rays Kill another 5 million.''' Add 5 million to the population loss on the warhead.

'''An additional 1 million are engulfed in the fireball.''' Add 1 million to the population loss on the warhead.

'''Dirty Bomb! Double the Yield.''' Double the population loss listed on the warhead. If the warhead is a 200 megaton warhead or larger, the world blows up, spreading nuclear fallout throughout the solar system and everyone loses. Smooth move!

'''No Appreciable Radiation Fallout.''' No extra effect, use the amount of population loss listed on the warhead.

'''Explodes a Nuclear Stockpile Triple the Yield.''' Triple the population loss listed on the warhead. If the warhead is 100 Megatons or more the world blows up in a massive chain reaction, spreading radioactive fallout throughout the solar system and everyone loses! Welcome to the new asteroid belt.

'''Bomb Shelters Save 2 Million.''' Reduce the amount of population loss by 2 million on the warhead. If this results in less than zero loss, treat it as a zero loss.

'''Lethal Doses of Radioactive Gamma Rays Kill Another 10 Million.''' Add 10 million to the population loss on the warhead.

'''Dud Warhead! (No Effect).''' Place the warhead on the delivery system without effect. Your attack ends, it is now the next player’s turn.

'''Radioactive Fallout Kills Another 2 Million.''' Add 2 Million to the population loss on the warhead.

'''Missile Booster Explodes on Launch (or Bomber Runs Out of Fuel)''' Discard the delivery system and the warhead(s). Your attack ends, it is now the next player’s turn.

==== Nuclear Escalation Die Roll Results ====

'''Cloud: Disaster!''' You have somehow directed this warhead at one of your own cities. You lose the population rather than your target.

'''2: Orbital Burst!''' The warhead goes off in the atmosphere over your country! Discard your delivery system and all face-up warheads on your player mat. You skip your next turn!

'''3: Missile Booster Explodes on Launch''' (or a Bomber Runs out of fuel) Discard the Delivery system and the warhead(s). Your attack ends and it is now the next player's turn.

'''4: This Warhead is a dud.''' Place the warhead on its delivery system without effect. Your attack ends and it is the next player's turn.

'''5: Neutron Bomb! Double the yield.''' Double the population loss listed on the warhead.

'''6: You hit a nuclear power plant.''' You do double damage, and your opponent misses one turn! Double the population loss listed on the warhead. Remind your opponent to skip their next turn.

=== Player Elimination and Final Strike ===

If you lose all of your population, you have been eliminated from the game.

If you’ve been eliminated through propaganda, you are out of the game, and the other players continue playing the game until there is a winner, or everyone loses.

If you are eliminated through any other means (i.e. secrets, or nuclear attack) you have the option to launch a final strike. You may play all the cards in your hand and on your launch mat. Combining any eligible warhead with your delivery systems in any way you wish. Once you have combined all of your eligible delivery systems and warheads, you may launch them at any targets you wish. Resolve them one at a time, just as above.

Anti-missiles will shoot down a final strike target, but it will not stop the rest of your final strike. The same is true for any dud or failed launch from the spinner.

The player to last play an anti-missile during the final strike will become the next player, otherwise, play continues clockwise. The exception is if another player is eliminated during a final strike, in which case they perform their final strike immediately after the first final strike is finished.

It is possible that a chain reaction of final strikes will '''eliminate all''' remaining players. If this happens, everyone loses the game, just like a real nuclear war! Once a player is eliminated and has played their final strike, it becomes Peacetime.

'''''Example:''' Trent has been eliminated and is planning out his final strike. He has 3 missiles and a bomber loaded with megatonnage. He looses his bomber on Brittany, who had eliminated him, but Brittany shoots it down with an anti-missile. Trent sighs and decides to send the rest of his missiles against Ed. Ed is eliminated and immediately begins his final strike, ignoring Brittanyâ€™s use of the anti-missile. If everyone left survives Ed's final strike, then Brittany will begin her turn, unless another player had played an anti-missile.''

==== When Peace is Declared... ====

When it becomes Peacetime, you may pick up all your cards on the launch track and replace them with cards from your hand.

=== Winning the Ultimate Victory ===

If, after all final strikes, you are the only remaining player with population, You have “won” the game! Your remaining population will enjoy the nuclear winter that follows and begin to slowly rebuild civilization.

=== Deterrent Force ===

If you have a powerful weapon in your hand you may wish to display it in order to discourage an enemy attack. You may, as part of your turn, place one or two cards face up in the deterrent force area as shown on the launch mat. A Saturn missile and a 100-megaton warhead, for example, may cause an enemy to think twice before beginning a nuclear exchange.

Cards in your deterrent force area remain part of your hand and must be put into play in the same way as any other cards. Any specials or secrets that affect your hand also affect any cards in the deterrent force. You should pick up your deterrents before resolving a secret that affects your hand.

== Optional Rules ==

=== More people! ===

Before dealing starting populations, give each player one 25 million population card. Then deal one less population card to all the players.

=== Not so secretive! ===

If a player has more than two secrets dealt to them at the beginning, randomly choose two of them, return the rest to the bottom of the deck and draw replacements. If more secrets are drawn they are also put at the bottom of the deck and replaced.

=== Bombers aren’t quite as fast as Missiles! ===

When launching a Bomber you must target a player sitting next to you. After targeting that player you may fly to the player sitting next to the current target or stay on the current target with the next warhead the bomber carries. During a Final Strike, a bomber must target only one player.

Gamehelpnuclearwar

2026-03-16T00:25:41Z

BaronFraser: /* Player Elimination and Final Strike */

== Introduction ==

The atomic bomb has been invented. Nations are building up their stockpiles of atomic bombs while vying for the hearts and minds of their rivals’ populace. Welcome to the world of Nuclear War!

The game begins with an uneasy cold war between all the players, each representing a nuclear power. Once the first player launches a nuclear warhead, the war turns hot as populations decrease in huge balls of nuclear fire. Will there be any nation left when the last bomb has fallen?

== Object ==

In Nuclear War players seek world domination by eliminating the other major powers. This can be accomplished in two ways:

* The peaceful way is to persuade the populations of opposing countries to join your superior form of government through the use of propaganda cards.
* The warlike way is to destroy the enemy’s population by using nuclear weapons.

Population is the measure of success or failure in the game. A player who loses their entire population is eliminated. The last player with population wins the game, but sometimes everyone is engulfed in flames and there are only losers.

== Set Up ==

# Shuffle the population cards. Based on the player count, deal each player the following number of cards: 2 players: 15 cards; 3 players: 10 cards; 4 players: 8 cards; 5 players: 7 cards; 6+ players: 6 cards. Deal these cards face down. Only you may look at your population cards.
# Place the remaining population cards in a face up stack in the middle of the table forming a bank. Players may use the bank to make ‘change’ only when they are forced to lose population.
# Shuffle the Nuclear War cards and deal 9 face-down to each player. You may examine your cards but not other player’s.
# Place the remaining Nuclear War cards in a face-down stack in the middle of the table. This is a draw deck.
# The first player is randomly chosen. Play will proceed clockwise around the table from the first player.
# The first player examines their cards for any secrets and top secrets. If they have any, they play them. Once the first player has a hand with no secrets, the next player in turn declares and plays secrets. Continue this around the table until no one has any secrets left!

'''NOTE''': '''Spies!''' To play a '''secret''' you announce that you have a secret, then give each other player a moment to decide if they want to play a spy. If no one plays a '''spy''', reveal and resolve the secret. Repeat this process every time you play a secret.

7: All players, at the same time, choose and place 1 card facedown in each of the two face-down slots on their playmat. These are the cards that will be played on your first and second turn respectively!
8: Now you are ready to play! The first player takes the first turn.

== Overview of Gameplay ==

On your turn you will:

* Draw cards until you have 8 in your hand.
* Play secrets and draw replacement cards until no secrets are in hand.
* Move the cards on your launch track forward to the next box
* Place a card into the 2nd face-down slot
* Reveal the card in the face-up slot and play it.

== War and Peace ==

Nuclear War has two game states - '''Peacetime''' and '''War'''. The game state affects how some cards work.

The game starts in Peacetime. Once there is a successful launch of a delivery system with a warhead, whether or not the launch results in population loss, the game state changes to War.

The game state remains in War until one player is eliminated and has performed their final strike (see page 7). At that point, Peacetime begins again… until the next warhead is launched.

Whenever Peacetime begins all players pick up the face-down cards on their launch track (see below). They then replace those cards with any cards from their hand, including the cards they just picked up. Active delivery systems remain active.

== Components Overview ==

=== Launch Track ===

In Nuclear War, you must plan your moves two turns in advance using the Launch Track.

Your Launch track is three spaces. The face-up space is for the card you are using this turn. The first face-down card is the card you will use next turn, and the second face-down space is the card you will play two turns from now.

'''2nd Face Down Card''' -> '''1st Face Down Card''' -> '''FACE UP CARD'''

You may look at facedown cards on your Launch Track whenever you want. You cannot change the order, or discard cards. Once you play a card to your Launch Track it is locked in!

Your Launch Track may only have delivery systems, warheads, and propaganda cards on it. If you ever reveal a card that is not a delivery system, warhead, or propaganda card, it is discarded without effect. This counts as your turn!

If your launch track is ever empty you must fill it immediately, if you don’t have enough eligible cards in your hand you must fill it on your next turn during the Play a Card step

== Card Types ==

=== Propagandas ===

During Peacetime, propaganda cards are used to steal population from other players (ie, the population defects to your nation). During Wartime, some propaganda cards allow you to draw new cards from the deck.

Whenever you steal population with a propaganda card, if the player doesn’t have enough population to give you, they give all their remaining population, and then they are eliminated from the game.

=== Delivery Systems ===

In order to launch a warhead in Nuclear Destruction, you need to have an appropriate delivery system.

Delivery systems are played in your launch track before a warhead. To launch a warhead, first, you must reveal a delivery system, and in the subsequent turn, reveal a warhead to go with that delivery system. If any card follows a delivery system that isn’t compatible with that delivery system, the delivery system will be discarded.

There are two main types of delivery systems: bombers and missiles. The two types of delivery systems work slightly differently when they are launched. For resolving a launch, see the Attacking the Enemy section.

The '''evasion rating''' on delivery systems determines how vulnerable they are to Anti-Missile cards. The Evasion rating has a letter, either M(Missile) or B(Bomber), and a number. See Anti-Missile cards (below) for details on evading a launch.

'''NOTE:''' If you shoot down a delivery system with an anti-missile, you play next, skipping all the players between.

==== Missiles ====

Missile delivery systems can carry one warhead up to a maximum megatonnage listed on the card.

'''''Example:''' An East Wind-DS31 Missile may carry a single warhead of up to 25 Megatons.''

Launching a missile requires playing the missile, and on the next turn, following it with a warhead of an appropriate size. After launching a missile it, and the warhead it carried, are discarded.

==== Bombers ====

Bombers are launched just like missiles: you reveal one and on the next turn reveal a warhead with low enough tonnage to be carried by it. Unlike missiles, a bomber is not discarded after delivering a payload. Instead, a bomber may deliver multiple warheads, each on its own turn, until the total megatonnage of war-heads delivered equals the bomber rating.

Bombers may bomb different enemy powers on different turns, flying over to the offending country. You do not discard a warhead delivered by a bomber. Instead, place the warhead under the bomber with its megatonnage showing so you can keep track of the megatonnage that the bomber has used. You only discard the warheads delivered by a bomber when the bomber is discarded. If you reveal a warhead that doesn’t fit the bomber, the warhead, the bomber, and all warheads under the bomber, are immediately discarded.

'''''Example:''' On The first turn, Ed launches the B-58 Bomber, which carries up to 60 mega-tons of warheads. On the next turn, Ed reveals a 20-megaton warhead. After resolving the strike, the 20-megaton warhead is kept with the B-58 Bomber. On the following turn, Ed reveals a 10-megaton warhead, this again is stacked with the bomber after resolving. In the next turn Ed reveals a 40-megaton warhead, this exceeds the bombers max-imum tonnage, and so the bomber along with all three warheads are discarded. The 40-megaton warhead would have no effect.''

==== Warheads ====

Warhead cards are played after a delivery system on the launch track. Warhead cards are rated by megatonnage, and how much population they destroy. The megatonnage is a limit to certain delivery systems, A larger megaton warhead that follows a delivery system not capable of carrying it is discarded along with the delivery system without effect. If the warhead fits on the delivery system played before it, the warhead has successfully launched and can target any other player. See Attacking a Player.

==== Anti Missiles ====

Anti-Missiles are reactive cards. They are played directly out of your hand when another player targets you with a warhead. When a delivery system targets you, you may discard an anti-missile to shoot down the delivery system. All anti-missiles are rated for what they will shoot down. Anti-Missiles have two ratings, one for Bombers (B) and one for Missiles (M). If the rating of the anti-missile is equal to or higher than the evasion rating of the incoming delivery system, the anti-missile can shoot it down.

If you cannot shoot down the incoming delivery system, you may not play an anti-missile. You may not use an anti-missile to help another player. You may only shoot down delivery systems targeting you.

When you successfully use an anti-missile, it becomes your turn, skipping all other players. Play continues clockwise after you have finished your turn.

==== Secrets and Top Secrets ====

Secrets are resolved, one at a time, when drawn, and do not go through the launch track. When drawn, announce you have a secret, as it may be stolen by a Spy. If it isn't stolen, play it. Each secret is a random event that has an effect on the game. Resolve the text, and then draw a replacement card. If the replacement is also a secret, resolve that one, and draw another replacement, continue to resolve secrets until a non-secret is drawn. If you have more than one secret in your hand, you choose which secret or top secret to resolve first. Top Secrets are resolved the same way as secrets, with the exception you have to announce it is a Top Secret. Top Secrets tend to be more powerful.

'''SECRETS!''' Secrets can be good or bad. When you draw a secret it is played before you begin your turn. Remember to give your opponents a chance to steal it before revealing the secret and resolving it!

==== Specials ====

Special cards are cards that are played out of your hand. Each Special explains when it may be played and what it does when you play it.

==== Hybrid Cards ====

Hybrid cards show both a warhead and a delivery system. When a hybrid card is revealed the revealing player decides which option to use. After choosing which option, the card is considered to be that type until discarded.

== Game Turn in Detail ==

=== Draw Cards ===

At the start of your turn, draw cards until you have 8 cards in hand.

If you have a secret in your hand you must announce you have a secret, and if no Spy steals it, then read it aloud and resolve the effects of the secret. If you draw more than one secret, you must play all of them, but you choose the order you play them. Whenever you play a secret or have it stolen from you, you draw a replacement card.

=== Play a Card ===

After drawing, slide your cards along the launch track pushing the first face-down card to the face-up card space, and the second face-down card to the first face-down card space. After sliding your cards over, place another card from your hand, face-down, onto the second face-down space.

=== Reveal a Card ===

Reveal and resolve the card in the face-up space. If the card is a propaganda card use the appropriate effect depending on whether it is Peacetime or War.

If it is a delivery system, place it in your active delivery system space, discarding any delivery system already there.

If it is a warhead, and there is a delivery system in your active delivery system space that can hold the warhead, congratulations, you’ve launched a nuke! Place the warhead on the active delivery system and Attack an Enemy! If the game state is Peacetime, it is now War!

If you did not launch a nuke, the next player in turn order takes their turn starting from step 1. If you did, once the attack is resolved – as long as no anti-missiles change whose turn it is – the next player in turn order takes their turn starting from step 1.

=== Attacking the Enemy ===

If you have launched a warhead, choose a target player. Then follow the steps below to resolve the strike:

# The target may use an anti-missile or a Saboteur to shoot down the delivery system or foil the launch. If they do, discard your delivery system and any of your warhead(s) that are face-up.
# If a launch is stopped by an anti-missile (not a Saboteur) the player that used the anti-missile immediately takes their turn, skipping all the players between the launching player and the target.
# If the target does not stop the attack, spin the spinner to find out the extra effects of the nuclear strike.
# You may roll the Nuclear Escalation die. If you do, add the amount rolled to the total population loss. If a Nuclear Cloud is rolled, roll on the malfunction chart.

The target then discards the amount of population equal to the damage dealt by the warhead. The target player may make change from unused population cards if needed. If the target does not have enough population, they are eliminated and they may make a final strike!

'''''Example:''' Trent takes 22 Million damage from a warhead, and discards a 25 Million population card, taking a 2 million and a 1 million population card from the unused population cards.''

# If the delivery system is a missile, discard the missile and warhead. If it is a bomber, only discard the bomber and warhead(s) if the total megatonnage of warheads on the bomber equals or exceeds its maximum tonnage.

==== Spinner Results ====

'''Radioactive Beta Rays Kill another 5 million.''' Add 5 million to the population loss on the warhead.

'''An additional 1 million are engulfed in the fireball.''' Add 1 million to the population loss on the warhead.

'''Dirty Bomb! Double the Yield.''' Double the population loss listed on the warhead. If the warhead is a 200 megaton warhead or larger, the world blows up, spreading nuclear fallout throughout the solar system and everyone loses. Smooth move!

'''No Appreciable Radiation Fallout.''' No extra effect, use the amount of population loss listed on the warhead.

'''Explodes a Nuclear Stockpile Triple the Yield.''' Triple the population loss listed on the warhead. If the warhead is 100 Megatons or more the world blows up in a massive chain reaction, spreading radioactive fallout throughout the solar system and everyone loses! Welcome to the new asteroid belt.

'''Bomb Shelters Save 2 Million.''' Reduce the amount of population loss by 2 million on the warhead. If this results in less than zero loss, treat it as a zero loss.

'''Lethal Doses of Radioactive Gamma Rays Kill Another 10 Million.''' Add 10 million to the population loss on the warhead.

'''Dud Warhead! (No Effect).''' Place the warhead on the delivery system without effect. Your attack ends, it is now the next player’s turn.

'''Radioactive Fallout Kills Another 2 Million.''' Add 2 Million to the population loss on the warhead.

'''Missile Booster Explodes on Launch (or Bomber Runs Out of Fuel)''' Discard the delivery system and the warhead(s). Your attack ends, it is now the next player’s turn.

==== Nuclear Escalation Die Roll Results ====

'''Cloud: Disaster!''' You have somehow directed this warhead at one of your own cities. You lose the population rather than your target.

'''2: Orbital Burst!''' The warhead goes off in the atmosphere over your country! Discard your delivery system and all face-up warheads on your player mat. You skip your next turn!

'''3: Missile Booster Explodes on Launch''' (or a Bomber Runs out of fuel) Discard the Delivery system and the warhead(s). Your attack ends and it is now the next player's turn.

'''4: This Warhead is a dud.''' Place the warhead on its delivery system without effect. Your attack ends and it is the next player's turn.

'''5: Neutron Bomb! Double the yield.''' Double the population loss listed on the warhead.

'''6: You hit a nuclear power plant.''' You do double damage, and your opponent misses one turn! Double the population loss listed on the warhead. Remind your opponent to skip their next turn.

=== Player Elimination and Final Strike ===

If you lose all of your population, you have been eliminated from the game.

If you’ve been eliminated through propaganda, you are out of the game, and the other players continue playing the game until there is a winner, or everyone loses.

If you are eliminated through any other means (i.e. secrets, or nuclear attack) you have the option to launch a final strike. You may play all the cards in your hand and on your launch mat. Combining any eligible warhead with your delivery systems in any way you wish. Once you have combined all of your eligible delivery systems and warheads, you may launch them at any targets you wish. Resolve them one at a time, just as above.

Anti-missiles will shoot down a final strike target, but it will not stop the rest of your final strike. The same is true for any dud or failed launch from the spinner.

The player to last play an anti-missile during the final strike will become the next player, otherwise, play continues clockwise. The exception is if another player is eliminated during a final strike, in which case they perform their final strike immediately after the first final strike is finished.

It is possible that a chain reaction of final strikes will '''eliminate all''' remaining players. If this happens, everyone loses the game, just like a real nuclear war! Once a player is eliminated and has played their final strike, it becomes Peacetime.

'''''Example:''' Trent has been eliminated and is planning out his final strike. He has 3 missiles and a bomber loaded with megatonnage. He looses his bomber on Brittany, who had eliminated him, but Brittany shoots it down with an anti-missile. Trent sighs and decides to send the rest of his missiles against Ed. Ed is eliminated and immediately begins his final strike, ignoring Brittanyâ€™s use of the anti-missile. If everyone left survives Ed's final strike, then Brittany will begin her turn, unless another player had played an anti-missile.''

==== When Peace is Declared... ====

When it becomes Peacetime, you may pick up all your cards on the launch track and replace them with cards from your hand.

=== Winning the Ultimate Victory ===

If, after all final strikes, you are the only remaining player with population, You have “won” the game! Your remaining population will enjoy the nuclear winter that follows and begin to slowly rebuild civilization.

==== Deterrent Force ====

If you have a powerful weapon in your hand you may wish to display it in order to discourage an enemy attack. You may, as part of your turn, place one or two cards face up in the deterrent force area as shown on the launch mat. A Saturn missile and a 100-megaton warhead, for example, may cause an enemy to think twice before beginning a nuclear exchange.

Cards in your deterrent force area remain part of your hand and must be put into play in the same way as any other cards. Any specials or secrets that affect your hand also affect any cards in the deterrent force. You should pick up your deterrents before resolving a secret that affects your hand.

== Optional Rules ==

=== More people! ===

Before dealing starting populations, give each player one 25 million population card. Then deal one less population card to all the players.

=== Not so secretive! ===

If a player has more than two secrets dealt to them at the beginning, randomly choose two of them, return the rest to the bottom of the deck and draw replacements. If more secrets are drawn they are also put at the bottom of the deck and replaced.

=== Bombers aren’t quite as fast as Missiles! ===

When launching a Bomber you must target a player sitting next to you. After targeting that player you may fly to the player sitting next to the current target or stay on the current target with the next warhead the bomber carries. During a Final Strike, a bomber must target only one player.

Gamehelpnuclearwar

2026-03-16T00:25:17Z

BaronFraser: /* Nuclear Escalation Die Roll Results */

== Introduction ==

The atomic bomb has been invented. Nations are building up their stockpiles of atomic bombs while vying for the hearts and minds of their rivals’ populace. Welcome to the world of Nuclear War!

The game begins with an uneasy cold war between all the players, each representing a nuclear power. Once the first player launches a nuclear warhead, the war turns hot as populations decrease in huge balls of nuclear fire. Will there be any nation left when the last bomb has fallen?

== Object ==

In Nuclear War players seek world domination by eliminating the other major powers. This can be accomplished in two ways:

* The peaceful way is to persuade the populations of opposing countries to join your superior form of government through the use of propaganda cards.
* The warlike way is to destroy the enemy’s population by using nuclear weapons.

Population is the measure of success or failure in the game. A player who loses their entire population is eliminated. The last player with population wins the game, but sometimes everyone is engulfed in flames and there are only losers.

== Set Up ==

# Shuffle the population cards. Based on the player count, deal each player the following number of cards: 2 players: 15 cards; 3 players: 10 cards; 4 players: 8 cards; 5 players: 7 cards; 6+ players: 6 cards. Deal these cards face down. Only you may look at your population cards.
# Place the remaining population cards in a face up stack in the middle of the table forming a bank. Players may use the bank to make ‘change’ only when they are forced to lose population.
# Shuffle the Nuclear War cards and deal 9 face-down to each player. You may examine your cards but not other player’s.
# Place the remaining Nuclear War cards in a face-down stack in the middle of the table. This is a draw deck.
# The first player is randomly chosen. Play will proceed clockwise around the table from the first player.
# The first player examines their cards for any secrets and top secrets. If they have any, they play them. Once the first player has a hand with no secrets, the next player in turn declares and plays secrets. Continue this around the table until no one has any secrets left!

'''NOTE''': '''Spies!''' To play a '''secret''' you announce that you have a secret, then give each other player a moment to decide if they want to play a spy. If no one plays a '''spy''', reveal and resolve the secret. Repeat this process every time you play a secret.

7: All players, at the same time, choose and place 1 card facedown in each of the two face-down slots on their playmat. These are the cards that will be played on your first and second turn respectively!
8: Now you are ready to play! The first player takes the first turn.

== Overview of Gameplay ==

On your turn you will:

* Draw cards until you have 8 in your hand.
* Play secrets and draw replacement cards until no secrets are in hand.
* Move the cards on your launch track forward to the next box
* Place a card into the 2nd face-down slot
* Reveal the card in the face-up slot and play it.

== War and Peace ==

Nuclear War has two game states - '''Peacetime''' and '''War'''. The game state affects how some cards work.

The game starts in Peacetime. Once there is a successful launch of a delivery system with a warhead, whether or not the launch results in population loss, the game state changes to War.

The game state remains in War until one player is eliminated and has performed their final strike (see page 7). At that point, Peacetime begins again… until the next warhead is launched.

Whenever Peacetime begins all players pick up the face-down cards on their launch track (see below). They then replace those cards with any cards from their hand, including the cards they just picked up. Active delivery systems remain active.

== Components Overview ==

=== Launch Track ===

In Nuclear War, you must plan your moves two turns in advance using the Launch Track.

Your Launch track is three spaces. The face-up space is for the card you are using this turn. The first face-down card is the card you will use next turn, and the second face-down space is the card you will play two turns from now.

'''2nd Face Down Card''' -> '''1st Face Down Card''' -> '''FACE UP CARD'''

You may look at facedown cards on your Launch Track whenever you want. You cannot change the order, or discard cards. Once you play a card to your Launch Track it is locked in!

Your Launch Track may only have delivery systems, warheads, and propaganda cards on it. If you ever reveal a card that is not a delivery system, warhead, or propaganda card, it is discarded without effect. This counts as your turn!

If your launch track is ever empty you must fill it immediately, if you don’t have enough eligible cards in your hand you must fill it on your next turn during the Play a Card step

== Card Types ==

=== Propagandas ===

During Peacetime, propaganda cards are used to steal population from other players (ie, the population defects to your nation). During Wartime, some propaganda cards allow you to draw new cards from the deck.

Whenever you steal population with a propaganda card, if the player doesn’t have enough population to give you, they give all their remaining population, and then they are eliminated from the game.

=== Delivery Systems ===

In order to launch a warhead in Nuclear Destruction, you need to have an appropriate delivery system.

Delivery systems are played in your launch track before a warhead. To launch a warhead, first, you must reveal a delivery system, and in the subsequent turn, reveal a warhead to go with that delivery system. If any card follows a delivery system that isn’t compatible with that delivery system, the delivery system will be discarded.

There are two main types of delivery systems: bombers and missiles. The two types of delivery systems work slightly differently when they are launched. For resolving a launch, see the Attacking the Enemy section.

The '''evasion rating''' on delivery systems determines how vulnerable they are to Anti-Missile cards. The Evasion rating has a letter, either M(Missile) or B(Bomber), and a number. See Anti-Missile cards (below) for details on evading a launch.

'''NOTE:''' If you shoot down a delivery system with an anti-missile, you play next, skipping all the players between.

==== Missiles ====

Missile delivery systems can carry one warhead up to a maximum megatonnage listed on the card.

'''''Example:''' An East Wind-DS31 Missile may carry a single warhead of up to 25 Megatons.''

Launching a missile requires playing the missile, and on the next turn, following it with a warhead of an appropriate size. After launching a missile it, and the warhead it carried, are discarded.

==== Bombers ====

Bombers are launched just like missiles: you reveal one and on the next turn reveal a warhead with low enough tonnage to be carried by it. Unlike missiles, a bomber is not discarded after delivering a payload. Instead, a bomber may deliver multiple warheads, each on its own turn, until the total megatonnage of war-heads delivered equals the bomber rating.

Bombers may bomb different enemy powers on different turns, flying over to the offending country. You do not discard a warhead delivered by a bomber. Instead, place the warhead under the bomber with its megatonnage showing so you can keep track of the megatonnage that the bomber has used. You only discard the warheads delivered by a bomber when the bomber is discarded. If you reveal a warhead that doesn’t fit the bomber, the warhead, the bomber, and all warheads under the bomber, are immediately discarded.

'''''Example:''' On The first turn, Ed launches the B-58 Bomber, which carries up to 60 mega-tons of warheads. On the next turn, Ed reveals a 20-megaton warhead. After resolving the strike, the 20-megaton warhead is kept with the B-58 Bomber. On the following turn, Ed reveals a 10-megaton warhead, this again is stacked with the bomber after resolving. In the next turn Ed reveals a 40-megaton warhead, this exceeds the bombers max-imum tonnage, and so the bomber along with all three warheads are discarded. The 40-megaton warhead would have no effect.''

==== Warheads ====

Warhead cards are played after a delivery system on the launch track. Warhead cards are rated by megatonnage, and how much population they destroy. The megatonnage is a limit to certain delivery systems, A larger megaton warhead that follows a delivery system not capable of carrying it is discarded along with the delivery system without effect. If the warhead fits on the delivery system played before it, the warhead has successfully launched and can target any other player. See Attacking a Player.

==== Anti Missiles ====

Anti-Missiles are reactive cards. They are played directly out of your hand when another player targets you with a warhead. When a delivery system targets you, you may discard an anti-missile to shoot down the delivery system. All anti-missiles are rated for what they will shoot down. Anti-Missiles have two ratings, one for Bombers (B) and one for Missiles (M). If the rating of the anti-missile is equal to or higher than the evasion rating of the incoming delivery system, the anti-missile can shoot it down.

If you cannot shoot down the incoming delivery system, you may not play an anti-missile. You may not use an anti-missile to help another player. You may only shoot down delivery systems targeting you.

When you successfully use an anti-missile, it becomes your turn, skipping all other players. Play continues clockwise after you have finished your turn.

==== Secrets and Top Secrets ====

Secrets are resolved, one at a time, when drawn, and do not go through the launch track. When drawn, announce you have a secret, as it may be stolen by a Spy. If it isn't stolen, play it. Each secret is a random event that has an effect on the game. Resolve the text, and then draw a replacement card. If the replacement is also a secret, resolve that one, and draw another replacement, continue to resolve secrets until a non-secret is drawn. If you have more than one secret in your hand, you choose which secret or top secret to resolve first. Top Secrets are resolved the same way as secrets, with the exception you have to announce it is a Top Secret. Top Secrets tend to be more powerful.

'''SECRETS!''' Secrets can be good or bad. When you draw a secret it is played before you begin your turn. Remember to give your opponents a chance to steal it before revealing the secret and resolving it!

==== Specials ====

Special cards are cards that are played out of your hand. Each Special explains when it may be played and what it does when you play it.

==== Hybrid Cards ====

Hybrid cards show both a warhead and a delivery system. When a hybrid card is revealed the revealing player decides which option to use. After choosing which option, the card is considered to be that type until discarded.

== Game Turn in Detail ==

=== Draw Cards ===

At the start of your turn, draw cards until you have 8 cards in hand.

If you have a secret in your hand you must announce you have a secret, and if no Spy steals it, then read it aloud and resolve the effects of the secret. If you draw more than one secret, you must play all of them, but you choose the order you play them. Whenever you play a secret or have it stolen from you, you draw a replacement card.

=== Play a Card ===

After drawing, slide your cards along the launch track pushing the first face-down card to the face-up card space, and the second face-down card to the first face-down card space. After sliding your cards over, place another card from your hand, face-down, onto the second face-down space.

=== Reveal a Card ===

Reveal and resolve the card in the face-up space. If the card is a propaganda card use the appropriate effect depending on whether it is Peacetime or War.

If it is a delivery system, place it in your active delivery system space, discarding any delivery system already there.

If it is a warhead, and there is a delivery system in your active delivery system space that can hold the warhead, congratulations, you’ve launched a nuke! Place the warhead on the active delivery system and Attack an Enemy! If the game state is Peacetime, it is now War!

If you did not launch a nuke, the next player in turn order takes their turn starting from step 1. If you did, once the attack is resolved – as long as no anti-missiles change whose turn it is – the next player in turn order takes their turn starting from step 1.

=== Attacking the Enemy ===

If you have launched a warhead, choose a target player. Then follow the steps below to resolve the strike:

# The target may use an anti-missile or a Saboteur to shoot down the delivery system or foil the launch. If they do, discard your delivery system and any of your warhead(s) that are face-up.
# If a launch is stopped by an anti-missile (not a Saboteur) the player that used the anti-missile immediately takes their turn, skipping all the players between the launching player and the target.
# If the target does not stop the attack, spin the spinner to find out the extra effects of the nuclear strike.
# You may roll the Nuclear Escalation die. If you do, add the amount rolled to the total population loss. If a Nuclear Cloud is rolled, roll on the malfunction chart.

The target then discards the amount of population equal to the damage dealt by the warhead. The target player may make change from unused population cards if needed. If the target does not have enough population, they are eliminated and they may make a final strike!

'''''Example:''' Trent takes 22 Million damage from a warhead, and discards a 25 Million population card, taking a 2 million and a 1 million population card from the unused population cards.''

# If the delivery system is a missile, discard the missile and warhead. If it is a bomber, only discard the bomber and warhead(s) if the total megatonnage of warheads on the bomber equals or exceeds its maximum tonnage.

==== Spinner Results ====

'''Radioactive Beta Rays Kill another 5 million.''' Add 5 million to the population loss on the warhead.

'''An additional 1 million are engulfed in the fireball.''' Add 1 million to the population loss on the warhead.

'''Dirty Bomb! Double the Yield.''' Double the population loss listed on the warhead. If the warhead is a 200 megaton warhead or larger, the world blows up, spreading nuclear fallout throughout the solar system and everyone loses. Smooth move!

'''No Appreciable Radiation Fallout.''' No extra effect, use the amount of population loss listed on the warhead.

'''Explodes a Nuclear Stockpile Triple the Yield.''' Triple the population loss listed on the warhead. If the warhead is 100 Megatons or more the world blows up in a massive chain reaction, spreading radioactive fallout throughout the solar system and everyone loses! Welcome to the new asteroid belt.

'''Bomb Shelters Save 2 Million.''' Reduce the amount of population loss by 2 million on the warhead. If this results in less than zero loss, treat it as a zero loss.

'''Lethal Doses of Radioactive Gamma Rays Kill Another 10 Million.''' Add 10 million to the population loss on the warhead.

'''Dud Warhead! (No Effect).''' Place the warhead on the delivery system without effect. Your attack ends, it is now the next player’s turn.

'''Radioactive Fallout Kills Another 2 Million.''' Add 2 Million to the population loss on the warhead.

'''Missile Booster Explodes on Launch (or Bomber Runs Out of Fuel)''' Discard the delivery system and the warhead(s). Your attack ends, it is now the next player’s turn.

==== Nuclear Escalation Die Roll Results ====

'''Cloud: Disaster!''' You have somehow directed this warhead at one of your own cities. You lose the population rather than your target.

'''2: Orbital Burst!''' The warhead goes off in the atmosphere over your country! Discard your delivery system and all face-up warheads on your player mat. You skip your next turn!

'''3: Missile Booster Explodes on Launch''' (or a Bomber Runs out of fuel) Discard the Delivery system and the warhead(s). Your attack ends and it is now the next player's turn.

'''4: This Warhead is a dud.''' Place the warhead on its delivery system without effect. Your attack ends and it is the next player's turn.

'''5: Neutron Bomb! Double the yield.''' Double the population loss listed on the warhead.

'''6: You hit a nuclear power plant.''' You do double damage, and your opponent misses one turn! Double the population loss listed on the warhead. Remind your opponent to skip their next turn.

=== Player Elimination and Final Strike ===

If you lose all of your population, you have been eliminated from the game.

If you’ve been eliminated through propaganda, you are out of the game, and the other players continue playing the game until there is a winner, or everyone loses.

If you are eliminated through any other means (i.e. secrets, or nuclear attack) you have the option to launch a final strike. You may play all the cards in your hand and on your launch mat. Combining any eligible warhead with your delivery systems in any way you wish. Once you have combined all of your eligible delivery systems and warheads, you may launch them at any targets you wish. Resolve them one at a time, just as above.

Anti-missiles will shoot down a final strike target, but it will not stop the rest of your final strike. The same is true for any dud or failed launch from the spinner.

The player to last play an anti-missile during the final strike will become the next player, otherwise, play continues clockwise. The exception is if another player is eliminated during a final strike, in which case they perform their final strike immediately after the first final strike is finished.

It is possible that a chain reaction of final strikes will '''eliminate all''' remaining players. If this happens, everyone loses the game, just like a real nuclear war! Once a player is eliminated and has played their final strike, it becomes Peacetime.

''''Example:''' Trent has been eliminated and is planning out his final strike. He has 3 missiles and a bomber loaded with megatonnage. He looses his bomber on Brittany, who had eliminated him, but Brittany shoots it down with an anti-missile. Trent sighs and decides to send the rest of his missiles against Ed. Ed is eliminated and immediately begins his final strike, ignoring Brittanyâ€™s use of the anti-missile. If everyone left survives Ed's final strike, then Brittany will begin her turn, unless another player had played an anti-missile.

==== When Peace is Declared... ====

When it becomes Peacetime, you may pick up all your cards on the launch track and replace them with cards from your hand.

=== Winning the Ultimate Victory ===

If, after all final strikes, you are the only remaining player with population, You have “won” the game! Your remaining population will enjoy the nuclear winter that follows and begin to slowly rebuild civilization.

==== Deterrent Force ====

If you have a powerful weapon in your hand you may wish to display it in order to discourage an enemy attack. You may, as part of your turn, place one or two cards face up in the deterrent force area as shown on the launch mat. A Saturn missile and a 100-megaton warhead, for example, may cause an enemy to think twice before beginning a nuclear exchange.

Cards in your deterrent force area remain part of your hand and must be put into play in the same way as any other cards. Any specials or secrets that affect your hand also affect any cards in the deterrent force. You should pick up your deterrents before resolving a secret that affects your hand.

== Optional Rules ==

=== More people! ===

Before dealing starting populations, give each player one 25 million population card. Then deal one less population card to all the players.

=== Not so secretive! ===

If a player has more than two secrets dealt to them at the beginning, randomly choose two of them, return the rest to the bottom of the deck and draw replacements. If more secrets are drawn they are also put at the bottom of the deck and replaced.

=== Bombers aren’t quite as fast as Missiles! ===

When launching a Bomber you must target a player sitting next to you. After targeting that player you may fly to the player sitting next to the current target or stay on the current target with the next warhead the bomber carries. During a Final Strike, a bomber must target only one player.

Gamehelpnuclearwar

2026-03-16T00:24:48Z

BaronFraser: /* Spinner Results */

== Introduction ==

The atomic bomb has been invented. Nations are building up their stockpiles of atomic bombs while vying for the hearts and minds of their rivals’ populace. Welcome to the world of Nuclear War!

The game begins with an uneasy cold war between all the players, each representing a nuclear power. Once the first player launches a nuclear warhead, the war turns hot as populations decrease in huge balls of nuclear fire. Will there be any nation left when the last bomb has fallen?

== Object ==

In Nuclear War players seek world domination by eliminating the other major powers. This can be accomplished in two ways:

* The peaceful way is to persuade the populations of opposing countries to join your superior form of government through the use of propaganda cards.
* The warlike way is to destroy the enemy’s population by using nuclear weapons.

Population is the measure of success or failure in the game. A player who loses their entire population is eliminated. The last player with population wins the game, but sometimes everyone is engulfed in flames and there are only losers.

== Set Up ==

# Shuffle the population cards. Based on the player count, deal each player the following number of cards: 2 players: 15 cards; 3 players: 10 cards; 4 players: 8 cards; 5 players: 7 cards; 6+ players: 6 cards. Deal these cards face down. Only you may look at your population cards.
# Place the remaining population cards in a face up stack in the middle of the table forming a bank. Players may use the bank to make ‘change’ only when they are forced to lose population.
# Shuffle the Nuclear War cards and deal 9 face-down to each player. You may examine your cards but not other player’s.
# Place the remaining Nuclear War cards in a face-down stack in the middle of the table. This is a draw deck.
# The first player is randomly chosen. Play will proceed clockwise around the table from the first player.
# The first player examines their cards for any secrets and top secrets. If they have any, they play them. Once the first player has a hand with no secrets, the next player in turn declares and plays secrets. Continue this around the table until no one has any secrets left!

'''NOTE''': '''Spies!''' To play a '''secret''' you announce that you have a secret, then give each other player a moment to decide if they want to play a spy. If no one plays a '''spy''', reveal and resolve the secret. Repeat this process every time you play a secret.

7: All players, at the same time, choose and place 1 card facedown in each of the two face-down slots on their playmat. These are the cards that will be played on your first and second turn respectively!
8: Now you are ready to play! The first player takes the first turn.

== Overview of Gameplay ==

On your turn you will:

* Draw cards until you have 8 in your hand.
* Play secrets and draw replacement cards until no secrets are in hand.
* Move the cards on your launch track forward to the next box
* Place a card into the 2nd face-down slot
* Reveal the card in the face-up slot and play it.

== War and Peace ==

Nuclear War has two game states - '''Peacetime''' and '''War'''. The game state affects how some cards work.

The game starts in Peacetime. Once there is a successful launch of a delivery system with a warhead, whether or not the launch results in population loss, the game state changes to War.

The game state remains in War until one player is eliminated and has performed their final strike (see page 7). At that point, Peacetime begins again… until the next warhead is launched.

Whenever Peacetime begins all players pick up the face-down cards on their launch track (see below). They then replace those cards with any cards from their hand, including the cards they just picked up. Active delivery systems remain active.

== Components Overview ==

=== Launch Track ===

In Nuclear War, you must plan your moves two turns in advance using the Launch Track.

Your Launch track is three spaces. The face-up space is for the card you are using this turn. The first face-down card is the card you will use next turn, and the second face-down space is the card you will play two turns from now.

'''2nd Face Down Card''' -> '''1st Face Down Card''' -> '''FACE UP CARD'''

You may look at facedown cards on your Launch Track whenever you want. You cannot change the order, or discard cards. Once you play a card to your Launch Track it is locked in!

Your Launch Track may only have delivery systems, warheads, and propaganda cards on it. If you ever reveal a card that is not a delivery system, warhead, or propaganda card, it is discarded without effect. This counts as your turn!

If your launch track is ever empty you must fill it immediately, if you don’t have enough eligible cards in your hand you must fill it on your next turn during the Play a Card step

== Card Types ==

=== Propagandas ===

During Peacetime, propaganda cards are used to steal population from other players (ie, the population defects to your nation). During Wartime, some propaganda cards allow you to draw new cards from the deck.

Whenever you steal population with a propaganda card, if the player doesn’t have enough population to give you, they give all their remaining population, and then they are eliminated from the game.

=== Delivery Systems ===

In order to launch a warhead in Nuclear Destruction, you need to have an appropriate delivery system.

Delivery systems are played in your launch track before a warhead. To launch a warhead, first, you must reveal a delivery system, and in the subsequent turn, reveal a warhead to go with that delivery system. If any card follows a delivery system that isn’t compatible with that delivery system, the delivery system will be discarded.

There are two main types of delivery systems: bombers and missiles. The two types of delivery systems work slightly differently when they are launched. For resolving a launch, see the Attacking the Enemy section.

The '''evasion rating''' on delivery systems determines how vulnerable they are to Anti-Missile cards. The Evasion rating has a letter, either M(Missile) or B(Bomber), and a number. See Anti-Missile cards (below) for details on evading a launch.

'''NOTE:''' If you shoot down a delivery system with an anti-missile, you play next, skipping all the players between.

==== Missiles ====

Missile delivery systems can carry one warhead up to a maximum megatonnage listed on the card.

'''''Example:''' An East Wind-DS31 Missile may carry a single warhead of up to 25 Megatons.''

Launching a missile requires playing the missile, and on the next turn, following it with a warhead of an appropriate size. After launching a missile it, and the warhead it carried, are discarded.

==== Bombers ====

Bombers are launched just like missiles: you reveal one and on the next turn reveal a warhead with low enough tonnage to be carried by it. Unlike missiles, a bomber is not discarded after delivering a payload. Instead, a bomber may deliver multiple warheads, each on its own turn, until the total megatonnage of war-heads delivered equals the bomber rating.

Bombers may bomb different enemy powers on different turns, flying over to the offending country. You do not discard a warhead delivered by a bomber. Instead, place the warhead under the bomber with its megatonnage showing so you can keep track of the megatonnage that the bomber has used. You only discard the warheads delivered by a bomber when the bomber is discarded. If you reveal a warhead that doesn’t fit the bomber, the warhead, the bomber, and all warheads under the bomber, are immediately discarded.

'''''Example:''' On The first turn, Ed launches the B-58 Bomber, which carries up to 60 mega-tons of warheads. On the next turn, Ed reveals a 20-megaton warhead. After resolving the strike, the 20-megaton warhead is kept with the B-58 Bomber. On the following turn, Ed reveals a 10-megaton warhead, this again is stacked with the bomber after resolving. In the next turn Ed reveals a 40-megaton warhead, this exceeds the bombers max-imum tonnage, and so the bomber along with all three warheads are discarded. The 40-megaton warhead would have no effect.''

==== Warheads ====

Warhead cards are played after a delivery system on the launch track. Warhead cards are rated by megatonnage, and how much population they destroy. The megatonnage is a limit to certain delivery systems, A larger megaton warhead that follows a delivery system not capable of carrying it is discarded along with the delivery system without effect. If the warhead fits on the delivery system played before it, the warhead has successfully launched and can target any other player. See Attacking a Player.

==== Anti Missiles ====

Anti-Missiles are reactive cards. They are played directly out of your hand when another player targets you with a warhead. When a delivery system targets you, you may discard an anti-missile to shoot down the delivery system. All anti-missiles are rated for what they will shoot down. Anti-Missiles have two ratings, one for Bombers (B) and one for Missiles (M). If the rating of the anti-missile is equal to or higher than the evasion rating of the incoming delivery system, the anti-missile can shoot it down.

If you cannot shoot down the incoming delivery system, you may not play an anti-missile. You may not use an anti-missile to help another player. You may only shoot down delivery systems targeting you.

When you successfully use an anti-missile, it becomes your turn, skipping all other players. Play continues clockwise after you have finished your turn.

==== Secrets and Top Secrets ====

Secrets are resolved, one at a time, when drawn, and do not go through the launch track. When drawn, announce you have a secret, as it may be stolen by a Spy. If it isn't stolen, play it. Each secret is a random event that has an effect on the game. Resolve the text, and then draw a replacement card. If the replacement is also a secret, resolve that one, and draw another replacement, continue to resolve secrets until a non-secret is drawn. If you have more than one secret in your hand, you choose which secret or top secret to resolve first. Top Secrets are resolved the same way as secrets, with the exception you have to announce it is a Top Secret. Top Secrets tend to be more powerful.

'''SECRETS!''' Secrets can be good or bad. When you draw a secret it is played before you begin your turn. Remember to give your opponents a chance to steal it before revealing the secret and resolving it!

==== Specials ====

Special cards are cards that are played out of your hand. Each Special explains when it may be played and what it does when you play it.

==== Hybrid Cards ====

Hybrid cards show both a warhead and a delivery system. When a hybrid card is revealed the revealing player decides which option to use. After choosing which option, the card is considered to be that type until discarded.

== Game Turn in Detail ==

=== Draw Cards ===

At the start of your turn, draw cards until you have 8 cards in hand.

If you have a secret in your hand you must announce you have a secret, and if no Spy steals it, then read it aloud and resolve the effects of the secret. If you draw more than one secret, you must play all of them, but you choose the order you play them. Whenever you play a secret or have it stolen from you, you draw a replacement card.

=== Play a Card ===

After drawing, slide your cards along the launch track pushing the first face-down card to the face-up card space, and the second face-down card to the first face-down card space. After sliding your cards over, place another card from your hand, face-down, onto the second face-down space.

=== Reveal a Card ===

Reveal and resolve the card in the face-up space. If the card is a propaganda card use the appropriate effect depending on whether it is Peacetime or War.

If it is a delivery system, place it in your active delivery system space, discarding any delivery system already there.

If it is a warhead, and there is a delivery system in your active delivery system space that can hold the warhead, congratulations, you’ve launched a nuke! Place the warhead on the active delivery system and Attack an Enemy! If the game state is Peacetime, it is now War!

If you did not launch a nuke, the next player in turn order takes their turn starting from step 1. If you did, once the attack is resolved – as long as no anti-missiles change whose turn it is – the next player in turn order takes their turn starting from step 1.

=== Attacking the Enemy ===

If you have launched a warhead, choose a target player. Then follow the steps below to resolve the strike:

# The target may use an anti-missile or a Saboteur to shoot down the delivery system or foil the launch. If they do, discard your delivery system and any of your warhead(s) that are face-up.
# If a launch is stopped by an anti-missile (not a Saboteur) the player that used the anti-missile immediately takes their turn, skipping all the players between the launching player and the target.
# If the target does not stop the attack, spin the spinner to find out the extra effects of the nuclear strike.
# You may roll the Nuclear Escalation die. If you do, add the amount rolled to the total population loss. If a Nuclear Cloud is rolled, roll on the malfunction chart.

The target then discards the amount of population equal to the damage dealt by the warhead. The target player may make change from unused population cards if needed. If the target does not have enough population, they are eliminated and they may make a final strike!

'''''Example:''' Trent takes 22 Million damage from a warhead, and discards a 25 Million population card, taking a 2 million and a 1 million population card from the unused population cards.''

# If the delivery system is a missile, discard the missile and warhead. If it is a bomber, only discard the bomber and warhead(s) if the total megatonnage of warheads on the bomber equals or exceeds its maximum tonnage.

==== Spinner Results ====

'''Radioactive Beta Rays Kill another 5 million.''' Add 5 million to the population loss on the warhead.

'''An additional 1 million are engulfed in the fireball.''' Add 1 million to the population loss on the warhead.

'''Dirty Bomb! Double the Yield.''' Double the population loss listed on the warhead. If the warhead is a 200 megaton warhead or larger, the world blows up, spreading nuclear fallout throughout the solar system and everyone loses. Smooth move!

'''No Appreciable Radiation Fallout.''' No extra effect, use the amount of population loss listed on the warhead.

'''Explodes a Nuclear Stockpile Triple the Yield.''' Triple the population loss listed on the warhead. If the warhead is 100 Megatons or more the world blows up in a massive chain reaction, spreading radioactive fallout throughout the solar system and everyone loses! Welcome to the new asteroid belt.

'''Bomb Shelters Save 2 Million.''' Reduce the amount of population loss by 2 million on the warhead. If this results in less than zero loss, treat it as a zero loss.

'''Lethal Doses of Radioactive Gamma Rays Kill Another 10 Million.''' Add 10 million to the population loss on the warhead.

'''Dud Warhead! (No Effect).''' Place the warhead on the delivery system without effect. Your attack ends, it is now the next player’s turn.

'''Radioactive Fallout Kills Another 2 Million.''' Add 2 Million to the population loss on the warhead.

'''Missile Booster Explodes on Launch (or Bomber Runs Out of Fuel)''' Discard the delivery system and the warhead(s). Your attack ends, it is now the next player’s turn.

==== Nuclear Escalation Die Roll Results ====

'''Cloud: Disaster!''' You have somehow directed this warhead at one of your own cities. You lose the population rather than your target.
'''2: Orbital Burst!''' The warhead goes off in the atmosphere over your country! Discard your delivery system and all face-up warheads on your player mat. You skip your next turn!
'''3: Missile Booster Explodes on Launch''' (or a Bomber Runs out of fuel) Discard the Delivery system and the warhead(s). Your attack ends and it is now the next playerâ€™s turn.
'''4: This Warhead is a dud.''' Place the warhead on its delivery system without effect. Your attack ends and it is the next playerâ€™s turn.
'''5: Neutron Bomb! Double the yield.''' Double the population loss listed on the warhead.
'''6: You hit a nuclear power plant.''' You do double damage, and your opponent misses one turn! Double the population loss listed on the warhead. Remind your opponent to skip their next turn.

=== Player Elimination and Final Strike ===

If you lose all of your population, you have been eliminated from the game.

If you’ve been eliminated through propaganda, you are out of the game, and the other players continue playing the game until there is a winner, or everyone loses.

If you are eliminated through any other means (i.e. secrets, or nuclear attack) you have the option to launch a final strike. You may play all the cards in your hand and on your launch mat. Combining any eligible warhead with your delivery systems in any way you wish. Once you have combined all of your eligible delivery systems and warheads, you may launch them at any targets you wish. Resolve them one at a time, just as above.

Anti-missiles will shoot down a final strike target, but it will not stop the rest of your final strike. The same is true for any dud or failed launch from the spinner.

The player to last play an anti-missile during the final strike will become the next player, otherwise, play continues clockwise. The exception is if another player is eliminated during a final strike, in which case they perform their final strike immediately after the first final strike is finished.

It is possible that a chain reaction of final strikes will '''eliminate all''' remaining players. If this happens, everyone loses the game, just like a real nuclear war! Once a player is eliminated and has played their final strike, it becomes Peacetime.

''''Example:''' Trent has been eliminated and is planning out his final strike. He has 3 missiles and a bomber loaded with megatonnage. He looses his bomber on Brittany, who had eliminated him, but Brittany shoots it down with an anti-missile. Trent sighs and decides to send the rest of his missiles against Ed. Ed is eliminated and immediately begins his final strike, ignoring Brittanyâ€™s use of the anti-missile. If everyone left survives Ed's final strike, then Brittany will begin her turn, unless another player had played an anti-missile.

==== When Peace is Declared... ====

When it becomes Peacetime, you may pick up all your cards on the launch track and replace them with cards from your hand.

=== Winning the Ultimate Victory ===

If, after all final strikes, you are the only remaining player with population, You have “won” the game! Your remaining population will enjoy the nuclear winter that follows and begin to slowly rebuild civilization.

==== Deterrent Force ====

If you have a powerful weapon in your hand you may wish to display it in order to discourage an enemy attack. You may, as part of your turn, place one or two cards face up in the deterrent force area as shown on the launch mat. A Saturn missile and a 100-megaton warhead, for example, may cause an enemy to think twice before beginning a nuclear exchange.

Cards in your deterrent force area remain part of your hand and must be put into play in the same way as any other cards. Any specials or secrets that affect your hand also affect any cards in the deterrent force. You should pick up your deterrents before resolving a secret that affects your hand.

== Optional Rules ==

=== More people! ===

Before dealing starting populations, give each player one 25 million population card. Then deal one less population card to all the players.

=== Not so secretive! ===

If a player has more than two secrets dealt to them at the beginning, randomly choose two of them, return the rest to the bottom of the deck and draw replacements. If more secrets are drawn they are also put at the bottom of the deck and replaced.

=== Bombers aren’t quite as fast as Missiles! ===

When launching a Bomber you must target a player sitting next to you. After targeting that player you may fly to the player sitting next to the current target or stay on the current target with the next warhead the bomber carries. During a Final Strike, a bomber must target only one player.

Gamehelpnuclearwar

2026-03-16T00:23:25Z

BaronFraser: /* Nuclear War */

== Introduction ==

The atomic bomb has been invented. Nations are building up their stockpiles of atomic bombs while vying for the hearts and minds of their rivals’ populace. Welcome to the world of Nuclear War!

The game begins with an uneasy cold war between all the players, each representing a nuclear power. Once the first player launches a nuclear warhead, the war turns hot as populations decrease in huge balls of nuclear fire. Will there be any nation left when the last bomb has fallen?

== Object ==

In Nuclear War players seek world domination by eliminating the other major powers. This can be accomplished in two ways:

* The peaceful way is to persuade the populations of opposing countries to join your superior form of government through the use of propaganda cards.
* The warlike way is to destroy the enemy’s population by using nuclear weapons.

Population is the measure of success or failure in the game. A player who loses their entire population is eliminated. The last player with population wins the game, but sometimes everyone is engulfed in flames and there are only losers.

== Set Up ==

# Shuffle the population cards. Based on the player count, deal each player the following number of cards: 2 players: 15 cards; 3 players: 10 cards; 4 players: 8 cards; 5 players: 7 cards; 6+ players: 6 cards. Deal these cards face down. Only you may look at your population cards.
# Place the remaining population cards in a face up stack in the middle of the table forming a bank. Players may use the bank to make ‘change’ only when they are forced to lose population.
# Shuffle the Nuclear War cards and deal 9 face-down to each player. You may examine your cards but not other player’s.
# Place the remaining Nuclear War cards in a face-down stack in the middle of the table. This is a draw deck.
# The first player is randomly chosen. Play will proceed clockwise around the table from the first player.
# The first player examines their cards for any secrets and top secrets. If they have any, they play them. Once the first player has a hand with no secrets, the next player in turn declares and plays secrets. Continue this around the table until no one has any secrets left!

'''NOTE''': '''Spies!''' To play a '''secret''' you announce that you have a secret, then give each other player a moment to decide if they want to play a spy. If no one plays a '''spy''', reveal and resolve the secret. Repeat this process every time you play a secret.

7: All players, at the same time, choose and place 1 card facedown in each of the two face-down slots on their playmat. These are the cards that will be played on your first and second turn respectively!
8: Now you are ready to play! The first player takes the first turn.

== Overview of Gameplay ==

On your turn you will:

* Draw cards until you have 8 in your hand.
* Play secrets and draw replacement cards until no secrets are in hand.
* Move the cards on your launch track forward to the next box
* Place a card into the 2nd face-down slot
* Reveal the card in the face-up slot and play it.

== War and Peace ==

Nuclear War has two game states - '''Peacetime''' and '''War'''. The game state affects how some cards work.

The game starts in Peacetime. Once there is a successful launch of a delivery system with a warhead, whether or not the launch results in population loss, the game state changes to War.

The game state remains in War until one player is eliminated and has performed their final strike (see page 7). At that point, Peacetime begins again… until the next warhead is launched.

Whenever Peacetime begins all players pick up the face-down cards on their launch track (see below). They then replace those cards with any cards from their hand, including the cards they just picked up. Active delivery systems remain active.

== Components Overview ==

=== Launch Track ===

In Nuclear War, you must plan your moves two turns in advance using the Launch Track.

Your Launch track is three spaces. The face-up space is for the card you are using this turn. The first face-down card is the card you will use next turn, and the second face-down space is the card you will play two turns from now.

'''2nd Face Down Card''' -> '''1st Face Down Card''' -> '''FACE UP CARD'''

You may look at facedown cards on your Launch Track whenever you want. You cannot change the order, or discard cards. Once you play a card to your Launch Track it is locked in!

Your Launch Track may only have delivery systems, warheads, and propaganda cards on it. If you ever reveal a card that is not a delivery system, warhead, or propaganda card, it is discarded without effect. This counts as your turn!

If your launch track is ever empty you must fill it immediately, if you don’t have enough eligible cards in your hand you must fill it on your next turn during the Play a Card step

== Card Types ==

=== Propagandas ===

During Peacetime, propaganda cards are used to steal population from other players (ie, the population defects to your nation). During Wartime, some propaganda cards allow you to draw new cards from the deck.

Whenever you steal population with a propaganda card, if the player doesn’t have enough population to give you, they give all their remaining population, and then they are eliminated from the game.

=== Delivery Systems ===

In order to launch a warhead in Nuclear Destruction, you need to have an appropriate delivery system.

Delivery systems are played in your launch track before a warhead. To launch a warhead, first, you must reveal a delivery system, and in the subsequent turn, reveal a warhead to go with that delivery system. If any card follows a delivery system that isn’t compatible with that delivery system, the delivery system will be discarded.

There are two main types of delivery systems: bombers and missiles. The two types of delivery systems work slightly differently when they are launched. For resolving a launch, see the Attacking the Enemy section.

The '''evasion rating''' on delivery systems determines how vulnerable they are to Anti-Missile cards. The Evasion rating has a letter, either M(Missile) or B(Bomber), and a number. See Anti-Missile cards (below) for details on evading a launch.

'''NOTE:''' If you shoot down a delivery system with an anti-missile, you play next, skipping all the players between.

==== Missiles ====

Missile delivery systems can carry one warhead up to a maximum megatonnage listed on the card.

'''''Example:''' An East Wind-DS31 Missile may carry a single warhead of up to 25 Megatons.''

Launching a missile requires playing the missile, and on the next turn, following it with a warhead of an appropriate size. After launching a missile it, and the warhead it carried, are discarded.

==== Bombers ====

Bombers are launched just like missiles: you reveal one and on the next turn reveal a warhead with low enough tonnage to be carried by it. Unlike missiles, a bomber is not discarded after delivering a payload. Instead, a bomber may deliver multiple warheads, each on its own turn, until the total megatonnage of war-heads delivered equals the bomber rating.

Bombers may bomb different enemy powers on different turns, flying over to the offending country. You do not discard a warhead delivered by a bomber. Instead, place the warhead under the bomber with its megatonnage showing so you can keep track of the megatonnage that the bomber has used. You only discard the warheads delivered by a bomber when the bomber is discarded. If you reveal a warhead that doesn’t fit the bomber, the warhead, the bomber, and all warheads under the bomber, are immediately discarded.

'''''Example:''' On The first turn, Ed launches the B-58 Bomber, which carries up to 60 mega-tons of warheads. On the next turn, Ed reveals a 20-megaton warhead. After resolving the strike, the 20-megaton warhead is kept with the B-58 Bomber. On the following turn, Ed reveals a 10-megaton warhead, this again is stacked with the bomber after resolving. In the next turn Ed reveals a 40-megaton warhead, this exceeds the bombers max-imum tonnage, and so the bomber along with all three warheads are discarded. The 40-megaton warhead would have no effect.''

==== Warheads ====

Warhead cards are played after a delivery system on the launch track. Warhead cards are rated by megatonnage, and how much population they destroy. The megatonnage is a limit to certain delivery systems, A larger megaton warhead that follows a delivery system not capable of carrying it is discarded along with the delivery system without effect. If the warhead fits on the delivery system played before it, the warhead has successfully launched and can target any other player. See Attacking a Player.

==== Anti Missiles ====

Anti-Missiles are reactive cards. They are played directly out of your hand when another player targets you with a warhead. When a delivery system targets you, you may discard an anti-missile to shoot down the delivery system. All anti-missiles are rated for what they will shoot down. Anti-Missiles have two ratings, one for Bombers (B) and one for Missiles (M). If the rating of the anti-missile is equal to or higher than the evasion rating of the incoming delivery system, the anti-missile can shoot it down.

If you cannot shoot down the incoming delivery system, you may not play an anti-missile. You may not use an anti-missile to help another player. You may only shoot down delivery systems targeting you.

When you successfully use an anti-missile, it becomes your turn, skipping all other players. Play continues clockwise after you have finished your turn.

==== Secrets and Top Secrets ====

Secrets are resolved, one at a time, when drawn, and do not go through the launch track. When drawn, announce you have a secret, as it may be stolen by a Spy. If it isn't stolen, play it. Each secret is a random event that has an effect on the game. Resolve the text, and then draw a replacement card. If the replacement is also a secret, resolve that one, and draw another replacement, continue to resolve secrets until a non-secret is drawn. If you have more than one secret in your hand, you choose which secret or top secret to resolve first. Top Secrets are resolved the same way as secrets, with the exception you have to announce it is a Top Secret. Top Secrets tend to be more powerful.

'''SECRETS!''' Secrets can be good or bad. When you draw a secret it is played before you begin your turn. Remember to give your opponents a chance to steal it before revealing the secret and resolving it!

==== Specials ====

Special cards are cards that are played out of your hand. Each Special explains when it may be played and what it does when you play it.

==== Hybrid Cards ====

Hybrid cards show both a warhead and a delivery system. When a hybrid card is revealed the revealing player decides which option to use. After choosing which option, the card is considered to be that type until discarded.

== Game Turn in Detail ==

=== Draw Cards ===

At the start of your turn, draw cards until you have 8 cards in hand.

If you have a secret in your hand you must announce you have a secret, and if no Spy steals it, then read it aloud and resolve the effects of the secret. If you draw more than one secret, you must play all of them, but you choose the order you play them. Whenever you play a secret or have it stolen from you, you draw a replacement card.

=== Play a Card ===

After drawing, slide your cards along the launch track pushing the first face-down card to the face-up card space, and the second face-down card to the first face-down card space. After sliding your cards over, place another card from your hand, face-down, onto the second face-down space.

=== Reveal a Card ===

Reveal and resolve the card in the face-up space. If the card is a propaganda card use the appropriate effect depending on whether it is Peacetime or War.

If it is a delivery system, place it in your active delivery system space, discarding any delivery system already there.

If it is a warhead, and there is a delivery system in your active delivery system space that can hold the warhead, congratulations, you’ve launched a nuke! Place the warhead on the active delivery system and Attack an Enemy! If the game state is Peacetime, it is now War!

If you did not launch a nuke, the next player in turn order takes their turn starting from step 1. If you did, once the attack is resolved – as long as no anti-missiles change whose turn it is – the next player in turn order takes their turn starting from step 1.

=== Attacking the Enemy ===

If you have launched a warhead, choose a target player. Then follow the steps below to resolve the strike:

# The target may use an anti-missile or a Saboteur to shoot down the delivery system or foil the launch. If they do, discard your delivery system and any of your warhead(s) that are face-up.
# If a launch is stopped by an anti-missile (not a Saboteur) the player that used the anti-missile immediately takes their turn, skipping all the players between the launching player and the target.
# If the target does not stop the attack, spin the spinner to find out the extra effects of the nuclear strike.
# You may roll the Nuclear Escalation die. If you do, add the amount rolled to the total population loss. If a Nuclear Cloud is rolled, roll on the malfunction chart.

The target then discards the amount of population equal to the damage dealt by the warhead. The target player may make change from unused population cards if needed. If the target does not have enough population, they are eliminated and they may make a final strike!

'''''Example:''' Trent takes 22 Million damage from a warhead, and discards a 25 Million population card, taking a 2 million and a 1 million population card from the unused population cards.''

# If the delivery system is a missile, discard the missile and warhead. If it is a bomber, only discard the bomber and warhead(s) if the total megatonnage of warheads on the bomber equals or exceeds its maximum tonnage.

==== Spinner Results ====

===== Radioactive Beta Rays Kill another 5 million. =====
Add 5 million to the population loss on the warhead.

===== An additional 1 million are engulfed in the fireball. =====
Add 1 million to the population loss on the warhead.

===== Dirty Bomb! Double the Yield. =====
Double the population loss listed on the warhead. If the warhead is a 200 megaton warhead or larger, the world blows up, spreading nuclear fallout throughout the solar system and everyone loses. Smooth move!

===== No Appreciable Radiation Fallout. =====
No extra effect, use the amount of population loss listed on the warhead.

===== Explodes a Nuclear Stockpile Triple the Yield. =====
Triple the population loss listed on the warhead. If the warhead is 100 Megatons or more the world blows up in a massive chain reaction, spreading radioactive fallout throughout the solar system and everyone loses! Welcome to the new asteroid belt.

===== Bomb Shelters Save 2 Million. =====
Reduce the amount of population loss by 2 million on the warhead. If this results in less than zero loss, treat it as a zero loss.

===== Lethal Doses of Radioactive Gamma Rays Kill Another 10 Million. =====
Add 10 million to the population loss on the warhead.

===== Dud Warhead! (No Effect). =====
Place the warhead on the delivery system without effect. Your attack ends, it is now the next player’s turn.

===== Radioactive Fallout Kills Another 2 Million. =====
Add 2 Million to the population loss on the warhead.

===== Missile Booster Explodes on Launch (or Bomber Runs Out of Fuel) =====
Discard the delivery system and the warhead(s). Your attack ends, it is now the next player’s turn.

==== Nuclear Escalation Die Roll Results ====

'''Cloud: Disaster!''' You have somehow directed this warhead at one of your own cities. You lose the population rather than your target.
'''2: Orbital Burst!''' The warhead goes off in the atmosphere over your country! Discard your delivery system and all face-up warheads on your player mat. You skip your next turn!
'''3: Missile Booster Explodes on Launch''' (or a Bomber Runs out of fuel) Discard the Delivery system and the warhead(s). Your attack ends and it is now the next playerâ€™s turn.
'''4: This Warhead is a dud.''' Place the warhead on its delivery system without effect. Your attack ends and it is the next playerâ€™s turn.
'''5: Neutron Bomb! Double the yield.''' Double the population loss listed on the warhead.
'''6: You hit a nuclear power plant.''' You do double damage, and your opponent misses one turn! Double the population loss listed on the warhead. Remind your opponent to skip their next turn.

=== Player Elimination and Final Strike ===

If you lose all of your population, you have been eliminated from the game.

If you’ve been eliminated through propaganda, you are out of the game, and the other players continue playing the game until there is a winner, or everyone loses.

If you are eliminated through any other means (i.e. secrets, or nuclear attack) you have the option to launch a final strike. You may play all the cards in your hand and on your launch mat. Combining any eligible warhead with your delivery systems in any way you wish. Once you have combined all of your eligible delivery systems and warheads, you may launch them at any targets you wish. Resolve them one at a time, just as above.

Anti-missiles will shoot down a final strike target, but it will not stop the rest of your final strike. The same is true for any dud or failed launch from the spinner.

The player to last play an anti-missile during the final strike will become the next player, otherwise, play continues clockwise. The exception is if another player is eliminated during a final strike, in which case they perform their final strike immediately after the first final strike is finished.

It is possible that a chain reaction of final strikes will '''eliminate all''' remaining players. If this happens, everyone loses the game, just like a real nuclear war! Once a player is eliminated and has played their final strike, it becomes Peacetime.

''''Example:''' Trent has been eliminated and is planning out his final strike. He has 3 missiles and a bomber loaded with megatonnage. He looses his bomber on Brittany, who had eliminated him, but Brittany shoots it down with an anti-missile. Trent sighs and decides to send the rest of his missiles against Ed. Ed is eliminated and immediately begins his final strike, ignoring Brittanyâ€™s use of the anti-missile. If everyone left survives Ed's final strike, then Brittany will begin her turn, unless another player had played an anti-missile.

==== When Peace is Declared... ====

When it becomes Peacetime, you may pick up all your cards on the launch track and replace them with cards from your hand.

=== Winning the Ultimate Victory ===

If, after all final strikes, you are the only remaining player with population, You have “won” the game! Your remaining population will enjoy the nuclear winter that follows and begin to slowly rebuild civilization.

==== Deterrent Force ====

If you have a powerful weapon in your hand you may wish to display it in order to discourage an enemy attack. You may, as part of your turn, place one or two cards face up in the deterrent force area as shown on the launch mat. A Saturn missile and a 100-megaton warhead, for example, may cause an enemy to think twice before beginning a nuclear exchange.

Cards in your deterrent force area remain part of your hand and must be put into play in the same way as any other cards. Any specials or secrets that affect your hand also affect any cards in the deterrent force. You should pick up your deterrents before resolving a secret that affects your hand.

== Optional Rules ==

=== More people! ===

Before dealing starting populations, give each player one 25 million population card. Then deal one less population card to all the players.

=== Not so secretive! ===

If a player has more than two secrets dealt to them at the beginning, randomly choose two of them, return the rest to the bottom of the deck and draw replacements. If more secrets are drawn they are also put at the bottom of the deck and replaced.

=== Bombers aren’t quite as fast as Missiles! ===

When launching a Bomber you must target a player sitting next to you. After targeting that player you may fly to the player sitting next to the current target or stay on the current target with the next warhead the bomber carries. During a Final Strike, a bomber must target only one player.

Gamehelpformulad

2026-03-02T21:29:12Z

BaronFraser: /* BGA Rule Variations */

= 10-Second Explainer of Formula D =
New to Formula D?

This 10-second explainer will get you started:

# Your car will start in 1st gear.
# At the start of your turn, your first decision is whether to stay on your current gear, or go up 1 gear or go down 1 gear.
# You can go down 1 gear without penalty, or "skip" up to 3 gears at the cost of wear points. You may only go up by 1 gear per turn.
# After choosing a gear, you will roll the appropriate "gear die". The higher the gear, the bigger the die, as well as the farther you go.
# Once you have rolled, you must move the number of spaces rolled, although you may choose which lane you take.
# Corners are areas marked in red. To drive around corners without penalty, you must finish at least 1 turn in them.
# Some corners are particularly slow and may require that you finish at least 2 or even 3 turns in them.

That's it! There's a lot more to it than that, but this covers the absolute basics of driving safely around the track.

= Important: BGA Rule Variations =

The BGA Adaptation of Formula D uses a number of variations from the Masters (Tournament) rules.

[[#BGA Rule Variations|At the end of these rules]], you will find a list of all differences from the published game rules.

=Adaptation Notes/Common Mistakes=

# The body of your car is the colour of the pit box you are using (or your team's color if playing a team game)
# Your sidepods are your personal color
# To enter the pitbox, you must move out of the pit lane and onto the coloured pit box. Stopping in the pit lane in front of your box is not a pit stop.
# To zoom the circuit in and out with a mouse, use Ctrl+Wheel mouse.

=Basic Rules=

== (Basic Rules) Aim of the game ==

FORMULA D is a car race. The aim is to win a race (of one, two, or three laps) and be the first to cross the finishing line. There are all sorts of risks involved and you have to anticipate what will happen during the course of the race. You must decide on your strategy, trust to luck, keep to the rules and always keep an eye on the technical condition of your car.

== (Basic Rules) The gears ==

The cars have 6 gears. Each gear has its own die. The numbers on the dice tell you how many spaces to move the car. The higher the gear you choose, the faster and farther the corresponding die will allow the car to travel. You are not allowed to skip gears when accelerating (e.g. changing straight from 1st to 3rd gear). You are allowed to skip 1, 2 or 3 gears when braking (e.g. from 6th to 4th or from 4th to 1st gear); however there is a penalty for doing this. You cannot go from 6th gear to 1st.

{|
!Gear!! Color||Die||Movement (Number of spaces)
!Face distribution
|-
|1||Yellow||d4||1-2
|2 of each
|-
|2||Orange||d6||2-4
|2,3,3,4,4,4
|-
|3||Red||d8||4-8
|4,5,6,6,7,7,8,8
|-
|4||Green||d12||7-12
|2 of each
|-
|5||Purple||d20||11-20
|2 of each
|-
|6||Blue||d20||21-30
|2 of each
|}

== (Basic Rules) Driving ==

As in real life the car starts in 1st gear. Then you shift up to 2nd gear and so on up to 6th gear, in order to move as fast as possible. When it is a driver’s turn they announce which gear they have chosen, move the gear stick on their dashboard accordingly and then roll the die which corresponds to the chosen speed. They then move their car forward the number of spaces indicated on the die. When the move is finished the car “stops”. This notion is especially important in the corners.

'''Order of play''': In each round the drivers play according to their car position on the track, with the current gear deciding tie-breakers, and the first one there is the final decider.

Example: During a round of play car A overtakes car B which was in 1st position. When the next round starts, car A, now in 1st position, will play before car B.

Cars in the straight outside the pit lane will always move before cars in the pit lane. When two cars are level, the car in the highest gear goes first. When cars are level and in the same gear, the car that arrived in their current space first will go first.

==(Basic Rules) Driving Code ==

The cars drive in the track lanes. Different driving codes apply to corners and straights. It is generally not allowed to go over other cars – they must be driven round. Driving backwards is also not allowed.

===(Basic Rules) Driving code in the corners ===

To drive through a corner a car must stop a minimum number of times (indicated in the corner information box) within the limits of the corner. The number of filled red circles indicates the number of stops for that corner. After the requisite number of stops, the car may safely exit the corner, without penalty, on its next move.

To make it easier to drive through the corner, the driver should consider the indicated number of spaces. The number in the green box refers to the longest path, the number in the red box refers to the shortest path. Refer to these when deciding the gear you enter the corner in.

===(Basic Rules) Driving code on the straights ===

Straights are the portions of track between corners. Depending on the length of each straight, cars may need several rounds before entering the next corner.

'''Important''': The maneuver must be completed using the smallest number of spaces possible. (ex. You can't fishtail back and forth between the inside and outside edges)

==(Basic Rules) Wear points (WP) ==

They reflect the capability of the car to stay on the track and survive events during the race. In the Basic Game, each car has 18 WP at the beginning of the race. The players use these points to survive various incidents and risky maneuvers. In the advanced game, they are divided up into different categories that are used in different situations.

==(Basic Rules) Preparation for play ==

===(Basic Rules) Start formation ===

Every player rolls the black die in order to determine the starting position of their car. Whoever rolls the highest number gains pole position. The other cars are positioned in decreasing order according to the numbers rolled. In the case of a tie, all '''involved''' players re-roll the die.

===(Basic Rules) Start ===

Before engaging 1st gear, every player rolls the black die to see how successfully they can start.

'''Number rolled: 1 – poor start'''. The player has stalled the motor of their car. They cannot engage 1st gear and so they have to wait till the next round. Then they can start in 1st gear without having to roll the black die again.

'''Number rolled: between 2 and 16''' – normal start. The player can start normally. They roll the die for 1st gear and move their car forward according to the number rolled.

'''Number rolled: between 17 and 20''' – great start! The player makes a fantastic start. They move their car forward 4 spaces immediately, although they are still in 1st gear. The car can change one or two lanes to avoid other cars. The driver may shift to 2nd gear in the next round.
==(Basic Rules) Overshooting==

If a car passes through a corner at the end of its turn without making the required number of stops, it overshoots the corner. The number of spaces the car overshot the corner by is deducted from the car’s WP as a penalty.

'''Corner with 2 stops''': If the car has made no stops, it is automatically removed from play.

'''Corner with 3 stops''': If the car has made no stops, or only one stop, it is automatically removed from play.

When coming out of a corner the car may not change lane, but must stay in the same lane. If the move ends in another corner, this stop does not count for the new corner. If the car is blocked by another car, it cannot drive round it and has to brake.

==(Basic Rules) Braking==

A player may use their WP at any time to avoid having to advance the full number of spaces shown on the die. In this way they can control their progress better, for example when the lanes are blocked by other cars.

==(Basic Rules) Changing down==

A driver can skip one, two or three gears when changing down, however this wears out their gearbox. The number of gears skipped equates to the number of WP their car loses as a result. Note: It is not possible to skip four gears (from 6th to 1st gear).

==(Basic Rules) Collision==

Whenever a car ends its move on a space next to or behind one or several cars, there is a risk of collision. A driver in this situation must roll the black die to see whether there is a collision or not. If they roll a number between 1 and 4 their car loses 1 WP.

==(Basic Rules) Motor damage==

If a player rolls a 20 in 5th gear or a 30 in 6th gear, this puts a strain on their engine. After their car has finished moving they must therefore roll the black die to test whether their engine has withstood the strain. All players who are driving in 5th or 6th gear at this moment must also roll the black die. If a number between 1 and 4 is rolled, the corresponding car loses 1 WP.

==(Basic Rules) Finish==

The player whose car passes the finishing line first has won the race. The race ends when all cars have crossed the finishing line, in order to enable ranking.

==(Basic Rules) Two-lap race==

For players who have already played several single-lap games.

Whoever crosses the finishing line first after two laps wins the game. Players may make a pit stop between the first and second laps to regain the WP points they lost during the first round.

==(Basic Rules) Pit stop==

At the end of the first lap a player may decide to make a pit stop to regain all the WP they have lost. There is no speed limit in the pit lanes. It is also not necessary to roll the exact number needed to reach one’s own pit.

In the BGA adaptation, your pit box matches the colour of your car's central strip.

===(Basic Rules) Entering pits===

To enter the pits it is sufficient to roll the minimum number required or higher using the die corresponding to the selected gear. The car receives all 18 WP back and awaits their next turn to start from the pits in 4th gear (maximum).

The rules for changing down gear, collision, braking and engine damage do not apply in the pit lane. Overtaking is not possible as it is a single lane. Drivers have to be patient and wait until the car ahead of them moves forward, regardless of selected gear and with no effect on the WP.

Cars in the pit lane must wait for their turn, until the cars on the circuit between pit exit and entry have had their turn.

There are minimum gears required in the pit lane:

* Once a player has entered the pit lane, they must choose a gear which would allow their car to enter their pit box on a maximum roll. If they cannot use such a gear, they must use the highest gear permitted by their previous move.

* Exiting the pits: 1st gear is prohibited to drivers from their pit box to the outlet of the pit lane, except when 2nd gear might be unsafe

=Advanced Rules=

==Basics==

===(Advanced Rules) The gears===

The cars have 6 gears, each gear has its own die. The numbers on the dice tell you how many spaces to move the car. The higher the gear you choose, the faster and further the corresponding die will allow the car to travel. You are not allowed to skip gears when accelerating (e.g. changing straight from 1st to 3rd gear). You are allowed to skip 1, 2, or 3 gears when braking (e.g. from 6th to 4th or from 4th to 1st gear); however there is a penalty for doing this.

{|
!Gear!! Die Color||Die Size||Movement (Number of spaces)
|-
|1||Yellow||d4||1-2
|-
|2||Orange||d6||2-4
|-
|3||Red||d8||4-8
|-
|4||Green||d12||7-12
|-
|5||Purple||d20||11-20
|-
|6||Blue||d20||21-30
|}

===(Advanced Rules) Driving===

As in real life, the car starts in 1st gear. Then you upshift to 2nd gear and so on up to 6th gear, in order to move as fast as possible. When it is a driver’s turn they announce which gear they have chosen, move the gear stick on their dashboard accordingly and then roll the die which corresponds to the chosen speed. They then move their car forward the number of spaces indicated on the die. When the move is finished the car “stops”. This notion is especially important in the corners.

====(Advanced Rules) Order of play====

In each round the drivers play according to their car position on the track.

Example: During a round of play car A overtakes car B which was in 1st position. When the next round starts, car A, now in 1st position, will play before car B.

Cars in the straight outside the pit lane will always move before cars in the pit lane. When two cars are level, the car in the highest gear goes first. When cars are level and in the same gear, the car that arrived in their current space first will go first.

====(Advanced Rules) Same position====

If two cars on the track are level with each other, the driver with the highest gear plays first.

If both cars are in the same gear, the car that arrived first at their current space plays first.

===(Advanced Rules) Driving Code===

The cars drive in the track lanes. Different driving codes apply to corners and straights. It is generally not allowed to go over other cars – they must be driven round. Driving backwards is also not allowed.

====(Advanced Rules) Driving code in the corners====

To drive through a corner a car must stop a minimum number of times (indicated by the number of red stop lights in the corner information box) within the limits of the corner. After the requisite number of stops, the car may proceed and exit the corner on its next move.

To make it easier to drive through the corner, the driver should consider the indicated number of spaces. The number in the green box refers to the longest path, the number in the red box refers to the shortest path. Refer to these numbers when considering what gear to enter the corner in.

====(Advanced Rules) Driving code on the straights====

Straights are the portions of track between corners. Depending on the length of each straight, cars may need several rounds before entering the next corner.

'''Important''': The maneuver must be completed using the smallest number of spaces possible.

===(Advanced Rules) Wear points (WP)===

Wear Points reflect the ability of the car to stay on the track and survive events during the race. Each car has a certain number of WP at the beginning of the race, which are divided up between six different categories. These points are distributed as follows in the game for advanced players:

{|
|WP tires:||6
|-
|WP brakes:||3
|-
|WP gearbox:||3
|-
|WP car body:||3
|-
|WP engine:||3
|-
|WP road handling:||2
|}

==Preparation for play==

===(Advanced Rules) Start formation===

Every player rolls the black die in order to determine the starting position of their car. Whoever rolls the highest number gains pole position. The other cars are positioned in decreasing order according to the numbers rolled. (In the case of a tie, all concerned players re-roll the die.)

===(Advanced Rules) Start===

Before engaging 1st gear, every player rolls the black die to see how successfully they can start.

====Number rolled, 1 - poor start====

The player has stalled the motor of their car. They cannot engage 1st gear and so have to wait till the next round. Then they can start in 1st gear without having to roll the black die again.

====Number rolled: between 2 and 19 - normal start====

The player can start normally. They roll the die for 1st gear and move their car forward according to the number rolled.

====Number rolled: 20 - great start!====

The player makes a fantastic start. They move their car forward 4 spaces immediately, although they are still in 1st gear. The car can change one or two lanes to avoid other cars. The driver may shift to 2nd gear in the next round.

==(Advanced Rules) Overshooting==

If a car passes through a corner at the end of its turn without making the required number of stops, it overshoots the corner. The number of spaces the car overshot the corner by is deducted from the car’s tire WP as a penalty.

'''Corner with 2 stops''': If the car has made no stops, it is automatically removed from play.

'''Corner with 3 stops''': If the car has made no stops, or only one stop, it is automatically removed from play.

When coming out of a corner the car may not change lane, but must stay in the same lane. If the move ends in another corner, this stop does not count for the new corner. If the car is blocked by another car, it cannot drive round it and has to brake.

When a car loses their last tire WP by overshooting a corner, they spin round in a circle. The car is placed on the space where their move ended, pointing backwards. The player must turn their car round again and drive off in 1st gear when it is their next turn. In this adaptation, their Tire WPs are reset to 1.

If a car loses more tire WP than it possesses, it is eliminated from the race.

==(Advanced Rules) Braking==

A player may use their brake WP at any time to avoid having to advance the full number of spaces shown on the die. This can help to prevent losing tire WP if they would otherwise overshoot a corner.

A driver can find themselves blocked by one or more cars which they are unable to overtake. After the driver has moved their car forward as many spaces as possible, they count how many spaces they would have moved if they had not been blocked.

If the number of spaces short of the full number is 4 or greater, they may use Emergency Braking. In this case, their first 3 spaces must be paid for with Brake WP. Each additional space after that may be paid by either Brake or Tire WP.

Braking is paid for *after* Overshooting, so any Tire WPs lost to Overshooting will not be available for Emergency Braking.

If a car doesn't have enough brake WP and tire WP to stop before a blockage, it is eliminated from the race.

==(Advanced Rules) Gearing down==

A driver can skip one, two or three gears when changing down, however this wears out their gearbox.

As a result, the car then loses a certain number of brake WP, engine WP and gearbox WP. The table below lists the corresponding wear. Note: It is not possible to skip four gears (from 6th to 1st gear).

{|
!Gears skipped!!Gearbox WP!!Brake WP!!Engine WP
|-
|1 gear||1||0||0
|-
|2 gears||1||1||0
|-
|3 gears||1||1||1
|}

If a car has no gearbox WP left, the driver can only change down one gear at a time until the game is over.

==(Advanced Rules) Collision==

Whenever a car ends its move on a space next to or behind one or several cars, there is a risk of collision. A driver in this situation must roll the black die to see whether there is a collision or not. If they roll a 1, their car loses 1 Car Body WP.

'''In this adaptation''' the car that did not just move rolls first. If it fails the roll and is eliminated from the race as a result, the car that moved will automatically fail its roll.

'''If a car loses its last car body WP, it is eliminated''' from the race.

==(Advanced Rules) Motor damage==

If a player rolls a 20 in 5th gear or a 30 in 6th gear, this puts a strain on their engine. After their car has finished moving they must therefore roll the black die to test whether their engine has withstood the strain. All players who are driving in 5th or 6th gear at this moment must also roll the black die. If a number between 1 and 4 is rolled, the corresponding car loses 1 engine WP.

If a car loses its last engine WP, it is eliminated from the race.

==(Advanced Rules) Damage and road handling==

Each time a car loses a car body WP or an engine WP, a damage marker is placed on the space where the move ended.

The same applies whenever a car is eliminated from the race for whatever reason. These spaces are judged to be "dangerous" from then on.

If a car passes over one of these spaces or lands on it, the driver must roll the black die. If the result is between 1 and 4, the car loses one road handling WP. The dangerous spaces can be avoided by changing lanes.

'''If a car loses its last road handling WP, it is eliminated from the race.'''

==(Advanced Rules) Slipstreaming==

If a car drives in the wake of another car, this is called slipstreaming.

For the two concerned drivers, slipstreaming is possible from the 4th gear on.

The car must be driving as fast or faster than the car in front.

If a car wants to profit from slipstreaming after moving, it has to stop directly behind another car. From this position they can then add 3 spaces onto their last move. They can move forward 3 spaces in the following way:

*change a lane, overtake the car in front and return to the original lane.
*change a lane and move two spaces in a straight line.
*change two lanes and move one space in a straight line.

The player must move a total of three spaces in any case. (However, the driver may use brake WP in order to reduce this number of spaces.) If slipstreaming brings a car up immediately behind another car, they can carry on slipstreaming (and so on).

If a car is carried into a corner by slipstreaming, they lose a brake WP (without the number of spaces being reduced).

In a corner, a slipstreaming car must follow normal driving code (eg. following the arrows).

Braking in order to take advantage of slipstreaming in the wake of another player's car is not allowed.

Drivers do not have to slipstream!

Note that in this implementation, if your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

==(Advanced Rules) Pit stop==

At the end of the first lap, a player may decide to make a pit stop to regain all the tire WP they have lost. There is no speed limit in the pit lanes. It is also not necessary to roll the exact number needed to reach one's own pit.

In the BGA adaptation, your pit box matches the central colour of your car.

To enter the pits it is necessary to roll the minimum number required or higher using the die corresponding to the selected gear. As soon as the car enters the pits, it receives all its tire WP back. The player now rolls the black die, in order to see how fast their mechanics work.

===Result between 1 and 10: quick pit stop===

The player divides the number shown on the black die by two (rounding it up if necessary). The result is the number of spaces the car is allowed to move when the car leaves the pit in 4th gear.

===Result between 11 and 20: slow pit stop===

The car remains in the pit until the next round. Then the car moves on in 4th gear (or a lower gear).

The rules for gearing down, collision, braking and engine damage do not apply in the pit lane. Overtaking is not possible as it is a single lane. Drivers have to be patient and wait until the car ahead of them moves forward, regardless of selected gear and with no effect on the WP.

Cars in the pit lane must wait for their turn, until the cars on the circuit between pit exit and entry have had their turn.

==(Advanced Rules) Finish==

The player whose car passes the finishing line first has won the race. The race ends when all cars have crossed the finishing line, in order to enable ranking.

=(Advanced Rules) Optional Rules=

All the following rules can be used independently of one another.

==(Advanced Rules) Construction of one's own car==

Every player can distribute their 20 WP between the zones of their car at their own discretion. At least 1 WP must be assigned to each zone.

If using the Technical Pit Stops option, 2 additional WPs are available to assign, and players may assign 0-2 points to Repair points.

==(Advanced Rules) Qualifying lap with a stopwatch==

All players drive a qualifying lap with stopwatch consecutively, in order to determine their start positions. The rules for moves and driving code remain unchanged during the qualifier, however the WP are not taken into account. The only exception is if a car overshoots a corner - this is penalized.

* The player whose turn it is to drive a qualifying lap places their car in the middle lane in front of the starting line.
* You may not apply the brakes at all during Qualifying. If a roll forces you to overshoot a corner, it cannot be avoided.
* You may freely Gear down any number of gears during Qualifying, with no cost or penalty.
* The player receives a total number of points over their lap:
**1 point for each round the player takes to complete the lap
**1 point for each space the player overshoots a corner by (soft tires will have their points doubled)
**1 point for every full real-time minute it takes the player to complete the lap

'''Note:''' The qualifying lap is over if the driver does not stop at all in corners where two or three stops are required. They then have to start the race at the back of the field from the last start position.

After that the order of starting is determined: the car which has completed the qualifying lap with the fewest points takes first position. The other cars follow on in decreasing order of points. If two drivers have the same number of points, the real time taken to complete the lap decides: the fastest player gets the better start position.

==(Advanced Rules) Weather Conditions ==

There is a weather chart for each "Formula D" racing circuit, which is available to all players before the game so that they can inform themselves about weather conditions during the race and qualifying laps.

If the weather rules are used, it is strongly recommended that the tire selection rules be used as well.

Before the qualifying laps begin, the black die is rolled and the weather chart consulted:

'''Good weather''' no problems for the drivers.
'''Changeable''': no problems for drivers, treat as good weather for the qualifying lap.
'''Rain''': The qualifying laps for all players take place in rain (see below).

Before the actual race begins, the black die is rolled again and the weather chart consulted:

'''Good weather''': no problem.
'''Changeable''': The sky is overcast at the beginning of the race, but it does not rain '''unless''' it rained during qualifying. Either way, this can change during the course of the race. Whenever a player in 5th gear throws a 20 or a 30 in 6th gear, at the end of the round they have to roll the black die and consult the weather chart:

If "good weather" comes up, the weather conditions are shifted one line upwards.
If "rain" is the result, the weather conditions are shifted one line downwards.
If the result is "changeable", the weather stays the same.

{|
|'''Weather'''||'''Effect on race'''
|-
|Good||None. The weather will no longer change.
|-
|Good (Temporary)||None.
|-
|Changeable||This is the starting step and once the weather conditions shift up or down off Changeable, it will be skipped for the rest of the game.
|-
|Rain (Temporary)||Rain.
|-
|Rain||Rain. The weather will no longer change.
|}

=== Effect of rain ===

* '''Collision''': A result of 1 or 2 (instead of just a 1, as in good weather) means a collision occurs.
* '''Engine damage''': Occurs when result is between 1 and 3 (instead of between 1 and 4, as in good weather).
* '''Road handling''': The car loses one road handling WP for a result between 1 and 5 (instead of between 1 and 4, as in good weather)
* '''Skidding on corners''': Cars will skid on corners depending on their tire selection. See "Selection of tires", below.

==(Advanced Rules) Selection of tires ==

The choice of tires is crucial not just for qualifying lap, but for the race itself. When weather conditions have been determined, each player can fit their car with special tires (see below). It is also possible to change tires between qualifying lap and the race.

=== Hard Tires ===

They are recommended on a dry track and inefficient on a wet track.

* The game rules apply unchanged if the weather is good or changeable.
* If it is raining, the car moves three additional spaces on any turn which contributes to advancing a corner.

=== Soft Tires ===

They are recommended on a dry track and inefficient - if not handicapping - on a wet track.

* If the weather is changeable or good, the car can move one additional space during each move in the qualifying or race laps. This additional move is not compulsory. But if a car overshoots a corner, the penalty is doubled (loss of tire WP). If a driver does not change their tires during a pit stop after the first lap, they lose the bonus. If a driver does not change their tires during a pit stop after the second lap, the penalties for overshooting a corner are trebled.
* If it is raining, the car travels three spaces further on any turn which contributes to advancing a corner. If a driver does not change their tires during a pit stop before beginning the third lap, the penalties for overshooting a corner are trebled.

Note that in this implementation, if your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

=== Rain Tires ===

They are highly recommended if it is raining, but are otherwise very sensitive.

* If the weather is changeable or good, the penalties for overshooting a corner are doubled (loss of tire WP) for qualifying and the first two laps of the race. If a driver does not change their tires before the third race lap, the
penalties are trebled.
* If it is raining, the car travels one space further on any turn which contributes to advancing a corner.

==(Advanced Rules) Technical Pit Stops ==

Your pit has 2 WP which can be used during the race to regain lost WP (with the exception of tire WP). Every time a driver makes a pit stop they can choose between two options:

* '''Tire pit stop''': As in the rules for advanced players, except that the driver may change the type of tire whenever they change tires.
* '''Technical pit stop''': The driver can change their tires (see above) and in addition regain up to two WP in one or two zones (except the tires). This "reservoir" of 2 WP applies for the entire duration of the race, even if it lasts for more than two laps. In the next round, the car may not start higher than 4th gear. A car with soft tires does not profit from the bonus of an additional space when leaving the pits.

==(Advanced Rules) Team Race ==

A game using these rules is appropriate for a large group with an even number of players. The players form teams each with two players; each colour corresponds to a racing team. Apart from the following two exceptions, the rules apply unchanged:

* '''Pit stop''': Each team has 4 WP to repair the cars. Both players must decide together how they want to use these points.
* '''Winner by points''': A team race is not necessarily won by the first car to cross the finishing line. Each car receives a certain number of winning points. The team with the highest number of total points wins the race.

{|
|'''Ranking''||'''No. of points'''
|-
|1||1000
|-
|2||720
|-
|3||600
|-
|4||480
|-
|5||400
|-
|6||320
|-
|7||240
|-
|8||160
|-
|9||80
|-
|10||40
|}

Note that these points differ from the published rules. If qualifying is enabled, qualifying points are also awarded equally to both members of the team.

==(Advanced Rules) Nitro Fuel ==

When this option is chosen, all cars have a Nitro Fuel injection, which allows instant acceleration. Players can use their nitro once a lap after rolling the corresponding gear die. They receive a movement bonus according to the gear they are using at that moment (1 space in 1st gear, 2 spaces in 2nd gear, etc.). This bonus must be used completely.

When a car pits, or crosses the finish line at the end of a lap, it replenishes its nitro fuel and may use it again.

Nitro may only be used if it is available when rolling the gear die. It does not become available during the same move where you complete a lap.

= BGA Rule Variations=

The BGA Adaptation of Formula D uses a number of variations from the Masters (Tournament) rules.

The differences from the rules you will find in your own copy of Formula D are:

==Round Order ==

In the original rules, if two cars are level with each other, the driver with the highest gear plays first. If both cars are in the same gear, the car nearest the inside with reference to the next (or the current) corner plays first.

In this adaptation, the higher gear continues to be first but if both cars are in the same gear *then the player who first arrived at their space* goes first. Corners no longer affect who goes first.

==Points ==

In this adaptation, points are awarded for race completion '''and''' for Qualifying (if enabled). The Qualifying points are minor by comparison and serve as a tie-break if two players are both eliminated and score 0 in the race.

{|
|'''Ranking'''||'''Race Points'''||'''Qualifying Points'''
|-
|1||1000||10
|-
|2||720||9
|-
|3||600||8
|-
|4||480||7
|-
|5||400||6
|-
|6||320||5
|-
|7||240||4
|-
|8||160||3
|-
|9||80||2
|-
|10||40||1
|}

To cover multiple players being eliminated during a game where there is no Qualifying, their distance travelled before being eliminated is used as the final tie-break (only in non-team games). If a player overshoots a corner or crashes into the back of other cars, their position at the '''start''' of the turn is used.

==Braking ==

The original rules provide a table that describes the outcome of "Emergency Braking" (when a car is blocked by one or more cars which they are unable to overtake). The table does not take Constructed Cars into account, so to clarify, the implemented rules are:

If a player performs Emergency Braking, they must move their car forward as many spaces as possible. If they need to brake more than 3 spaces, they are required to use Brake WPs for the first 3 spaces, and each subsequent space may be paid for using Brake WP *or* Tire WPs.

Braking is paid for *after* Overshooting, so any Tire WPs lost to Overshooting will not be available for Emergency Braking.

==Qualifying ==

Players do not roll the black starting die at the beginning of Qualifying: they just start in 1st gear.

The original rules simply state that "WP are not taken into account" during qualifying. However, the effect of this is clarified in this adaptation:

* You may not apply the brakes at all during Qualifying. If a roll forces you to overshoot a corner, it cannot be avoided.
* You may freely Gear down any number of gears during Qualifying, with no cost or penalty.

In this version, Qualifying awards points as long as you complete your lap:

{|
|'''Ranking''||'''No. of points'''
|-
|1||10
|-
|2||9
|-
|3||8
|-
|4||7
|-
|5||6
|-
|6||5
|-
|7||4
|-
|8||3
|-
|9||2
|-
|10||1
|}

==Collision Checks ==

In this adaptation, the active player checks for collisions only after all adjacent players have rolled. If an adjacent player fails their roll and is eliminated as a result, the active player will automatically fail their roll against that player.

==Weather Options==

When setting up a game with Advanced rules, you have 4 choices for the weather.

===Roll for Weather===

This is the normal approach when using the weather rules: at the start of the race (and, separately, at the start of Qualify if it's been enabled) the Weather die is rolled to determine whether the race's weather will be Good (for the entire race) or Rain (for the entire race) or Changeable.

===Good Weather===

This option skips the opening Weather roll and the race plays with permanent Good weather.

===Rain===

This option skips the opening Weather roll and the race players with permanent Rain.

===Start Changeable===

This option skips the opening Weather roll and treats it as if "Changeable" had been rolled. However the Weather die is rolled to see if the weather starts in Rain. On a Rain result it does, on "Good" or "Changeable" the weather starts good, but either way it is changeable.

==Qualifying Weather Options==

When Qualifying is enabled, you may choose the weather option for it.

===Same as Race===

This is the default. The same setting that is used for "Race Weather" is also used for Qualifying. Note that although the setting is the same, the outcome can be different when "Roll for Weather" is being used.

===Random Weather===

The weather will be randomly chosen before Qualifying. It will NOT be changeable and will be the same outcome (Rain or Good) for all players.

===Good Weather===

Qualifying will be in good weather for all players.

===Rain===

Qualifying will be in rain for all players.

==Weather Rolls ==

In the original rules, the Weather die is thrown immediately when a player rolls the maximum number in 5th or 6th gear. In this adaptation, this roll still occurs but it is deferred until the end of the round. This way, weather can only change between rounds and not in the middle of a player's turn. If multiple players roll the maximum number, the weather die will be rolled multiple times.

==Changeable Weather ==

The original rules have 4 steps for Changeable Weather:
* Good
* Good - Changeable
* Rain - Changeable
* Rain

In this adaptation, there are 5 steps:
* Good
* Good - Temporary
* Changeable
* Rain - Temporary
* Rain

Changeable is only ever used at the start of a race, and by default is Good - with one exception: if it rained in qualifying then a changeable feature race will start Changeable but raining.

Weather will never be changeable in qualifying: it will be Good unless Rain is rolled.

==Spinning ==

The original rules state that if a car on 0 Tire WP overshoots a corner then it "will again spin round in a circle. If the car overshoots the corner by more than one space, it is out of the race". In this adaptation, a car with 0 Tire WP is eliminated if it overshoots a corner by more than 1 WP. Hence, even a single space overshoot will eliminate a 0 Tire WP car on soft tires.

Additionally, in this adaptation when you spin, your Tire WP are reset to 1 WP (instead of remaining at 0 WP).

==Skidding on Corners in the Rain ==

The original rules state that cars will skid in the rain "provided at least one space of the move lies within the limits of a corner". In this adaptation, skidding will only occur on any turn that counts towards a corner's completion. That means:

* Driving through a corner that you have already completed will ''not'' cause you to skid
* If you are on the final space in a corner and still need to land in it 1 more turn, you will skid on your next move even though you are driving into a straight

==Slipstreaming==

If your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

==Motor Damage Checks==

Motor damage checks are always performed in round order.

==Braking in the Pit Lane ==

The original rules state that the rules for braking do not apply in the pit lane. In this adaptation, there is no braking cost for stopping immediately behind another car, or in your pit box. However, there is a brake cost for travelling any distance shorter than that.

== Pit Boxes ==

In Individual Driver games, a single pit box will be reserved for each driver instead of drivers being assigned a pit box color. The box will be indicated with the player's avatar.

== Pit Lane ==

The rules for gearing down DO apply in the pit lane.

There are also minimum gears that may be used in the pit lane:

* Once a player has entered the pit lane, they must choose a gear which would allow their car to enter their pit box on a maximum roll. If they cannot use such a gear, they must use the highest gear permitted by their previous move.

* Exiting the pits: 1st gear is prohibited to drivers from their pit box to the outlet of the pit lane, except when 2nd gear might be unsafe

== Pit Stops ==

The soft tire bonus may not be used when moving after a Quick Pit Stop.

If Technical Pit Stops are enabled, players may always choose to take one (and thus finish their turn) even if they have no repair points or repairs to perform.

==Construction of one's own car ==

In this adaptation, if players have selected the option to Construct their own car then there are no limits to how many points they may assign to any given area.

In games that have also selected the Technical Pit Stop rules, then instead of having a fixed 2 WPs available for Pit repairs, a player will have 22 WPs to use in Construction and can choose how many repair points to make available, with a maximum of 2.

==Road Races ==

The Road Race rules, including Drivers with special abilities, are not used.

Where Road Race circuits are used, all non-standard rules are ignored.

Nitro Fuel Injection is available as an option for all races.

==Nitro Fuel==

The original rules are imprecise about when nitro fuel replenishes when pitting.

To clarify, nitro fuel replenishes when:

* You cross the finish line (if not pitting), or
* When you actually pit

Note that when going through the pit lane, your lap number does not increase until further down the pit lane than your pit box, but your nitro fuel is replenished in your pit box, not when your lap number increases.

==Elimination ==

When a player is eliminated, the outcome is slightly different from the published rules.

*If the elimination was caused by the player overshooting corners, or driving over a damage marker, or quitting, the car is immediately removed from the board and '''no damage marker is placed'''
*If the elimination was caused by the player failing a motor damage test, the car is immediately removed from the board and a damage marker is added.
*If the player is eliminated by any other reason, a damage marker is added and the car remains on the board until the end of the round, when it is removed.

Gamehelpformulad

2026-02-09T22:36:11Z

BaronFraser:

= 10-Second Explainer of Formula D =
New to Formula D?

This 10-second explainer will get you started:

# Your car will start in 1st gear.
# At the start of your turn, your first decision is whether to stay on your current gear, or go up 1 gear or go down 1 gear.
# You can go down 1 gear without penalty, or "skip" up to 3 gears at the cost of wear points. You may only go up by 1 gear per turn.
# After choosing a gear, you will roll the appropriate "gear die". The higher the gear, the bigger the die, as well as the farther you go.
# Once you have rolled, you must move the number of spaces rolled, although you may choose which lane you take.
# Corners are areas marked in red. To drive around corners without penalty, you must finish at least 1 turn in them.
# Some corners are particularly slow and may require that you finish at least 2 or even 3 turns in them.

That's it! There's a lot more to it than that, but this covers the absolute basics of driving safely around the track.

= Important: BGA Rule Variations =

The BGA Adaptation of Formula D uses a number of variations from the Masters (Tournament) rules.

[[#BGA Rule Variations|At the end of these rules]], you will find a list of all differences from the published game rules.

=Adaptation Notes/Common Mistakes=

# The body of your car is the colour of the pit box you are using (or your team's color if playing a team game)
# Your sidepods are your personal color
# To enter the pitbox, you must move out of the pit lane and onto the coloured pit box. Stopping in the pit lane in front of your box is not a pit stop.
# To zoom the circuit in and out with a mouse, use Ctrl+Wheel mouse.

=Basic Rules=

== (Basic Rules) Aim of the game ==

FORMULA D is a car race. The aim is to win a race (of one, two, or three laps) and be the first to cross the finishing line. There are all sorts of risks involved and you have to anticipate what will happen during the course of the race. You must decide on your strategy, trust to luck, keep to the rules and always keep an eye on the technical condition of your car.

== (Basic Rules) The gears ==

The cars have 6 gears. Each gear has its own die. The numbers on the dice tell you how many spaces to move the car. The higher the gear you choose, the faster and farther the corresponding die will allow the car to travel. You are not allowed to skip gears when accelerating (e.g. changing straight from 1st to 3rd gear). You are allowed to skip 1, 2 or 3 gears when braking (e.g. from 6th to 4th or from 4th to 1st gear); however there is a penalty for doing this. You cannot go from 6th gear to 1st.

{|
!Gear!! Color||Die||Movement (Number of spaces)
!Face distribution
|-
|1||Yellow||d4||1-2
|2 of each
|-
|2||Orange||d6||2-4
|2,3,3,4,4,4
|-
|3||Red||d8||4-8
|4,5,6,6,7,7,8,8
|-
|4||Green||d12||7-12
|2 of each
|-
|5||Purple||d20||11-20
|2 of each
|-
|6||Blue||d20||21-30
|2 of each
|}

== (Basic Rules) Driving ==

As in real life the car starts in 1st gear. Then you shift up to 2nd gear and so on up to 6th gear, in order to move as fast as possible. When it is a driver’s turn they announce which gear they have chosen, move the gear stick on their dashboard accordingly and then roll the die which corresponds to the chosen speed. They then move their car forward the number of spaces indicated on the die. When the move is finished the car “stops”. This notion is especially important in the corners.

'''Order of play''': In each round the drivers play according to their car position on the track, with the current gear deciding tie-breakers, and the first one there is the final decider.

Example: During a round of play car A overtakes car B which was in 1st position. When the next round starts, car A, now in 1st position, will play before car B.

Cars in the straight outside the pit lane will always move before cars in the pit lane. When two cars are level, the car in the highest gear goes first. When cars are level and in the same gear, the car that arrived in their current space first will go first.

==(Basic Rules) Driving Code ==

The cars drive in the track lanes. Different driving codes apply to corners and straights. It is generally not allowed to go over other cars – they must be driven round. Driving backwards is also not allowed.

===(Basic Rules) Driving code in the corners ===

To drive through a corner a car must stop a minimum number of times (indicated in the corner information box) within the limits of the corner. The number of filled red circles indicates the number of stops for that corner. After the requisite number of stops, the car may safely exit the corner, without penalty, on its next move.

To make it easier to drive through the corner, the driver should consider the indicated number of spaces. The number in the green box refers to the longest path, the number in the red box refers to the shortest path. Refer to these when deciding the gear you enter the corner in.

===(Basic Rules) Driving code on the straights ===

Straights are the portions of track between corners. Depending on the length of each straight, cars may need several rounds before entering the next corner.

'''Important''': The maneuver must be completed using the smallest number of spaces possible. (ex. You can't fishtail back and forth between the inside and outside edges)

==(Basic Rules) Wear points (WP) ==

They reflect the capability of the car to stay on the track and survive events during the race. In the Basic Game, each car has 18 WP at the beginning of the race. The players use these points to survive various incidents and risky maneuvers. In the advanced game, they are divided up into different categories that are used in different situations.

==(Basic Rules) Preparation for play ==

===(Basic Rules) Start formation ===

Every player rolls the black die in order to determine the starting position of their car. Whoever rolls the highest number gains pole position. The other cars are positioned in decreasing order according to the numbers rolled. In the case of a tie, all '''involved''' players re-roll the die.

===(Basic Rules) Start ===

Before engaging 1st gear, every player rolls the black die to see how successfully they can start.

'''Number rolled: 1 – poor start'''. The player has stalled the motor of their car. They cannot engage 1st gear and so they have to wait till the next round. Then they can start in 1st gear without having to roll the black die again.

'''Number rolled: between 2 and 16''' – normal start. The player can start normally. They roll the die for 1st gear and move their car forward according to the number rolled.

'''Number rolled: between 17 and 20''' – great start! The player makes a fantastic start. They move their car forward 4 spaces immediately, although they are still in 1st gear. The car can change one or two lanes to avoid other cars. The driver may shift to 2nd gear in the next round.
==(Basic Rules) Overshooting==

If a car passes through a corner at the end of its turn without making the required number of stops, it overshoots the corner. The number of spaces the car overshot the corner by is deducted from the car’s WP as a penalty.

'''Corner with 2 stops''': If the car has made no stops, it is automatically removed from play.

'''Corner with 3 stops''': If the car has made no stops, or only one stop, it is automatically removed from play.

When coming out of a corner the car may not change lane, but must stay in the same lane. If the move ends in another corner, this stop does not count for the new corner. If the car is blocked by another car, it cannot drive round it and has to brake.

==(Basic Rules) Braking==

A player may use their WP at any time to avoid having to advance the full number of spaces shown on the die. In this way they can control their progress better, for example when the lanes are blocked by other cars.

==(Basic Rules) Changing down==

A driver can skip one, two or three gears when changing down, however this wears out their gearbox. The number of gears skipped equates to the number of WP their car loses as a result. Note: It is not possible to skip four gears (from 6th to 1st gear).

==(Basic Rules) Collision==

Whenever a car ends its move on a space next to or behind one or several cars, there is a risk of collision. A driver in this situation must roll the black die to see whether there is a collision or not. If they roll a number between 1 and 4 their car loses 1 WP.

==(Basic Rules) Motor damage==

If a player rolls a 20 in 5th gear or a 30 in 6th gear, this puts a strain on their engine. After their car has finished moving they must therefore roll the black die to test whether their engine has withstood the strain. All players who are driving in 5th or 6th gear at this moment must also roll the black die. If a number between 1 and 4 is rolled, the corresponding car loses 1 WP.

==(Basic Rules) Finish==

The player whose car passes the finishing line first has won the race. The race ends when all cars have crossed the finishing line, in order to enable ranking.

==(Basic Rules) Two-lap race==

For players who have already played several single-lap games.

Whoever crosses the finishing line first after two laps wins the game. Players may make a pit stop between the first and second laps to regain the WP points they lost during the first round.

==(Basic Rules) Pit stop==

At the end of the first lap a player may decide to make a pit stop to regain all the WP they have lost. There is no speed limit in the pit lanes. It is also not necessary to roll the exact number needed to reach one’s own pit.

In the BGA adaptation, your pit box matches the colour of your car's central strip.

===(Basic Rules) Entering pits===

To enter the pits it is sufficient to roll the minimum number required or higher using the die corresponding to the selected gear. The car receives all 18 WP back and awaits their next turn to start from the pits in 4th gear (maximum).

The rules for changing down gear, collision, braking and engine damage do not apply in the pit lane. Overtaking is not possible as it is a single lane. Drivers have to be patient and wait until the car ahead of them moves forward, regardless of selected gear and with no effect on the WP.

Cars in the pit lane must wait for their turn, until the cars on the circuit between pit exit and entry have had their turn.

There are minimum gears required in the pit lane:

* Once a player has entered the pit lane, they must choose a gear which would allow their car to enter their pit box on a maximum roll. If they cannot use such a gear, they must use the highest gear permitted by their previous move.

* Exiting the pits: 1st gear is prohibited to drivers from their pit box to the outlet of the pit lane, except when 2nd gear might be unsafe

=Advanced Rules=

==Basics==

===(Advanced Rules) The gears===

The cars have 6 gears, each gear has its own die. The numbers on the dice tell you how many spaces to move the car. The higher the gear you choose, the faster and further the corresponding die will allow the car to travel. You are not allowed to skip gears when accelerating (e.g. changing straight from 1st to 3rd gear). You are allowed to skip 1, 2, or 3 gears when braking (e.g. from 6th to 4th or from 4th to 1st gear); however there is a penalty for doing this.

{|
!Gear!! Die Color||Die Size||Movement (Number of spaces)
|-
|1||Yellow||d4||1-2
|-
|2||Orange||d6||2-4
|-
|3||Red||d8||4-8
|-
|4||Green||d12||7-12
|-
|5||Purple||d20||11-20
|-
|6||Blue||d20||21-30
|}

===(Advanced Rules) Driving===

As in real life, the car starts in 1st gear. Then you upshift to 2nd gear and so on up to 6th gear, in order to move as fast as possible. When it is a driver’s turn they announce which gear they have chosen, move the gear stick on their dashboard accordingly and then roll the die which corresponds to the chosen speed. They then move their car forward the number of spaces indicated on the die. When the move is finished the car “stops”. This notion is especially important in the corners.

====(Advanced Rules) Order of play====

In each round the drivers play according to their car position on the track.

Example: During a round of play car A overtakes car B which was in 1st position. When the next round starts, car A, now in 1st position, will play before car B.

Cars in the straight outside the pit lane will always move before cars in the pit lane. When two cars are level, the car in the highest gear goes first. When cars are level and in the same gear, the car that arrived in their current space first will go first.

====(Advanced Rules) Same position====

If two cars on the track are level with each other, the driver with the highest gear plays first.

If both cars are in the same gear, the car that arrived first at their current space plays first.

===(Advanced Rules) Driving Code===

The cars drive in the track lanes. Different driving codes apply to corners and straights. It is generally not allowed to go over other cars – they must be driven round. Driving backwards is also not allowed.

====(Advanced Rules) Driving code in the corners====

To drive through a corner a car must stop a minimum number of times (indicated by the number of red stop lights in the corner information box) within the limits of the corner. After the requisite number of stops, the car may proceed and exit the corner on its next move.

To make it easier to drive through the corner, the driver should consider the indicated number of spaces. The number in the green box refers to the longest path, the number in the red box refers to the shortest path. Refer to these numbers when considering what gear to enter the corner in.

====(Advanced Rules) Driving code on the straights====

Straights are the portions of track between corners. Depending on the length of each straight, cars may need several rounds before entering the next corner.

'''Important''': The maneuver must be completed using the smallest number of spaces possible.

===(Advanced Rules) Wear points (WP)===

Wear Points reflect the ability of the car to stay on the track and survive events during the race. Each car has a certain number of WP at the beginning of the race, which are divided up between six different categories. These points are distributed as follows in the game for advanced players:

{|
|WP tires:||6
|-
|WP brakes:||3
|-
|WP gearbox:||3
|-
|WP car body:||3
|-
|WP engine:||3
|-
|WP road handling:||2
|}

==Preparation for play==

===(Advanced Rules) Start formation===

Every player rolls the black die in order to determine the starting position of their car. Whoever rolls the highest number gains pole position. The other cars are positioned in decreasing order according to the numbers rolled. (In the case of a tie, all concerned players re-roll the die.)

===(Advanced Rules) Start===

Before engaging 1st gear, every player rolls the black die to see how successfully they can start.

====Number rolled, 1 - poor start====

The player has stalled the motor of their car. They cannot engage 1st gear and so have to wait till the next round. Then they can start in 1st gear without having to roll the black die again.

====Number rolled: between 2 and 19 - normal start====

The player can start normally. They roll the die for 1st gear and move their car forward according to the number rolled.

====Number rolled: 20 - great start!====

The player makes a fantastic start. They move their car forward 4 spaces immediately, although they are still in 1st gear. The car can change one or two lanes to avoid other cars. The driver may shift to 2nd gear in the next round.

==(Advanced Rules) Overshooting==

If a car passes through a corner at the end of its turn without making the required number of stops, it overshoots the corner. The number of spaces the car overshot the corner by is deducted from the car’s tire WP as a penalty.

'''Corner with 2 stops''': If the car has made no stops, it is automatically removed from play.

'''Corner with 3 stops''': If the car has made no stops, or only one stop, it is automatically removed from play.

When coming out of a corner the car may not change lane, but must stay in the same lane. If the move ends in another corner, this stop does not count for the new corner. If the car is blocked by another car, it cannot drive round it and has to brake.

When a car loses their last tire WP by overshooting a corner, they spin round in a circle. The car is placed on the space where their move ended, pointing backwards. The player must turn their car round again and drive off in 1st gear when it is their next turn. In this adaptation, their Tire WPs are reset to 1.

If a car loses more tire WP than it possesses, it is eliminated from the race.

==(Advanced Rules) Braking==

A player may use their brake WP at any time to avoid having to advance the full number of spaces shown on the die. This can help to prevent losing tire WP if they would otherwise overshoot a corner.

A driver can find themselves blocked by one or more cars which they are unable to overtake. After the driver has moved their car forward as many spaces as possible, they count how many spaces they would have moved if they had not been blocked.

If the number of spaces short of the full number is 4 or greater, they may use Emergency Braking. In this case, their first 3 spaces must be paid for with Brake WP. Each additional space after that may be paid by either Brake or Tire WP.

Braking is paid for *after* Overshooting, so any Tire WPs lost to Overshooting will not be available for Emergency Braking.

If a car doesn't have enough brake WP and tire WP to stop before a blockage, it is eliminated from the race.

==(Advanced Rules) Gearing down==

A driver can skip one, two or three gears when changing down, however this wears out their gearbox.

As a result, the car then loses a certain number of brake WP, engine WP and gearbox WP. The table below lists the corresponding wear. Note: It is not possible to skip four gears (from 6th to 1st gear).

{|
!Gears skipped!!Gearbox WP!!Brake WP!!Engine WP
|-
|1 gear||1||0||0
|-
|2 gears||1||1||0
|-
|3 gears||1||1||1
|}

If a car has no gearbox WP left, the driver can only change down one gear at a time until the game is over.

==(Advanced Rules) Collision==

Whenever a car ends its move on a space next to or behind one or several cars, there is a risk of collision. A driver in this situation must roll the black die to see whether there is a collision or not. If they roll a 1, their car loses 1 Car Body WP.

'''In this adaptation''' the car that did not just move rolls first. If it fails the roll and is eliminated from the race as a result, the car that moved will automatically fail its roll.

'''If a car loses its last car body WP, it is eliminated''' from the race.

==(Advanced Rules) Motor damage==

If a player rolls a 20 in 5th gear or a 30 in 6th gear, this puts a strain on their engine. After their car has finished moving they must therefore roll the black die to test whether their engine has withstood the strain. All players who are driving in 5th or 6th gear at this moment must also roll the black die. If a number between 1 and 4 is rolled, the corresponding car loses 1 engine WP.

If a car loses its last engine WP, it is eliminated from the race.

==(Advanced Rules) Damage and road handling==

Each time a car loses a car body WP or an engine WP, a damage marker is placed on the space where the move ended.

The same applies whenever a car is eliminated from the race for whatever reason. These spaces are judged to be "dangerous" from then on.

If a car passes over one of these spaces or lands on it, the driver must roll the black die. If the result is between 1 and 4, the car loses one road handling WP. The dangerous spaces can be avoided by changing lanes.

'''If a car loses its last road handling WP, it is eliminated from the race.'''

==(Advanced Rules) Slipstreaming==

If a car drives in the wake of another car, this is called slipstreaming.

For the two concerned drivers, slipstreaming is possible from the 4th gear on.

The car must be driving as fast or faster than the car in front.

If a car wants to profit from slipstreaming after moving, it has to stop directly behind another car. From this position they can then add 3 spaces onto their last move. They can move forward 3 spaces in the following way:

*change a lane, overtake the car in front and return to the original lane.
*change a lane and move two spaces in a straight line.
*change two lanes and move one space in a straight line.

The player must move a total of three spaces in any case. (However, the driver may use brake WP in order to reduce this number of spaces.) If slipstreaming brings a car up immediately behind another car, they can carry on slipstreaming (and so on).

If a car is carried into a corner by slipstreaming, they lose a brake WP (without the number of spaces being reduced).

In a corner, a slipstreaming car must follow normal driving code (eg. following the arrows).

Braking in order to take advantage of slipstreaming in the wake of another player's car is not allowed.

Drivers do not have to slipstream!

Note that in this implementation, if your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

==(Advanced Rules) Pit stop==

At the end of the first lap, a player may decide to make a pit stop to regain all the tire WP they have lost. There is no speed limit in the pit lanes. It is also not necessary to roll the exact number needed to reach one's own pit.

In the BGA adaptation, your pit box matches the central colour of your car.

To enter the pits it is necessary to roll the minimum number required or higher using the die corresponding to the selected gear. As soon as the car enters the pits, it receives all its tire WP back. The player now rolls the black die, in order to see how fast their mechanics work.

===Result between 1 and 10: quick pit stop===

The player divides the number shown on the black die by two (rounding it up if necessary). The result is the number of spaces the car is allowed to move when the car leaves the pit in 4th gear.

===Result between 11 and 20: slow pit stop===

The car remains in the pit until the next round. Then the car moves on in 4th gear (or a lower gear).

The rules for gearing down, collision, braking and engine damage do not apply in the pit lane. Overtaking is not possible as it is a single lane. Drivers have to be patient and wait until the car ahead of them moves forward, regardless of selected gear and with no effect on the WP.

Cars in the pit lane must wait for their turn, until the cars on the circuit between pit exit and entry have had their turn.

==(Advanced Rules) Finish==

The player whose car passes the finishing line first has won the race. The race ends when all cars have crossed the finishing line, in order to enable ranking.

=(Advanced Rules) Optional Rules=

All the following rules can be used independently of one another.

==(Advanced Rules) Construction of one's own car==

Every player can distribute their 20 WP between the zones of their car at their own discretion. At least 1 WP must be assigned to each zone.

If using the Technical Pit Stops option, 2 additional WPs are available to assign, and players may assign 0-2 points to Repair points.

==(Advanced Rules) Qualifying lap with a stopwatch==

All players drive a qualifying lap with stopwatch consecutively, in order to determine their start positions. The rules for moves and driving code remain unchanged during the qualifier, however the WP are not taken into account. The only exception is if a car overshoots a corner - this is penalized.

* The player whose turn it is to drive a qualifying lap places their car in the middle lane in front of the starting line.
* You may not apply the brakes at all during Qualifying. If a roll forces you to overshoot a corner, it cannot be avoided.
* You may freely Gear down any number of gears during Qualifying, with no cost or penalty.
* The player receives a total number of points over their lap:
**1 point for each round the player takes to complete the lap
**1 point for each space the player overshoots a corner by (soft tires will have their points doubled)
**1 point for every full real-time minute it takes the player to complete the lap

'''Note:''' The qualifying lap is over if the driver does not stop at all in corners where two or three stops are required. They then have to start the race at the back of the field from the last start position.

After that the order of starting is determined: the car which has completed the qualifying lap with the fewest points takes first position. The other cars follow on in decreasing order of points. If two drivers have the same number of points, the real time taken to complete the lap decides: the fastest player gets the better start position.

==(Advanced Rules) Weather Conditions ==

There is a weather chart for each "Formula D" racing circuit, which is available to all players before the game so that they can inform themselves about weather conditions during the race and qualifying laps.

If the weather rules are used, it is strongly recommended that the tire selection rules be used as well.

Before the qualifying laps begin, the black die is rolled and the weather chart consulted:

'''Good weather''' no problems for the drivers.
'''Changeable''': no problems for drivers, treat as good weather for the qualifying lap.
'''Rain''': The qualifying laps for all players take place in rain (see below).

Before the actual race begins, the black die is rolled again and the weather chart consulted:

'''Good weather''': no problem.
'''Changeable''': The sky is overcast at the beginning of the race, but it does not rain '''unless''' it rained during qualifying. Either way, this can change during the course of the race. Whenever a player in 5th gear throws a 20 or a 30 in 6th gear, at the end of the round they have to roll the black die and consult the weather chart:

If "good weather" comes up, the weather conditions are shifted one line upwards.
If "rain" is the result, the weather conditions are shifted one line downwards.
If the result is "changeable", the weather stays the same.

{|
|'''Weather'''||'''Effect on race'''
|-
|Good||None. The weather will no longer change.
|-
|Good (Temporary)||None.
|-
|Changeable||This is the starting step and once the weather conditions shift up or down off Changeable, it will be skipped for the rest of the game.
|-
|Rain (Temporary)||Rain.
|-
|Rain||Rain. The weather will no longer change.
|}

=== Effect of rain ===

* '''Collision''': A result of 1 or 2 (instead of just a 1, as in good weather) means a collision occurs.
* '''Engine damage''': Occurs when result is between 1 and 3 (instead of between 1 and 4, as in good weather).
* '''Road handling''': The car loses one road handling WP for a result between 1 and 5 (instead of between 1 and 4, as in good weather)
* '''Skidding on corners''': Cars will skid on corners depending on their tire selection. See "Selection of tires", below.

==(Advanced Rules) Selection of tires ==

The choice of tires is crucial not just for qualifying lap, but for the race itself. When weather conditions have been determined, each player can fit their car with special tires (see below). It is also possible to change tires between qualifying lap and the race.

=== Hard Tires ===

They are recommended on a dry track and inefficient on a wet track.

* The game rules apply unchanged if the weather is good or changeable.
* If it is raining, the car moves three additional spaces on any turn which contributes to advancing a corner.

=== Soft Tires ===

They are recommended on a dry track and inefficient - if not handicapping - on a wet track.

* If the weather is changeable or good, the car can move one additional space during each move in the qualifying or race laps. This additional move is not compulsory. But if a car overshoots a corner, the penalty is doubled (loss of tire WP). If a driver does not change their tires during a pit stop after the first lap, they lose the bonus. If a driver does not change their tires during a pit stop after the second lap, the penalties for overshooting a corner are trebled.
* If it is raining, the car travels three spaces further on any turn which contributes to advancing a corner. If a driver does not change their tires during a pit stop before beginning the third lap, the penalties for overshooting a corner are trebled.

Note that in this implementation, if your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

=== Rain Tires ===

They are highly recommended if it is raining, but are otherwise very sensitive.

* If the weather is changeable or good, the penalties for overshooting a corner are doubled (loss of tire WP) for qualifying and the first two laps of the race. If a driver does not change their tires before the third race lap, the
penalties are trebled.
* If it is raining, the car travels one space further on any turn which contributes to advancing a corner.

==(Advanced Rules) Technical Pit Stops ==

Your pit has 2 WP which can be used during the race to regain lost WP (with the exception of tire WP). Every time a driver makes a pit stop they can choose between two options:

* '''Tire pit stop''': As in the rules for advanced players, except that the driver may change the type of tire whenever they change tires.
* '''Technical pit stop''': The driver can change their tires (see above) and in addition regain up to two WP in one or two zones (except the tires). This "reservoir" of 2 WP applies for the entire duration of the race, even if it lasts for more than two laps. In the next round, the car may not start higher than 4th gear. A car with soft tires does not profit from the bonus of an additional space when leaving the pits.

==(Advanced Rules) Team Race ==

A game using these rules is appropriate for a large group with an even number of players. The players form teams each with two players; each colour corresponds to a racing team. Apart from the following two exceptions, the rules apply unchanged:

* '''Pit stop''': Each team has 4 WP to repair the cars. Both players must decide together how they want to use these points.
* '''Winner by points''': A team race is not necessarily won by the first car to cross the finishing line. Each car receives a certain number of winning points. The team with the highest number of total points wins the race.

{|
|'''Ranking''||'''No. of points'''
|-
|1||1000
|-
|2||720
|-
|3||600
|-
|4||480
|-
|5||400
|-
|6||320
|-
|7||240
|-
|8||160
|-
|9||80
|-
|10||40
|}

Note that these points differ from the published rules. If qualifying is enabled, qualifying points are also awarded equally to both members of the team.

==(Advanced Rules) Nitro Fuel ==

When this option is chosen, all cars have a Nitro Fuel injection, which allows instant acceleration. Players can use their nitro once a lap after rolling the corresponding gear die. They receive a movement bonus according to the gear they are using at that moment (1 space in 1st gear, 2 spaces in 2nd gear, etc.). This bonus must be used completely.

When a car pits, or crosses the finish line at the end of a lap, it replenishes its nitro fuel and may use it again.

Nitro may only be used if it is available when rolling the gear die. It does not become available during the same move where you complete a lap.

= BGA Rule Variations=

The BGA Adaptation of Formula D uses a number of variations from the Masters (Tournament) rules.

The differences from the rules you will find in your own copy of Formula D are:

==Round Order ==

In the original rules, if two cars are level with each other, the driver with the highest gear plays first. If both cars are in the same gear, the car nearest the inside with reference to the next (or the current) corner plays first.

In this adaptation, the higher gear continues to be first but if both cars are in the same gear *then the player who first arrived at their space* goes first. Corners no longer affect who goes first.

==Points ==

In this adaptation, points are awarded for race completion '''and''' for Qualifying (if enabled). The Qualifying points are minor by comparison and serve as a tie-break if two players are both eliminated and score 0 in the race.

{|
|'''Ranking'''||'''Race Points'''||'''Qualifying Points'''
|-
|1||1000||10
|-
|2||720||9
|-
|3||600||8
|-
|4||480||7
|-
|5||400||6
|-
|6||320||5
|-
|7||240||4
|-
|8||160||3
|-
|9||80||2
|-
|10||40||1
|}

To cover multiple players being eliminated during a game where there is no Qualifying, their distance travelled before being eliminated is used as the final tie-break (only in non-team games). If a player overshoots a corner or crashes into the back of other cars, their position at the '''start''' of the turn is used.

==Braking ==

The original rules provide a table that describes the outcome of "Emergency Braking" (when a car is blocked by one or more cars which they are unable to overtake). The table does not take Constructed Cars into account, so to clarify, the implemented rules are:

If a player performs Emergency Braking, they must move their car forward as many spaces as possible. If they need to brake more than 3 spaces, they are required to use Brake WPs for the first 3 spaces, and each subsequent space may be paid for using Brake WP *or* Tire WPs.

Braking is paid for *after* Overshooting, so any Tire WPs lost to Overshooting will not be available for Emergency Braking.

==Qualifying ==

Players do not roll the black starting die at the beginning of Qualifying: they just start in 1st gear.

The original rules simply state that "WP are not taken into account" during qualifying. However, the effect of this is clarified in this adaptation:

* You may not apply the brakes at all during Qualifying. If a roll forces you to overshoot a corner, it cannot be avoided.
* You may freely Gear down any number of gears during Qualifying, with no cost or penalty.

In this version, Qualifying awards points as long as you complete your lap:

{|
|'''Ranking''||'''No. of points'''
|-
|1||10
|-
|2||9
|-
|3||8
|-
|4||7
|-
|5||6
|-
|6||5
|-
|7||4
|-
|8||3
|-
|9||2
|-
|10||1
|}

==Collision Checks ==

In this adaptation, the active player checks for collisions only after all adjacent players have rolled. If an adjacent player fails their roll and is eliminated as a result, the active player will automatically fail their roll against that player.

==Weather Options==

When setting up a game with Advanced rules, you have 4 choices for the weather.

===Roll for Weather===

This is the normal approach when using the weather rules: at the start of the race (and, separately, at the start of Qualify if it's been enabled) the Weather die is rolled to determine whether the race's weather will be Good (for the entire race) or Rain (for the entire race) or Changeable.

===Good Weather===

This option skips the opening Weather roll and the race plays with permanent Good weather.

===Rain===

This option skips the opening Weather roll and the race players with permanent Rain.

===Start Changeable===

This option skips the opening Weather roll and treats it as if "Changeable" had been rolled. However the Weather die is rolled to see if the weather starts in Rain. On a Rain result it does, on "Good" or "Changeable" the weather starts good, but either way it is changeable.

==Qualifying Weather Options==

When Qualifying is enabled, you may choose the weather option for it.

===Same as Race===

This is the default. The same setting that is used for "Race Weather" is also used for Qualifying. Note that although the setting is the same, the outcome can be different when "Roll for Weather" is being used.

===Random Weather===

The weather will be randomly chosen before Qualifying. It will NOT be changeable and will be the same outcome (Rain or Good) for all players.

===Good Weather===

Qualifying will be in good weather for all players.

===Rain===

Qualifying will be in rain for all players.

==Weather Rolls ==

In the original rules, the Weather die is thrown immediately when a player rolls the maximum number in 5th or 6th gear. In this adaptation, this roll still occurs but it is deferred until the end of the round. This way, weather can only change between rounds and not in the middle of a player's turn. If multiple players roll the maximum number, the weather die will be rolled multiple times.

==Changeable Weather ==

The original rules have 4 steps for Changeable Weather:
* Good
* Good - Changeable
* Rain - Changeable
* Rain

In this adaptation, there are 5 steps:
* Good
* Good - Temporary
* Changeable
* Rain - Temporary
* Rain

Changeable is only ever used at the start of a race, and by default is Good - with one exception: if it rained in qualifying then a changeable feature race will start Changeable but raining.

Weather will never be changeable in qualifying: it will be Good unless Rain is rolled.

==Spinning ==

The original rules state that if a car on 0 Tire WP overshoots a corner then it "will again spin round in a circle. If the car overshoots the corner by more than one space, it is out of the race". In this adaptation, a car with 0 Tire WP is eliminated if it overshoots a corner by more than 1 WP. Hence, even a single space overshoot will eliminate a 0 Tire WP car on soft tires.

Additionally, in this adaptation when you spin, your Tire WP are reset to 1 WP (instead of remaining at 0 WP).

==Skidding on Corners in the Rain ==

The original rules state that cars will skid in the rain "provided at least one space of the move lies within the limits of a corner". In this adaptation, skidding will only occur on any turn that counts towards a corner's completion. That means:

* Driving through a corner that you have already completed will ''not'' cause you to skid
* If you are on the final space in a corner and still need to land in it 1 more turn, you will skid on your next move even though you are driving into a straight

==Slipstreaming==

If your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

==Motor Damage Checks==

Motor damage checks are always performed in round order.

==Braking in the Pit Lane ==

The original rules state that the rules for braking do not apply in the pit lane. In this adaptation, there is no braking cost for stopping immediately behind another car, or in your pit box. However, there is a brake cost for travelling any distance shorter than that.

== Pit Boxes ==

In Individual Driver games, a single pit box will be reserved for each driver instead of drivers being assigned a pit box color. The box will be indicated with the player's avatar.

== Pit Lane ==

The rules for gearing down DO apply in the pit lane.

There are also minimum gears that may be used in the pit lane:

* Once a player has entered the pit lane, they must choose a gear which would allow their car to enter their pit box on a maximum roll. If they cannot use such a gear, they must use the highest gear permitted by their previous move.

* Exiting the pits: 1st gear is prohibited to drivers from their pit box to the outlet of the pit lane, except when 2nd gear might be unsafe

== Pit Stops ==

The soft tire bonus may not be used when moving after a Quick Pit Stop.

If Technical Pit Stops are enabled, players may always choose to take one (and thus finish their turn) even if they have no repair points or repairs to perform.

==Construction of one's own car ==

In this adaptation, if players have selected the option to Construct their own car then there are no limits to how many points they may assign to any given area.

In games that have also selected the Technical Pit Stop rules, then instead of having a fixed 2 WPs available for Pit repairs, a player will have 22 WPs to use in Construction and can choose how many repair points to make available, with a maximum of 2.

==Road Races ==

The Road Race rules, including Drivers with special abilities, are not used.

Where Road Race circuits are used, all non-standard rules are ignored.

Nitro Fuel Injection is available as an option for all races.

==Elimination ==

When a player is eliminated, the outcome is slightly different from the published rules.

*If the elimination was caused by the player overshooting corners, or driving over a damage marker, or quitting, the car is immediately removed from the board and '''no damage marker is placed'''
*If the elimination was caused by the player failing a motor damage test, the car is immediately removed from the board and a damage marker is added.
*If the player is eliminated by any other reason, a damage marker is added and the car remains on the board until the end of the round, when it is removed.

Gamehelpformulad

2026-02-06T21:41:26Z

BaronFraser: /* BGA Rule Variations */

= 10-Second Explainer of Formula D =
New to Formula D?

This 10-second explainer will get you started:

# Your car will start in 1st gear.
# At the start of your turn, your first decision is whether to stay on your current gear, or go up 1 gear or go down 1 gear.
# You can go down 1 gear without penalty, or "skip" up to 3 gears at the cost of wear points. You may only go up by 1 gear per turn.
# After choosing a gear, you will roll the appropriate "gear die". The higher the gear, the bigger the die, as well as the farther you go.
# Once you have rolled, you must move the number of spaces rolled, although you may choose which lane you take.
# Corners are areas marked in red. To drive around corners without penalty, you must finish at least 1 turn in them.
# Some corners are particularly slow and may require that you finish at least 2 or even 3 turns in them.

That's it! There's a lot more to it than that, but this covers the absolute basics of driving safely around the track.

= Important: BGA Rule Variations =

The BGA Adaptation of Formula D uses a number of variations from the Masters (Tournament) rules.

[[#BGA Rule Variations|At the end of these rules]], you will find a list of all differences from the published game rules.

=Adaptation Notes/Common Mistakes=

# The body of your car is the colour of the pit box you are using (or your team's color if playing a team game)
# Your sidepods are your personal color
# To enter the pitbox, you must move out of the pit lane and onto the coloured pit box. Stopping in the pit lane in front of your box is not a pit stop.
# To zoom the circuit in and out with a mouse, use Ctrl+Wheel mouse.

=Basic Rules=

== Aim of the game ==

FORMULA D is a car race. The aim is to win a race (of one, two, or three laps) and be the first to cross the finishing line. There are all sorts of risks involved and you have to anticipate what will happen during the course of the race. You must decide on your strategy, trust to luck, keep to the rules and always keep an eye on the technical condition of your car.

== The gears ==

The cars have 6 gears. Each gear has its own die. The numbers on the dice tell you how many spaces to move the car. The higher the gear you choose, the faster and farther the corresponding die will allow the car to travel. You are not allowed to skip gears when accelerating (e.g. changing straight from 1st to 3rd gear). You are allowed to skip 1, 2 or 3 gears when braking (e.g. from 6th to 4th or from 4th to 1st gear); however there is a penalty for doing this. You cannot go from 6th gear to 1st.

{|
!Gear!! Color||Die||Movement (Number of spaces)
!Face distribution
|-
|1||Yellow||d4||1-2
|1,1,2,2
|-
|2||Orange||d6||2-4
|2,3,3,4,4,4
|-
|3||Red||d8||4-8
|4,5,6,6,7,7,8,8
|-
|4||Green||d12||7-12
|2 of each
|-
|5||Purple||d20||11-20
|2 of each
|-
|6||Blue||d20||21-30
|2 of each
|}

== Driving ==

As in real life the car starts in 1st gear. Then you shift up to 2nd gear and so on up to 6th gear, in order to move as fast as possible. When it is a driver’s turn they announce which gear they have chosen, move the gear stick on their dashboard accordingly and then roll the die which corresponds to the chosen speed. They then move their car forward the number of spaces indicated on the die. When the move is finished the car “stops”. This notion is especially important in the corners.

'''Order of play''': In each round the drivers play according to their car position on the track, with the current gear deciding tie-breakers, and the first one there is the final decider.

Example: During a round of play car A overtakes car B which was in 1st position. When the next round starts, car A, now in 1st position, will play before car B.

Cars in the straight outside the pit lane will always move before cars in the pit lane. When two cars are level, the car in the highest gear goes first. When cars are level and in the same gear, the car that arrived in their current space first will go first.

==Driving Code ==

The cars drive in the track lanes. Different driving codes apply to corners and straights. It is generally not allowed to go over other cars – they must be driven round. Driving backwards is also not allowed.

===Driving code in the corners ===

To drive through a corner a car must stop a minimum number of times (indicated in the corner information box) within the limits of the corner. The number of filled red circles indicates the number of stops for that corner. After the requisite number of stops, the car may safely exit the corner, without penalty, on its next move.

To make it easier to drive through the corner, the driver should consider the indicated number of spaces. The number in the green box refers to the longest path, the number in the red box refers to the shortest path. Refer to these when deciding the gear you enter the corner in.

===Driving code on the straights ===

Straights are the portions of track between corners. Depending on the length of each straight, cars may need several rounds before entering the next corner.

'''Important''': The maneuver must be completed using the smallest number of spaces possible. (ex. You can't fishtail back and forth between the inside and outside edges)

==Wear points (WP) ==

They reflect the capability of the car to stay on the track and survive events during the race. In the Basic Game, each car has 18 WP at the beginning of the race. The players use these points to survive various incidents and risky maneuvers. In the advanced game, they are divided up into different categories that are used in different situations.

==Preparation for play ==

===Start formation ===

Every player rolls the black die in order to determine the starting position of their car. Whoever rolls the highest number gains pole position. The other cars are positioned in decreasing order according to the numbers rolled. In the case of a tie, all '''involved''' players re-roll the die.

===Start ===

Before engaging 1st gear, every player rolls the black die to see how successfully they can start.

'''Number rolled: 1 – poor start'''. The player has stalled the motor of their car. They cannot engage 1st gear and so they have to wait till the next round. Then they can start in 1st gear without having to roll the black die again.

'''Number rolled: between 2 and 16''' – normal start. The player can start normally. They roll the die for 1st gear and move their car forward according to the number rolled.

'''Number rolled: between 17 and 20''' – great start! The player makes a fantastic start. They move their car forward 4 spaces immediately, although they are still in 1st gear. The car can change one or two lanes to avoid other cars. The driver may shift to 2nd gear in the next round.
==Overshooting==

If a car passes through a corner at the end of its turn without making the required number of stops, it overshoots the corner. The number of spaces the car overshot the corner by is deducted from the car’s WP as a penalty.

'''Corner with 2 stops''': If the car has made no stops, it is automatically removed from play.

'''Corner with 3 stops''': If the car has made no stops, or only one stop, it is automatically removed from play.

When coming out of a corner the car may not change lane, but must stay in the same lane. If the move ends in another corner, this stop does not count for the new corner. If the car is blocked by another car, it cannot drive round it and has to brake.

==Braking==

A player may use their WP at any time to avoid having to advance the full number of spaces shown on the die. In this way they can control their progress better, for example when the lanes are blocked by other cars.

==Changing down==

A driver can skip one, two or three gears when changing down, however this wears out their gearbox. The number of gears skipped equates to the number of WP their car loses as a result. Note: It is not possible to skip four gears (from 6th to 1st gear).

==Collision==

Whenever a car ends its move on a space next to or behind one or several cars, there is a risk of collision. A driver in this situation must roll the black die to see whether there is a collision or not. If they roll a number between 1 and 4 their car loses 1 WP.

==Motor damage==

If a player rolls a 20 in 5th gear or a 30 in 6th gear, this puts a strain on their engine. After their car has finished moving they must therefore roll the black die to test whether their engine has withstood the strain. All players who are driving in 5th or 6th gear at this moment must also roll the black die. If a number between 1 and 4 is rolled, the corresponding car loses 1 WP.

==Finish==

The player whose car passes the finishing line first has won the race. The race ends when all cars have crossed the finishing line, in order to enable ranking.

==Two-lap race==

For players who have already played several single-lap games.

Whoever crosses the finishing line first after two laps wins the game. Players may make a pit stop between the first and second laps to regain the WP points they lost during the first round.

==Pit stop==

At the end of the first lap a player may decide to make a pit stop to regain all the WP they have lost. There is no speed limit in the pit lanes. It is also not necessary to roll the exact number needed to reach one’s own pit.

In the BGA adaptation, your pit box matches the colour of your car's central strip.

===Entering pits===

To enter the pits it is sufficient to roll the minimum number required or higher using the die corresponding to the selected gear. The car receives all 18 WP back and awaits their next turn to start from the pits in 4th gear (maximum).

The rules for changing down gear, collision, braking and engine damage do not apply in the pit lane. Overtaking is not possible as it is a single lane. Drivers have to be patient and wait until the car ahead of them moves forward, regardless of selected gear and with no effect on the WP.

Cars in the pit lane must wait for their turn, until the cars on the circuit between pit exit and entry have had their turn.

There are minimum gears required in the pit lane:

* Once a player has entered the pit lane, they must choose a gear which would allow their car to enter their pit box on a maximum roll. If they cannot use such a gear, they must use the highest gear permitted by their previous move.

* Exiting the pits: 1st gear is prohibited to drivers from their pit box to the outlet of the pit lane, except when 2nd gear might be unsafe

=Advanced Rules=

==Basics==

===The gears===

The cars have 6 gears, each gear has its own die. The numbers on the dice tell you how many spaces to move the car. The higher the gear you choose, the faster and further the corresponding die will allow the car to travel. You are not allowed to skip gears when accelerating (e.g. changing straight from 1st to 3rd gear). You are allowed to skip 1, 2, or 3 gears when braking (e.g. from 6th to 4th or from 4th to 1st gear); however there is a penalty for doing this.

{|
!Gear!! Die Color||Die Size||Movement (Number of spaces)
|-
|1||Yellow||d4||1-2
|-
|2||Orange||d6||2-4
|-
|3||Red||d8||4-8
|-
|4||Green||d12||7-12
|-
|5||Purple||d20||11-20
|-
|6||Blue||d20||21-30
|}

===Driving===

As in real life, the car starts in 1st gear. Then you upshift to 2nd gear and so on up to 6th gear, in order to move as fast as possible. When it is a driver’s turn they announce which gear they have chosen, move the gear stick on their dashboard accordingly and then roll the die which corresponds to the chosen speed. They then move their car forward the number of spaces indicated on the die. When the move is finished the car “stops”. This notion is especially important in the corners.

====Order of play====

In each round the drivers play according to their car position on the track.

Example: During a round of play car A overtakes car B which was in 1st position. When the next round starts, car A, now in 1st position, will play before car B.

Cars in the straight outside the pit lane will always move before cars in the pit lane. When two cars are level, the car in the highest gear goes first. When cars are level and in the same gear, the car that arrived in their current space first will go first.

==== Same position====

If two cars on the track are level with each other, the driver with the highest gear plays first.

If both cars are in the same gear, the car that arrived first at their current space plays first.

===Driving Code===

The cars drive in the track lanes. Different driving codes apply to corners and straights. It is generally not allowed to go over other cars – they must be driven round. Driving backwards is also not allowed.

====Driving code in the corners====

To drive through a corner a car must stop a minimum number of times (indicated by the number of red stop lights in the corner information box) within the limits of the corner. After the requisite number of stops, the car may proceed and exit the corner on its next move.

To make it easier to drive through the corner, the driver should consider the indicated number of spaces. The number in the green box refers to the longest path, the number in the red box refers to the shortest path. Refer to these numbers when considering what gear to enter the corner in.

====Driving code on the straights====

Straights are the portions of track between corners. Depending on the length of each straight, cars may need several rounds before entering the next corner.

'''Important''': The maneuver must be completed using the smallest number of spaces possible.

=== Wear points (WP)===

Wear Points reflect the ability of the car to stay on the track and survive events during the race. Each car has a certain number of WP at the beginning of the race, which are divided up between six different categories. These points are distributed as follows in the game for advanced players:

{|
|WP tires:||6
|-
|WP brakes:||3
|-
|WP gearbox:||3
|-
|WP car body:||3
|-
|WP engine:||3
|-
|WP road handling:||2
|}

==Preparation for play==

===Start formation===

Every player rolls the black die in order to determine the starting position of their car. Whoever rolls the highest number gains pole position. The other cars are positioned in decreasing order according to the numbers rolled. (In the case of a tie, all concerned players re-roll the die.)

===Start===

Before engaging 1st gear, every player rolls the black die to see how successfully they can start.

====Number rolled, 1 - poor start====

The player has stalled the motor of their car. They cannot engage 1st gear and so have to wait till the next round. Then they can start in 1st gear without having to roll the black die again.

====Number rolled: between 2 and 19 - normal start====

The player can start normally. They roll the die for 1st gear and move their car forward according to the number rolled.

====Number rolled: 20 - great start!====

The player makes a fantastic start. They move their car forward 4 spaces immediately, although they are still in 1st gear. The car can change one or two lanes to avoid other cars. The driver may shift to 2nd gear in the next round.

==Overshooting==

If a car passes through a corner at the end of its turn without making the required number of stops, it overshoots the corner. The number of spaces the car overshot the corner by is deducted from the car’s tire WP as a penalty.

'''Corner with 2 stops''': If the car has made no stops, it is automatically removed from play.

'''Corner with 3 stops''': If the car has made no stops, or only one stop, it is automatically removed from play.

When coming out of a corner the car may not change lane, but must stay in the same lane. If the move ends in another corner, this stop does not count for the new corner. If the car is blocked by another car, it cannot drive round it and has to brake.

When a car loses their last tire WP by overshooting a corner, they spin round in a circle. The car is placed on the space where their move ended, pointing backwards. The player must turn their car round again and drive off in 1st gear when it is their next turn. In this adaptation, their Tire WPs are reset to 1.

If a car loses more tire WP than it possesses, it is eliminated from the race.

==Braking==

A player may use their brake WP at any time to avoid having to advance the full number of spaces shown on the die. This can help to prevent losing tire WP if they would otherwise overshoot a corner.

A driver can find themselves blocked by one or more cars which they are unable to overtake. After the driver has moved their car forward as many spaces as possible, they count how many spaces they would have moved if they had not been blocked.

If the number of spaces short of the full number is 4 or greater, they may use Emergency Braking. In this case, their first 3 spaces must be paid for with Brake WP. Each additional space after that may be paid by either Brake or Tire WP.

Braking is paid for *after* Overshooting, so any Tire WPs lost to Overshooting will not be available for Emergency Braking.

If a car doesn't have enough brake WP and tire WP to stop before a blockage, it is eliminated from the race.

==Gearing down==

A driver can skip one, two or three gears when changing down, however this wears out their gearbox.

As a result, the car then loses a certain number of brake WP, engine WP and gearbox WP. The table below lists the corresponding wear. Note: It is not possible to skip four gears (from 6th to 1st gear).

{|
!Gears skipped!!Gearbox WP!!Brake WP!!Engine WP
|-
|1 gear||1||0||0
|-
|2 gears||1||1||0
|-
|3 gears||1||1||1
|}

If a car has no gearbox WP left, the driver can only change down one gear at a time until the game is over.

==Collision==

Whenever a car ends its move on a space next to or behind one or several cars, there is a risk of collision. A driver in this situation must roll the black die to see whether there is a collision or not. If they roll a 1, their car loses 1 WP.

'''In this adaptation''' the car that did not just move rolls first. If it fails the roll and is eliminated from the race as a result, the car that moved will automatically fail its roll.

'''If a car loses its last car body WP, it is eliminated''' from the race.

==Motor damage==

If a player rolls a 20 in 5th gear or a 30 in 6th gear, this puts a strain on their engine. After their car has finished moving they must therefore roll the black die to test whether their engine has withstood the strain. All players who are driving in 5th or 6th gear at this moment must also roll the black die. If a number between 1 and 4 is rolled, the corresponding car loses 1 engine WP.

If a car loses its last engine WP, it is eliminated from the race.

==Damage and road handling==

Each time a car loses a car body WP or an engine WP, a damage marker is placed on the space where the move ended.

The same applies whenever a car is eliminated from the race for whatever reason. These spaces are judged to be "dangerous" from then on.

If a car passes over one of these spaces or lands on it, the driver must roll the black die. If the result is between 1 and 4, the car loses one road handling WP. The dangerous spaces can be avoided by changing lanes.

'''If a car loses its last road handling WP, it is eliminated from the race.'''

==Slipstreaming==

If a car drives in the wake of another car, this is called slipstreaming.

For the two concerned drivers, slipstreaming is possible from the 4th gear on.

The car must be driving as fast or faster than the car in front.

If a car wants to profit from slipstreaming after moving, it has to stop directly behind another car. From this position they can then add 3 spaces onto their last move. They can move forward 3 spaces in the following way:

*change a lane, overtake the car in front and return to the original lane.
*change a lane and move two spaces in a straight line.
*change two lanes and move one space in a straight line.

The player must move a total of three spaces in any case. (However, the driver may use brake WP in order to reduce this number of spaces.) If slipstreaming brings a car up immediately behind another car, they can carry on slipstreaming (and so on).

If a car is carried into a corner by slipstreaming, they lose a brake WP (without the number of spaces being reduced).

In a corner, a slipstreaming car must follow normal driving code (eg. following the arrows).

Braking in order to take advantage of slipstreaming in the wake of another player's car is not allowed.

Drivers do not have to slipstream!

Note that in this implementation, if your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

==Pit stop==

At the end of the first lap, a player may decide to make a pit stop to regain all the tire WP they have lost. There is no speed limit in the pit lanes. It is also not necessary to roll the exact number needed to reach one's own pit.

In the BGA adaptation, your pit box matches the central colour of your car.

To enter the pits it is necessary to roll the minimum number required or higher using the die corresponding to the selected gear. As soon as the car enters the pits, it receives all its tire WP back. The player now rolls the black die, in order to see how fast their mechanics work.

===Result between 1 and 10: quick pit stop===

The player divides the number shown on the black die by two (rounding it up if necessary). The result is the number of spaces the car is allowed to move when the car leaves the pit in 4th gear.

===Result between 11 and 20: slow pit stop===

The car remains in the pit until the next round. Then the car moves on in 4th gear (or a lower gear).

The rules for gearing down, collision, braking and engine damage do not apply in the pit lane. Overtaking is not possible as it is a single lane. Drivers have to be patient and wait until the car ahead of them moves forward, regardless of selected gear and with no effect on the WP.

Cars in the pit lane must wait for their turn, until the cars on the circuit between pit exit and entry have had their turn.

==Finish==

The player whose car passes the finishing line first has won the race. The race ends when all cars have crossed the finishing line, in order to enable ranking.

=Optional Rules=

All the following rules can be used independently of one another.

==Construction of one's own car==

Every player can distribute their 20 WP between the zones of their car at their own discretion. At least 1 WP must be assigned to each zone.

If using the Technical Pit Stops option, 2 additional WPs are available to assign, and players may assign 0-2 points to Repair points.

==Qualifying lap with a stopwatch==

All players drive a qualifying lap with stopwatch consecutively, in order to determine their start positions. The rules for moves and driving code remain unchanged during the qualifier, however the WP are not taken into account. The only exception is if a car overshoots a corner - this is penalized.

* The player whose turn it is to drive a qualifying lap places their car in the middle lane in front of the starting line.
* You may not apply the brakes at all during Qualifying. If a roll forces you to overshoot a corner, it cannot be avoided.
* You may freely Gear down any number of gears during Qualifying, with no cost or penalty.
* The player receives a total number of points over their lap:
**1 point for each round the player takes to complete the lap
**1 point for each space the player overshoots a corner by (soft tires will have their points doubled)
**1 point for every full real-time minute it takes the player to complete the lap

'''Note:''' The qualifying lap is over if the driver does not stop at all in corners where two or three stops are required. They then have to start the race at the back of the field from the last start position.

After that the order of starting is determined: the car which has completed the qualifying lap with the fewest points takes first position. The other cars follow on in decreasing order of points. If two drivers have the same number of points, the real time taken to complete the lap decides: the fastest player gets the better start position.

== Weather Conditions ==

There is a weather chart for each "Formula D" racing circuit, which is available to all players before the game so that they can inform themselves about weather conditions during the race and qualifying laps.

If the weather rules are used, it is strongly recommended that the tire selection rules be used as well.

Before the qualifying laps begin, the black die is rolled and the weather chart consulted:

'''Good weather''' no problems for the drivers.
'''Changeable''': no problems for drivers, treat as good weather for the qualifying lap.
'''Rain''': The qualifying laps for all players take place in rain (see below).

Before the actual race begins, the black die is rolled again and the weather chart consulted:

'''Good weather''': no problem.
'''Changeable''': The sky is overcast at the beginning of the race, but it does not rain '''unless''' it rained during qualifying. Either way, this can change during the course of the race. Whenever a player in 5th gear throws a 20 or a 30 in 6th gear, at the end of the round they have to roll the black die and consult the weather chart:

If "good weather" comes up, the weather conditions are shifted one line upwards.
If "rain" is the result, the weather conditions are shifted one line downwards.
If the result is "changeable", the weather stays the same.

{|
|'''Weather'''||'''Effect on race'''
|-
|Good||None. The weather will no longer change.
|-
|Good (Temporary)||None.
|-
|Changeable||This is the starting step and once the weather conditions shift up or down off Changeable, it will be skipped for the rest of the game.
|-
|Rain (Temporary)||Rain.
|-
|Rain||Rain. The weather will no longer change.
|}

=== Effect of rain ===

* '''Collision''': A result of 1 or 2 (instead of just a 1, as in good weather) means a collision occurs.
* '''Engine damage''': Occurs when result is between 1 and 3 (instead of between 1 and 4, as in good weather).
* '''Road handling''': The car loses one road handling WP for a result between 1 and 5 (instead of between 1 and 4, as in good weather)
* '''Skidding on corners''': Cars will skid on corners depending on their tire selection. See "Selection of tires", below.

== Selection of tires ==

The choice of tires is crucial not just for qualifying lap, but for the race itself. When weather conditions have been determined, each player can fit their car with special tires (see below). It is also possible to change tires between qualifying lap and the race.

=== Hard Tires ===

They are recommended on a dry track and inefficient on a wet track.

* The game rules apply unchanged if the weather is good or changeable.
* If it is raining, the car moves three additional spaces on any turn which contributes to advancing a corner.

=== Soft Tires ===

They are recommended on a dry track and inefficient - if not handicapping - on a wet track.

* If the weather is changeable or good, the car can move one additional space during each move in the qualifying or race laps. This additional move is not compulsory. But if a car overshoots a corner, the penalty is doubled (loss of tire WP). If a driver does not change their tires during a pit stop after the first lap, they lose the bonus. If a driver does not change their tires during a pit stop after the second lap, the penalties for overshooting a corner are trebled.
* If it is raining, the car travels three spaces further on any turn which contributes to advancing a corner. If a driver does not change their tires during a pit stop before beginning the third lap, the penalties for overshooting a corner are trebled.

Note that in this implementation, if your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

=== Rain Tires ===

They are highly recommended if it is raining, but are otherwise very sensitive.

* If the weather is changeable or good, the penalties for overshooting a corner are doubled (loss of tire WP) for qualifying and the first two laps of the race. If a driver does not change their tires before the third race lap, the
penalties are trebled.
* If it is raining, the car travels one space further on any turn which contributes to advancing a corner.

== Technical Pit Stops ==

Your pit has 2 WP which can be used during the race to regain lost WP (with the exception of tire WP). Every time a driver makes a pit stop they can choose between two options:

* '''Tire pit stop''': As in the rules for advanced players, except that the driver may change the type of tire whenever they change tires.
* '''Technical pit stop''': The driver can change their tires (see above) and in addition regain up to two WP in one or two zones (except the tires). This "reservoir" of 2 WP applies for the entire duration of the race, even if it lasts for more than two laps. In the next round, the car may not start higher than 4th gear. A car with soft tires does not profit from the bonus of an additional space when leaving the pits.

== Team Race ==

A game using these rules is appropriate for a large group with an even number of players. The players form teams each with two players; each colour corresponds to a racing team. Apart from the following two exceptions, the rules apply unchanged:

* '''Pit stop''': Each team has 4 WP to repair the cars. Both players must decide together how they want to use these points.
* '''Winner by points''': A team race is not necessarily won by the first car to cross the finishing line. Each car receives a certain number of winning points. The team with the highest number of total points wins the race.

{|
|'''Ranking''||'''No. of points'''
|-
|1||1000
|-
|2||720
|-
|3||600
|-
|4||480
|-
|5||400
|-
|6||320
|-
|7||240
|-
|8||160
|-
|9||80
|-
|10||40
|}

Note that these points differ from the published rules. If qualifying is enabled, qualifying points are also awarded equally to both members of the team.

== Nitro Fuel ==

When this option is chosen, all cars have a Nitro Fuel injection, which allows instant acceleration. Players can use their nitro once a lap after rolling the corresponding gear die. They receive a movement bonus according to the gear they are using at that moment (1 space in 1st gear, 2 spaces in 2nd gear, etc.). This bonus must be used completely.

When a car pits, or crosses the finish line at the end of a lap, it replenishes its nitro fuel and may use it again.

Nitro may only be used if it is available when rolling the gear die. It does not become available during the same move where you complete a lap.

= BGA Rule Variations=

The BGA Adaptation of Formula D uses a number of variations from the Masters (Tournament) rules.

The differences from the rules you will find in your own copy of Formula D are:

==Round Order ==

In the original rules, if two cars are level with each other, the driver with the highest gear plays first. If both cars are in the same gear, the car nearest the inside with reference to the next (or the current) corner plays first.

In this adaptation, the higher gear continues to be first but if both cars are in the same gear *then the player who first arrived at their space* goes first. Corners no longer affect who goes first.

==Points ==

In this adaptation, points are awarded for race completion '''and''' for Qualifying (if enabled). The Qualifying points are minor by comparison and serve as a tie-break if two players are both eliminated and score 0 in the race.

{|
|'''Ranking'''||'''Race Points'''||'''Qualifying Points'''
|-
|1||1000||10
|-
|2||720||9
|-
|3||600||8
|-
|4||480||7
|-
|5||400||6
|-
|6||320||5
|-
|7||240||4
|-
|8||160||3
|-
|9||80||2
|-
|10||40||1
|}

To cover multiple players being eliminated during a game where there is no Qualifying, their distance travelled before being eliminated is used as the final tie-break (only in non-team games). If a player overshoots a corner or crashes into the back of other cars, their position at the '''start''' of the turn is used.

==Braking ==

The original rules provide a table that describes the outcome of "Emergency Braking" (when a car is blocked by one or more cars which they are unable to overtake). The table does not take Constructed Cars into account, so to clarify, the implemented rules are:

If a player performs Emergency Braking, they must move their car forward as many spaces as possible. If they need to brake more than 3 spaces, they are required to use Brake WPs for the first 3 spaces, and each subsequent space may be paid for using Brake WP *or* Tire WPs.

Braking is paid for *after* Overshooting, so any Tire WPs lost to Overshooting will not be available for Emergency Braking.

==Qualifying ==

Players do not roll the black starting die at the beginning of Qualifying: they just start in 1st gear.

The original rules simply state that "WP are not taken into account" during qualifying. However, the effect of this is clarified in this adaptation:

* You may not apply the brakes at all during Qualifying. If a roll forces you to overshoot a corner, it cannot be avoided.
* You may freely Gear down any number of gears during Qualifying, with no cost or penalty.

In this version, Qualifying awards points as long as you complete your lap:

{|
|'''Ranking''||'''No. of points'''
|-
|1||10
|-
|2||9
|-
|3||8
|-
|4||7
|-
|5||6
|-
|6||5
|-
|7||4
|-
|8||3
|-
|9||2
|-
|10||1
|}

==Collision Checks ==

In this adaptation, the active player checks for collisions only after all adjacent players have rolled. If an adjacent player fails their roll and is eliminated as a result, the active player will automatically fail their roll against that player.

==Weather Options==

When setting up a game with Advanced rules, you have 4 choices for the weather.

===Roll for Weather===

This is the normal approach when using the weather rules: at the start of the race (and, separately, at the start of Qualify if it's been enabled) the Weather die is rolled to determine whether the race's weather will be Good (for the entire race) or Rain (for the entire race) or Changeable.

===Good Weather===

This option skips the opening Weather roll and the race plays with permanent Good weather.

===Rain===

This option skips the opening Weather roll and the race players with permanent Rain.

===Start Changeable===

This option skips the opening Weather roll and treats it as if "Changeable" had been rolled. However the Weather die is rolled to see if the weather starts in Rain. On a Rain result it does, on "Good" or "Changeable" the weather starts good, but either way it is changeable.

==Qualifying Weather Options==

When Qualifying is enabled, you may choose the weather option for it.

===Same as Race===

This is the default. The same setting that is used for "Race Weather" is also used for Qualifying. Note that although the setting is the same, the outcome can be different when "Roll for Weather" is being used.

===Random Weather===

The weather will be randomly chosen before Qualifying. It will NOT be changeable and will be the same outcome (Rain or Good) for all players.

===Good Weather===

Qualifying will be in good weather for all players.

===Rain===

Qualifying will be in rain for all players.

==Weather Rolls ==

In the original rules, the Weather die is thrown immediately when a player rolls the maximum number in 5th or 6th gear. In this adaptation, this roll still occurs but it is deferred until the end of the round. This way, weather can only change between rounds and not in the middle of a player's turn. If multiple players roll the maximum number, the weather die will be rolled multiple times.

==Changeable Weather ==

The original rules have 4 steps for Changeable Weather:
* Good
* Good - Changeable
* Rain - Changeable
* Rain

In this adaptation, there are 5 steps:
* Good
* Good - Temporary
* Changeable
* Rain - Temporary
* Rain

Changeable is only ever used at the start of a race, and by default is Good - with one exception: if it rained in qualifying then a changeable feature race will start Changeable but raining.

Weather will never be changeable in qualifying: it will be Good unless Rain is rolled.

==Spinning ==

The original rules state that if a car on 0 Tire WP overshoots a corner then it "will again spin round in a circle. If the car overshoots the corner by more than one space, it is out of the race". In this adaptation, a car with 0 Tire WP is eliminated if it overshoots a corner by more than 1 WP. Hence, even a single space overshoot will eliminate a 0 Tire WP car on soft tires.

Additionally, in this adaptation when you spin, your Tire WP are reset to 1 WP (instead of remaining at 0 WP).

==Skidding on Corners in the Rain ==

The original rules state that cars will skid in the rain "provided at least one space of the move lies within the limits of a corner". In this adaptation, skidding will only occur on any turn that counts towards a corner's completion. That means:

* Driving through a corner that you have already completed will ''not'' cause you to skid
* If you are on the final space in a corner and still need to land in it 1 more turn, you will skid on your next move even though you are driving into a straight

==Slipstreaming==

If your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

==Motor Damage Checks==

Motor damage checks are always performed in round order.

==Braking in the Pit Lane ==

The original rules state that the rules for braking do not apply in the pit lane. In this adaptation, there is no braking cost for stopping immediately behind another car, or in your pit box. However, there is a brake cost for travelling any distance shorter than that.

== Pit Boxes ==

In Individual Driver games, a single pit box will be reserved for each driver instead of drivers being assigned a pit box color. The box will be indicated with the player's avatar.

== Pit Lane ==

The rules for gearing down DO apply in the pit lane.

There are also minimum gears that may be used in the pit lane:

* Once a player has entered the pit lane, they must choose a gear which would allow their car to enter their pit box on a maximum roll. If they cannot use such a gear, they must use the highest gear permitted by their previous move.

* Exiting the pits: 1st gear is prohibited to drivers from their pit box to the outlet of the pit lane, except when 2nd gear might be unsafe

== Pit Stops ==

The soft tire bonus may not be used when moving after a Quick Pit Stop.

If Technical Pit Stops are enabled, players may always choose to take one (and thus finish their turn) even if they have no repair points or repairs to perform.

==Construction of one's own car ==

In this adaptation, if players have selected the option to Construct their own car then there are no limits to how many points they may assign to any given area.

In games that have also selected the Technical Pit Stop rules, then instead of having a fixed 2 WPs available for Pit repairs, a player will have 22 WPs to use in Construction and can choose how many repair points to make available, with a maximum of 2.

==Road Races ==

The Road Race rules, including Drivers with special abilities, are not used.

Where Road Race circuits are used, all non-standard rules are ignored.

Nitro Fuel Injection is available as an option for all races.

==Elimination ==

When a player is eliminated, the outcome is slightly different from the published rules.

*If the elimination was caused by the player overshooting corners, or driving over a damage marker, or quitting, the car is immediately removed from the board and '''no damage marker is placed'''
*If the elimination was caused by the player failing a motor damage test, the car is immediately removed from the board and a damage marker is added.
*If the player is eliminated by any other reason, a damage marker is added and the car remains on the board until the end of the round, when it is removed.

Bugsclarification formulad

2026-01-21T03:38:10Z

BaronFraser:

== Display ==

=== The Circuit is Black on My Display===

If you're using Firefox, it's been noted that the cache can sometimes fail. Refreshing the BGA cache seems to fix it:

# Goto the BGA website.
# Click padlock to the left of the site URL
# Click "Clear cookies and site data..."
# Close Firefox Browser
[[File:Clear Firefox Cookies and Site Data.jpg]]

==Corners==

===I Stopped In A Corner But It Did Not Count===

Did you fully stop in all previous corners? All corner stops are required. If you miss a stop in one corner and end your turn in a second corner, that stop counts ONLY AGAINST THE FIRST CORNER. You still need to stop in the second corner and if you move out of it without stopping again, you will be overshooting.

===I Exited A Corner And Crashed - Why?===

Did you fully stop in all previous corners? If you skip Corner 1 and end your turn in Corner 2, that move only counts against Corner 1 and you STILL have to finish a turn in Corner 2. If you move out of Corner 2 at speed without stopping again in it, you will probably destroy your tires.

===I Wasn't Able To Enter the Pits After Exiting A Corner ===

If you overshoot a corner, you are forced to travel in a straight line, so cars are unable to enter the pits on the same turn as overshooting a corner.

===I Was Allowed To Change Lanes After Leaving A Corner ===

Some players have been confused by the line in the rules "When coming out a corner the car may not change lanes". Note that this line appears in the '''Overshooting''' section and is ''only'' intended to apply to cars that are overshooting a corner.

==Collisions==

===A Car Ended It's Move Next To Another Car But No Collision Was Rolled===

Collisions are not rolled when a car ends its move IN FRONT of another car.

==Pit Stops==

===I Wasn't Able To Enter the Pits After Exiting A Corner ===

If you overshoot a corner, you are forced to travel in a straight line, so cars are unable to enter the pits on the same turn as overshooting a corner.

==Suggestions==

===Can You Change It So That Players Can Qualify Simultaneously?===

This is a great idea in principle, but unfortunately the adaptation was not developed with this functionality in mind and to implement it retrospectively would be a massive undertaking, requiring reworking all internal code to support multiple simultaneous boards, developing multi-player versions of the key user interaction steps, and adding a user interface to the client to allow players to switch between different boards.

As it stands, it's not worth the effort to make such a massive conversion, even though there's no denying that it would make realtime games with qualifying a lot faster.

If it's any consolation, imagine you're playing the actual board game where you also have to do it one at a time...

Bugsclarification formulad

2026-01-17T23:24:30Z

BaronFraser:

File:Clear Firefox Cookies and Site Data.jpg

2026-01-17T23:24:06Z

BaronFraser:

A screenshot of clearing Cookies and Site Data in Firefox

Bugsclarification formulad

2026-01-17T23:21:25Z

BaronFraser:

== Display ==

=== The Circuit is Black on My Display===

If you're using Firefox, it's been noted that the cache can sometimes fail. Refreshing the BGA cache seems to fix it:

# Goto the BGA website.
# Click padlock to the left of the site URL
# Click "Clear cookies and site data..."
# Close Firefox Browser
[[File:Skärmbild_2026-01-17_095452.png]]

==Corners==

===I Stopped In A Corner But It Did Not Count===

Did you fully stop in all previous corners? All corner stops are required. If you miss a stop in one corner and end your turn in a second corner, that stop counts ONLY AGAINST THE FIRST CORNER. You still need to stop in the second corner and if you move out of it without stopping again, you will be overshooting.

===I Exited A Corner And Crashed - Why?===

Did you fully stop in all previous corners? If you skip Corner 1 and end your turn in Corner 2, that move only counts against Corner 1 and you STILL have to finish a turn in Corner 2. If you move out of Corner 2 at speed without stopping again in it, you will probably destroy your tires.

===I Wasn't Able To Enter the Pits After Exiting A Corner ===

If you overshoot a corner, you are forced to travel in a straight line, so cars are unable to enter the pits on the same turn as overshooting a corner.

===I Was Allowed To Change Lanes After Leaving A Corner ===

Some players have been confused by the line in the rules "When coming out a corner the car may not change lanes". Note that this line appears in the '''Overshooting''' section and is ''only'' intended to apply to cars that are overshooting a corner.

==Collisions==

===A Car Ended It's Move Next To Another Car But No Collision Was Rolled===

Collisions are not rolled when a car ends its move IN FRONT of another car.

==Pit Stops==

===I Wasn't Able To Enter the Pits After Exiting A Corner ===

If you overshoot a corner, you are forced to travel in a straight line, so cars are unable to enter the pits on the same turn as overshooting a corner.

File:Skärmbild 2026-01-17 095452.png

2026-01-17T23:20:19Z

BaronFraser:

Screenshot of clearing site cookies in Firefox

Bugsclarification formulad

2026-01-17T23:18:53Z

BaronFraser: Added The Circuit is Black on My Display entry

== Display ==

=== The Circuit is Black on My Display===

If you're using Firefox, it's been noted that the cache can sometimes fail. Refreshing the BGA cache seems to fix it:

# Goto the BGA website.
# Click padlock to the left of the site URL
# Click "Clear cookies and site data..."
# Close Firefox Browser

[https://1drv.ms/i/c/e6131ec33915ec1b/IQDHDfzM93vTSrq4O4KDSqvrAUlDhPZQvs8sCZp4elsssBI?e=VeTl85 Illustrating screen shot here]

==Corners ==

===I Stopped In A Corner But It Did Not Count===

Did you fully stop in all previous corners? All corner stops are required. If you miss a stop in one corner and end your turn in a second corner, that stop counts ONLY AGAINST THE FIRST CORNER. You still need to stop in the second corner and if you move out of it without stopping again, you will be overshooting.

===I Exited A Corner And Crashed - Why?===

Did you fully stop in all previous corners? If you skip Corner 1 and end your turn in Corner 2, that move only counts against Corner 1 and you STILL have to finish a turn in Corner 2. If you move out of Corner 2 at speed without stopping again in it, you will probably destroy your tires.

===I Wasn't Able To Enter the Pits After Exiting A Corner ===

If you overshoot a corner, you are forced to travel in a straight line, so cars are unable to enter the pits on the same turn as overshooting a corner.

===I Was Allowed To Change Lanes After Leaving A Corner===

Some players have been confused by the line in the rules "When coming out a corner the car may not change lanes". Note that this line appears in the '''Overshooting''' section and is ''only'' intended to apply to cars that are overshooting a corner.

== Collisions==

===A Car Ended It's Move Next To Another Car But No Collision Was Rolled===

Collisions are not rolled when a car ends its move IN FRONT of another car.

==Pit Stops==

===I Wasn't Able To Enter the Pits After Exiting A Corner===

If you overshoot a corner, you are forced to travel in a straight line, so cars are unable to enter the pits on the same turn as overshooting a corner.

Gamehelpformulad

2026-01-15T06:06:43Z

BaronFraser:

= 10-Second Explainer of Formula D =
New to Formula D?

This 20-second explainer will get you started:

# Your car will start in 1st gear.
# At the start of your turn, your first decision is whether to stay on your current gear, or go up 1 gear or go down.
# You can go down 1 gear without penalty, or "skip" up to 3 gears at the cost of wear points. You may only go up by 1 gear per turn.
# After choosing a gear, you will roll the appropriate "gear die". The higher the gear, the bigger the die, as well as the farther you go.
# Once you have rolled, you must move the number of spaces rolled, although you may choose which lane you take.
# Corners are areas marked in red. To drive around corners without penalty, you must finish at least 1 turn in them.
# Some corners are particularly slow and may require that you finish at least 2 or even 3 turns in them.

That's it! There's a lot more to it than that, but this covers the absolute basics of driving safely around the track.

= Important: BGA Rule Variations =

The BGA Adaptation of Formula D uses a number of variations from the Masters (Tournament) rules.

[[#BGA Rule Variations|At the end of these rules]], you will find a list of all differences from the published game rules.

=Adaptation Notes/Common Mistakes=

# The body of your car is the colour of the pit box you are using (or your team's color if playing a team game)
# Your sidepods are your personal color
# To enter the pitbox, you must move out of the pit lane and onto the coloured pit box. Stopping in the pit lane in front of your box is not a pit stop.
# To zoom the circuit in and out with a mouse, use Ctrl+Wheelmouse.

=Basic Rules=

== Aim of the game ==

FORMULA D is a car race. The aim is to win a race (of one, two, or three laps) and be the first to cross the finishing line. There are all sorts of risks involved and you have to anticipate what will happen during the course of the race. You must decide on your strategy, trust to luck, keep to the rules and always keep an eye on the technical condition of your car.

== The gears ==

The cars have 6 gears. Each gear has its own die. The numbers on the dice tell you how many spaces to move the car. The higher the gear you choose, the faster and farther the corresponding die will allow the car to travel. You are not allowed to skip gears when accelerating (e.g. changing straight from 1st to 3rd gear). You are allowed to skip 1, 2 or 3 gears when braking (e.g. from 6th to 4th or from 4th to 1st gear); however there is a penalty for doing this. You cannot go from 6th gear to 1st.

{|
!Gear!! Color||Die||Movement (Number of spaces)
!Face distribution
|-
|1||Yellow||d4||1-2
|1,1,2,2
|-
|2||Orange||d6||2-4
|2,3,3,4,4,4
|-
|3||Red||d8||4-8
|4,5,6,6,7,7,8,8
|-
|4||Green||d12||7-12
|2 of each
|-
|5||Purple||d20||11-20
|2 of each
|-
|6||Blue||d20||21-30
|2 of each
|}

==Driving ==

As in real life the car starts in 1st gear. Then you shift up to 2nd gear and so on up to 6th gear, in order to move as fast as possible. When it is a driver’s turn they announce which gear they have chosen, move the gear stick on their dashboard accordingly and then roll the die which corresponds to the chosen speed. They then move their car forward the number of spaces indicated on the die. When the move is finished the car “stops”. This notion is especially important in the corners.

'''Order of play''': In each round the drivers play according to their car position on the track, with the current gear deciding tie-breakers, and the first one there is the final decider.

Example: During a round of play car A overtakes car B which was in 1st position. When the next round starts, car A, now in 1st position, will play before car B.

Cars in the straight outside the pit lane will always move before cars in the pit lane. When two cars are level, the car in the highest gear goes first. When cars are level and in the same gear, the car that arrived in their current space first will go first.

==Driving Code ==

The cars drive in the track lanes. Different driving codes apply to corners and straights. It is generally not allowed to go over other cars – they must be driven round. Driving backwards is also not allowed.

===Driving code in the corners ===

To drive through a corner a car must stop a minimum number of times (indicated in the corner information box) within the limits of the corner. The number of filled red circles indicates the number of stops for that corner. After the requisite number of stops, the car may safely exit the corner, without penalty, on its next move.

To make it easier to drive through the corner, the driver should consider the indicated number of spaces. The number in the green box refer to the longest path, the numbers in the red box refer to the shortest path. Refer to these when deciding the gear you enter the corner in.

===Driving code on the straights ===

Straights are the portions of track between corners. Depending on the length of each straight, cars may need several rounds before entering the next corner.

'''Important''': The maneuver must be completed using the smallest number of spaces possible. (ex. You can't fishtail back and forth between the inside and outside edges)

==Wear points (WP) ==

They reflect the capability of the car to stay on the track and survive events during the race. In the Basic Game, each car has 18 WP at the beginning of the race. The players use these points to survive various incidents and risky maneuvers. In the advanced game, they are divided up into different categories that are used in different situations.

==Preparation for play ==

===Start formation ===

Every player rolls the black die in order to determine the starting position of their car. Whoever rolls the highest number gains pole position. The other cars are positioned in decreasing order according to the numbers rolled. In the case of a tie, all '''involved''' players re-roll the die.

===Start ===

Before engaging 1st gear, every player rolls the black die to see how successfully they can start.

'''Number rolled: 1 – poor start'''. The player has stalled the motor of their car. They cannot engage 1st gear and so they have to wait till the next round. Then they can start in 1st gear without having to roll the black die again.

'''Number rolled: between 2 and 16''' – normal start. The player can start normally. They roll the die for 1st gear and moves their car forward according to the number rolled.

'''Number rolled: between 17 and 20''' – great start! The player makes a fantastic start. They moves their car forward 4 spaces immediately, although they is still in 1st gear. The car can change one or two lanes to avoid other cars. The driver may shift to 2nd gear in the next round.
==Overshooting==

If a car passes through a corner at the end of its turn without making the required number of stops, it overshoots the corner. The number of spaces the car overshot the corner by is deducted from the car’s WP as a penalty.

'''Corner with 2 stops''': If the car has made no stops, it is automatically removed from play.

'''Corner with 3 stops''': If the car has made no stops, or only one stop, it is automatically removed from play.

When coming out of a corner the car may not change lane, but must stay in the same lane. If the move ends in another corner, this stop does not count for the new corner. If the car is blocked by another car, they cannot drive round it and has to brake.

==Braking==

A player may use their WP at any time to avoid having to advance the full number of spaces shown on the die. In this way they can control their progress better, for example when the lanes are blocked by other cars.

==Changing down==

A driver can skip one, two or three gears when changing down, however this wears out their gearbox. The number of gears skipped equates to the number of WP their car loses as a result. Note: It is not possible to skip four gears (from 6th to 1st gear).

==Collision==

Whenever a car ends its move on a space next to or behind one or several cars, there is a risk of collision. A driver in this situation must roll the black die to see whether there is a collision or not. If they roll a number between 1 and 4 their car loses 1 WP.

==Motor damage==

If a player rolls a 20 in 5th gear or a 30 in 6th gear, this puts a strain on their engine. After their car has finished moving they must therefore roll the black die to test whether their engine has withstood the strain. All players who are driving in 5th or 6th gear at this moment must also roll the black die. If a number between 1 and 4 is rolled, the corresponding car loses 1 WP.

==Finish==

The player whose car passes the finishing line first has won the race. The race ends when all cars have crossed the finishing line, in order to enable ranking.

==Two-lap race==

For players who have already played several single-lap games.

Whoever crosses the finishing line first after two laps wins the game. Players may make a pit stop between the first and second laps to regain the WP points they lost during the first round.

==Pit stop==

At the end of the first lap a player may decide to make a pit stop to regain all the WP they have lost. There is no speed limit in the pit lanes. It is also not necessary to roll the exact number needed to reach one’s own pit.

In the BGA adaptation, your pit box matches the colour of your car's central strip.

===Entering pits===

To enter the pits it is sufficient to roll the minimum number required or higher using the die corresponding to the selected gear. The car receives all 18 WP back and awaits their next turn to start from the pits in 4th gear (maximum).

The rules for changing down gear, collision, braking and engine damage do not apply in the pit lane. Overtaking is not possible as it is a single lane. Drivers have to be patient and wait until the car ahead of them moves forward, regardless of selected gear and with no effect on the WP.

Cars in the pit lane must wait for their turn, until the cars on the circuit between pit exit and entry have had their turn.

There are minimum gears required in the pit lane:

* Once a player has entered the pit lane, they must choose a gear which would allow their car to enter their pit box on a maximum roll. If they cannot use such a gear, they must use the highest gear permitted by their previous move.

* Exiting the pits: 1st gear is prohibited to drivers from their pit box to the outlet of the pit lane, except when 2nd gear might be unsafe

=Advanced Rules=

==Basics==

===The gears===

The cars have 6 gears, each gear has its own die. The numbers on the dice tell you how many spaces to move the car. The higher the gear you choose, the faster and further the corresponding die will allow the car to travel. You are not allowed to skip gears when accelerating (e.g. changing straight from 1st to 3rd gear). You are allowed to skip 1, 2, or 3 gears when braking (e.g. from 6th to 4th or from 4th to 1st gear); however there is a penalty for doing this.

{|
!Gear!! Die Color||Die Size||Movement (Number of spaces)
|-
|1||Yellow||d4||1-2
|-
|2||Orange||d6||2-4
|-
|3||Red||d8||4-8
|-
|4||Green||d12||7-12
|-
|5||Purple||d20||11-20
|-
|6||Blue||d20||21-30
|}

===Driving===

As in real life, the car starts in 1st gear. Then you up shift to 2nd gear and so on up to 6th gear, in order to move as fast as possible. When it is a driver’s turn they announce which gear they have chosen, move the gear stick on their dashboard accordingly and then rolls the die which corresponds to the chosen speed. They then moves their car forward the number of spaces indicated on the die. When the move is finished the car “stops”. This notion is important especially in the corners.

====Order of play====

In each round the drivers play according to their car position on the track.

Example: During a round of play car A overtakes car B which was in 1st position. When the next round starts, car A, now in 1st position, will play before car B.

Cars in the straight outside the pit lane will always move before cars in the pit lane. When two cars are level, the car in the highest gear goes first. When cars are level and in the same gear, the car that arrived in their current space first will go first.

==== Same position====

If two cars on the track are level with each other, the driver with the highest gear plays first.

If both cars are in the same gear, the car that arrived first at their current space plays first.

===Driving Code===

The cars drive in the track lanes. Different driving codes apply to corners and straights. It is generally not allowed to go over other cars – they must be driven round. Driving backwards is also not allowed.

====Driving code in the corners====

To drive through a corner a car must stop a minimum number of times (indicated by the number of red stop lights in the corner information box) within the limits of the corner. After the requisite number of stops, the car may proceed and exit the corner on its next move.

To make it easier to drive through the corner, the driver should consider the indicated number of spaces. The number in the green box refers to the longest path, the numbers in the red box refers to the shortest path. Refer to these numbers when considering what gear to enter the corner in.

====Driving code on the straights====

Straights are the portions of track between corners. Depending on the length of each straight, cars may need several rounds before entering the next corner.

'''Important''': The maneuver must be completed using the smallest number of spaces possible.

=== Wear points (WP)===

Wear Points reflect the ability of the car to stay on the track and survive events during the race. Each car has a certain number of WP at the beginning of the race, which are divided up between six different categories. These points are distributed as follows in the game for advanced players:

{|
|WP tires:||6
|-
|WP brakes:||3
|-
|WP gearbox:||3
|-
|WP car body:||3
|-
|WP engine:||3
|-
|WP road handling:||2
|}

==Preparation for play==

===Start formation===

Every player rolls the black die in order to determine the starting position of their car. Whoever rolls the highest number gains pole position. The other cars are positioned in decreasing order according to the numbers rolled. (ln the case of a tie, all concerned players re-roll the die.)

===Start===

Before engaging 1st gear, every player rolls the black die to see how successfully they can start.

====Number rolled, 1 - poor start====

The player has stalled the motor of their car. They cannot engage 1st gear and so have to wait till the next round. Then they can start in 1st gear without having to roll the black die again.

====Number rolled: between 2 and 19 - normal start====

The player can start normally. They roll the die for 1st gear and moves their car forward according to the number rolled.

====Number rolled: 2O - great start!====

The player makes a fantastic start. They move their car forward 4 spaces immediately, although they is still in 1st gear. The car can change one or two lanes to avoid other cars. The driver may shift to 2nd gear in the next round.

==Overshooting==

If a car passes through a corner at the end of its turn without making the required number of stops, it overshoots the corner. The number of spaces the car overshot the corner by is deducted from the car’s tire WP as a penalty.

'''Corner with 2 stops''': If the car has made no stops, it is automatically removed from play.

'''Corner with 3 stops''': If the car has made no stops, or only one stop, it is automatically removed from play.

When coming out of a corner the car may not change lane, but must stay in the same lane. If the move ends in another corner, this stop does not count for the new corner. If the car is blocked by another car, they cannot drive round it and has to brake.

When a car loses their last tire WP by overshooting a corner, they spin round in a circle. The car is placed on the space where their move ended, pointing backwards. The player must turn their car round again and drive off in 1st gear when it is their next turn. In this adaptation, their Tire WPs are reset to 1.

If a car loses more tire WP than it possesses, it is eliminated from the race.

==Braking==

A player may use their brake WP at any time to avoid having to advance the full number of spaces shown on the die. This can help to prevent losing tire WP if they would otherwise overshoot a corner.

A driver can find themselves blocked by one or more cars which they are unable to overtake. After the driver has moved their car forward as many spaces as possible, they counts how many spaces they would have moved if they had not been blocked.

If the number of spaces short of the full number 4 or greater, they may use Emergency Braking. In this case, their first 3 spaces must be paid for with Brake WP. Each additional space after that may be paid by either Brake or Tire WP.

Braking is paid for *after* Overshooting, so any Tire WPs lost to Overshooting will not be available for Emergency Braking.

If a car doesn't have enough brake WP and tire WP to stop before a blockage, it is eliminated from the race.

==Gearing down==

A driver can skip one, two or three gears when changing down, however this wears out their gearbox.

As a result, the car then loses a certain number of brake WP, engine WP and gearbox WP. The table below lists the corresponding wear. Note: It is not possible to skip four gears (from 6th to 1st gear).

{|
!Gears skipped!!Gearbox WP!!Brake WP!!Engine WP
|-
|1 gear||1||0||0
|-
|2 gears||1||1||0
|-
|3 gears||1||1||1
|}

If a car has no gearbox WP left, the driver can only change clown one gear at a time until the game is over.

==Collision==

Whenever a car ends its move on a space next to or behind one or several cars, there is a risk of collision. A driver in this situation must roll the black die to see whether there is a collision or not. If they rolls a 1, their car loses 1 WP.

'''In this adaptation''' the car that did not just move rolls first. If it fails the roll and is eliminated from the race as a result, the car that moved will automatically fail its roll.

'''If a car loses its last car body WP, it is eliminated''' from the race.

==Motor damage==

If a player rolls a 20 in 5th gear or a 30 in 6th gear, this puts a strain on their engine. After their car has finished moving they must therefore roll the black die to test whether their engine has withstood the strain. All players who are driving in 5th or 6th gear at this moment must also roll the black die. If a number between 1 and 4 is rolled, the corresponding car loses 1 engine WP.

If a car loses its last engine WP, it is eliminated from the race.

==Damage and road handling==

Each time a car loses a car body WP or an engine WP, a damage marker is placed on the space where the move ended.

The same applies whenever a car is eliminated from the race for whatever reason. These spaces are judged to be "dangerous" from then on.

If a car passes over one of these spaces or lands on it, the driver must roll the black die. If the result is between 1 and 4, the car loses one road handling WP. The dangerous spaces can be avoided by changing lanes.

'''If a car loses its last road handling WP, it is eliminated from the race.'''

==Slipstreaming==

If a car drives in the wake of another car, this is called slipstreaming.

For the two concerned drivers, slipstreaming is possible from the 4th gear on.

The car must be driving as fast or faster than the car in front.

If a car wants to profit from slipstreaming after moving, it has to stop directly behind another car. From this position they can then add 3 spaces onto their last move. They can move forward 3 spaces in the following way:

*change a lane, overtake the car in front and return to the original lane.
*change a lane and move two spaces in a straight line.
*change two lanes and move one space in a straight line.

The player must move a total of three spaces in any case. (However, the driver may use brake WP in order to reduce this number of spaces.) If slipstreaming brings a car up immediately behind another car, they can carry on slipstreaming (and so on).

If a car is carried into a corner by slipstreaming, they lose a brake WP (without the number of spaces being reduced).

In a corner, a slipstreaming car must follow normal driving code (eg. following the arrows).

Braking in order to take advantage of slipstreaming in the wake of another player's car is not allowed.

Drivers do not have to slipstream!

Note that in this implementation, if your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

==Pit stop==

At the end of the first lap, a player may decide to make a pit stop to regain all the tire WP they have lost. There is no speed limit in the pit lanes. It is also not necessary to roll the exact number needed to reach one's own pit.

In the BGA adaptation, your pit box matches the central colour of your car.

To enter the pits it is necessary to roll the minimum number required or higher using the die corresponding to the selected gear. As soon as the car enters the pits, it receives all its tire WP back. The player now rolls the black die, in order to see how fast their mechanics work.

===Result between 1 and 10: quick pit stop===

The player divides the number shown on the black die by two (rounding it up if necessary). The result is the number of spaces the car is allowed to move when the car leaves the pit in 4th gear.

===Result between 11 and 20: slow pit stop===

The car remains in the pit until the next round. Then the car moves on in 4th gear (or a lower gear).

The rules for gearing down, collision, braking and engine damage do not apply in the pit lane. Overtaking is not possible as it is a single lane. Drivers have to be patient and wait until the car ahead of them moves forward, regardless of selected gear and with no effect on the WP.

Cars in the pit lane must wait for their turn, until the cars on the circuit between pit exit and entry have had their turn.

==Finish==

The player whose car passes the finishing line first has won the race. The race ends when all cars have crossed the finishing line, in order to enable ranking.

=Optional Rules=

All the following rules can be used of one another.

==Construction of one's own car==

Every player can distribute their 20 WP between the zones of their car at their own discretion. At least 1 WP must be assigned to each zone.

If using the Technical Pit Stops option, 2 addition WPs are available to assign, and players may assign 0-2 points to Repair points.

==Qualifying lap with a stopwatch==

All players drive a qualifying lap with stopwatch consecutively, in order to determine their start positions. The rules for moves and driving code remain unchanged during the qualifier, however the WP are not taken into account. The only exception is if a car overshoots a corner - this is penalized.

* The player whose turn it is to drive a qualifying lap places their car in the middle lane in front of the starting line.
* You may not apply the brakes at all during Qualifying. If a roll forces you to overshoot a corner, it cannot be avoided.
* You may freely Gear down any number of gears during Qualifying, with no cost or penalty.
* The player receives a total number of points over their lap:
**1 point for each round the player takes to complete the lap
**1 point for each space the player overshoots a corner by (soft tires will have their points doubled)
**1 point for every full real-time minute it takes the player to complete the lap

'''Note:''' The qualifying lap is over if the driver does not stop at all in corners where two or three stops are required. They then have to start the race at the back of the field from the last start position.

After that the order of starting is determined: the car which has completed the qualifying lap with the fewest points takes first position. The other cars follow on in decreasing order of points. If two drivers have the same number of points, the real time taken to complete the lap decides: the fastest player gets the better start position.

== Weather Conditions ==

There is a weather chart for each "Formula D" racing circuit, which is available to all players before the game so that they can inform themselves about weather conditions during the race and qualifying laps.

lf the weather rules are used, it is strongly recommended that the tire selection rules be used as well.

Before the qualifying laps begin, the black die is rolled and the weather chart consulted:

'''Good weather''' or '''Changable''': no problems for drivers
'''Rain''': The qualifying laps for all players take place in rain (see below).

Before the actual race begins, the black die is rolled again and the weather chart consulted:

'''Good weather''': no problem.
'''Changeable''': The sky is overcast at the beginning of the race, but is does not rain '''unless''' it rained during qualifying. Either way, this can change during the course of the race. Whenever a player in 5th gear throws a 20 or a 3O in 6th gear, at the end of the round they have to roll the black die and consult the weather chart:

If "good weather" comes up. the weather conditions are shifted one line upwards.
If "rain" is the result, the weather conditions are shifted one line downwards.
If the result is "changeable", the weather stays the same.

{|
|'''Weather'''||'''Effect on race'''
|-
|Good||None. The weather will no longer change.
|-
|Good (Temporary)||None.
|-
|Changable||This is the starting step and once the weather conditions shift up or down off Changeable, it will be skipped for the rest of the game.
|-
|Rain (Temporary)||Rain.
|-
|Rain||Rain. The weather will no longer change.
|}

=== Effect of rain ===

* '''Collision''': A result of 1 or 2 (instead of just a 1, as in good weather) means a collision occurs.
* '''Engine damage''': Occurs when result is between 1 and 3 (instead of between 1 and 4, as in good weather).
* '''Road handling''': The car loses one road handling WP for a result between 1 and 5 (instead of between 1 and 4, as in good weather)
* '''Skidding on corners''': Cars will skid on corners depending on their tire selection. See "Selection of tires", below.

== Selection of tires ==

The choice of tires is crucial not just for qualifying lap, but for the race itself. When weather conditions have been determined, each player can fit their car with special tires (see below). It is also possible to change tires between qualifying lap and the race.

=== Hard Tires ===

They are recommencled on a dry track and inefficient on a wet track.

* The game rules apply unchanged if the weather is good or changeable.
* If it is raining, the car moves three additional spaces on any turn which contributes to advancing a corner.

=== Soft Tires ===

They are recommended on a dry track and inefficient - if not handicapping - on a wet track.

* If the weather is changeable or good, the car can move one additional space during each move in the qualifying or race laps. This additional move is not compulsory. But if a car overshoots a corner, the penalty is doubled (loss of tire WP). if a driver does not change their tires during a pit stop after the first lap, they lose the bonus. If a driver does not change their tires during a pit stop after the second lap, the penalties for overshooting a corner are trebled.
* If it is raining, the car travels three spaces further on any turn which contributes to advancing a corner. If a driver cloes not change their tires during a pit stop before beginning the third lap, the penalties For overshooting a corner are trebled.

Note that in this implementation, if your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

=== Rain Tires ===

They are highly recommended if it is raining, but are otherwise very sensitive.

* If the weather is changeable or good, the penalties for overshooting a corner are doubled (loss of tire WP) for qualifying and the first two laps of the race. If a driver does not change their tires before the third race lap, the
penalties are trebled.
* If it is raining, the car travels one space further on any turn which contributes to advancing a corner.

== Technical Pit Stops ==

Your pit has 2 WP which can be used during the race to regain lost WP (with the exception of tire WP). Every time a driver makes a pit stop they can choose between two options:

* '''Tire pit stop''': As in the rules for advanced players, except that the driver may change the type of tire whenever they changes tires.
* '''Technlcal pit stop''': The driver can change their tires (see above) and in addition regain up to two WP in one or two zones (except the tires). This "reservoir" of 2 WP applies for the entire duration of the race, even if it lasts for more than two laps. In the next round, the car may not start higher than 4th gear. A car with soft tires does not profit from the bonus of an additional space when leaving the pits.

== Team Race ==

A game using these rules is appropriate for a large group with an even number of players. The players form teams each with two players; each colour corresponds to a racing team. Apart from the following two exceptions, the rules apply unchanged:

* '''Pit stop''': Each team has 4 WP to repair the cars. Both players must decide together how they want to use these points.
* '''Winner by points''': A team race is not necessarily won by the first car to cross the finishing line. Each car receives a certain number of winning points. The team with the highest number of total points wins the race.

{|
|'''Ranking''||'''No. of point'''
|-
|1||1000
|-
|2||720
|-
|3||600
|-
|4||480
|-
|5||400
|-
|6||320
|-
|7||240
|-
|8||160
|-
|9||80
|-
|10||40
|}

Note that these points differ from the published rules. If qualifying is enabled, qualifying points are also awarded equally to both members of the team.

== Nitro Fuel ==

When this option is chosen, all cars have a nitro Fuel injection, which allows instant acceleration. Players can use their nitro once a lap after rolling the corresponding gear die. They receive a movement bonus according to the gear they are using at that moment (1 space in 1st gear, 2 spaces in 2nd gear, etc.). This bonus must be used completely.

When a car pits, or crosses the finish line at the end of a lap, it replenishes its nitro fuel and may use it again.

Nitro may only be used if it is available when rolling the gear die. It does not become available during the same move where you complete a lap.

= BGA Rule Variations=

The BGA Adaptation of Formula D uses a number of variations from the Masters (Tournament) rules.

The differences from the rules you will find in your own copy of Formula D are:

==Round Order ==

In the original rules, if two cars are level with each other, the driver with the highest gear plays first. If both cars are in the same gear, the car nearest the inside with reference to the next (or the current) corner plays first.

In this adaptation, the higher gear continues to be first but if both cars are in the same gear *then the player who first arrived at their space* goes first. Corners no longer affect who goes first.

==Points ==

In this adaptation, points are awarded for race completion '''and''' for Qualifying (if enabled). The Qualifying points are minor by comparison and serve as a tie-break if two players are both eliminated and score 0 in the race.

{|
|'''Ranking'''||'''Race Points'''||'''Qualifying Points'''
|-
|1||1000||10
|-
|2||720||9
|-
|3||600||8
|-
|4||480||7
|-
|5||400||6
|-
|6||320||5
|-
|7||240||4
|-
|8||160||3
|-
|9||80||2
|-
|10||40||1
|}

To cover multiple players being eliminated during a game where there is not Qualifying, their distance travelled before being eliminated is used as the final tie-break (only in non-team games). If a player overshoots a corner or crashes into the back of other cars, their position at the '''start''' of the turn is used.

==Braking ==

The original rules provide a table that describes the outcome of "Emergency Braking" (when a car is blocked by one or more cars which they are unable to overtake). The table does not take Constructed Cars into account, so to clarify, the implemented rules are:

If a player performs Emergency Braking, they must move their car forward as many spaces as possible. If they need to brake more than 3 spaces, they are required to use Brake WPs for the first 3 spaces, and each subsequent space may be paid for using Brake WP *or* Tire WPs.

Braking is paid for *after* Overshooting, so any Tire WPs lost to Overshooting will not be available for Emergency Braking.

==Qualifying ==

Players do not roll the black starting die at the beginning of Qualifying: they just start in 1st gear.

The original rules simply state that "WP are not taken into account" during qualifying. However, the effect of this is clarified in this adaptation:

* You may not apply the brakes at all during Qualifying. If a roll forces you to overshoot a corner, it cannot be avoided.
* You may freely Gear down any number of gears during Qualifying, with no cost or penalty.

In this version, Qualifying awards points as long as you complete your lap:

{|
|'''Ranking''||'''No. of point'''
|-
|1||10
|-
|2||9
|-
|3||8
|-
|4||7
|-
|5||6
|-
|6||5
|-
|7||4
|-
|8||3
|-
|9||2
|-
|10||1
|}

==Collision Checks ==

In this adaptation, the active player checks for collisions only after all adjacent players have rolled. If an adjacent player fails their roll and is eliminated as a result, the active player will automatically fail their roll against that player.

==Weather Rolls ==

In the original rules, the Weather die is thrown immediately when a player rolls the maximum number in 5th or 6th gear. In this adaptation, this roll still occurs but it is deferred until the end of the round. This way, weather can only change between rounds and not in the middle of a player's turn. If multiple players roll the maximum number, the weather die will be rolled multiple times.

==Changeable Weather ==

The original rules have 4 steps for Changeable Weather (Good, Good - Changeable, Rain - Changeable, Rain).

In this adaptation, there are 5 steps: Good, Good - Temporary, Changeable, Rain - Temporary, Rain.

Changeable is only ever used at the start of a race, and by default is Good - with one exception: if it rained in qualifying then a changeable feature race will start Changeable but raining.

Weather will never be changeable in qualifying: it will be Good unless Rain is rolled.

==Spinning ==

The original rules state that if a car on 0 Tire WP overshoots a corner then it "will again spin round in a circle. If the car overshoots the corner by more than one space, it is out of the race". In this adaptation, a car with 0 Tire WP is eliminated if it overshoots a corner by more than 1 WP. Hence, even a single space overshoot will eliminate a 0 Tire WP car on soft tires.

Additionally, in this adaptation when you spin, your Tire WP are reset to 1 WP (instead of remaining at 0 WP).

==Skidding on Corners in the Rain ==

The original rules state that cars will skid in the rain "provided at least one space of the move lies within the limits of a corner". In this adaptation, skidding will only occur on any turn that counts towards a corner's completion. That means:

* Driving through a corner that you have already completed will ''not'' cause you to skid
* If you are on the final space in a corner and still need to land in it 1 more turn, you will skid on your next move even though you are driving into a straight

==Slipstreaming==

If your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

==Motor Damage Checks==

Motor damage checks are always performed in round order.

==Braking in the Pit Lane ==

The original rules state that the rules for braking do not apply in the pit lane. In this adaptation, there is no braking cost for stopping immediately behind another car, or in your pit box. However, there is a brake cost for travelling any distance shorter than that.

== Pit Boxes ==

In Individual Driver games, a single pit box will be reserved for each driver instead of drivers being assigned a pit box color. The box will be indicated with the player's avatar.

== Pit Lane ==

The rules for gearing down DO apply in the pit lane.

There are also minimum gears that may be used in the pit lane:

* Once a player has entered the pit lane, they must choose a gear which would allow their car to enter their pit box on a maximum roll. If they cannot use such a gear, they must use the highest gear permitted by their previous move.

* Exiting the pits: 1st gear is prohibited to drivers from their pit box to the outlet of the pit lane, except when 2nd gear might be unsafe

== Pit Stops ==

The soft tire bonus may not be used when moving after a Quick Pit Stop.

If Technical Pit Stops are enabled, players may always choose to take one (and thus finish their turn) even if they have no repair points or repairs to perform.

==Construction of one's own car ==

In this adaptation, if players have selected the option to Construct their own car then there are no limits to how many points they may assign to any given area.

In games that have also selected the Technical Pit Stop rules, then instead of having a fixed 2 WPs available for Pit repairs, a player will have 22 WPs to use in Construction and can choose how many repair points to make available, with a maximum of 2.

==Road Races ==

The Road Race rules, including Drivers with special abilities, are not used.

Where Road Race circuits are used, all non-standard rules are ignored.

Nitro Fuel Injection is available as an option for all races.

==Elimination ==

When a player is eliminated, the outcome is slightly different from the published rules.

*If the elimination was caused by the player overshooting corners, or driving over a damage marker, or quitting the car is immediately removed from the board and '''no damage marker is placed'''
*If the elimination was caused by the player failing a motor damage test, the car is immediately removed from the board and a damage marker is added.
*If the player is eliminated by any other reason, a damage marker is added and the car remains on the board until the end of the round, when it is removed.

Bugsclarification formulad

2026-01-15T04:39:20Z

BaronFraser:

== Corners ==

=== I Stopped In A Corner But It Did Not Count ===

Did you fully stop in all previous corners? All corner stops are required. If you miss a stop in one corner and end your turn in a second corner, that stop counts ONLY AGAINST THE FIRST CORNER. You still need to stop in the second corner and if you move out of it without stopping again, you will be overshooting.

=== I Exited A Corner And Crashed - Why? ===

Did you fully stop in all previous corners? If you skip Corner 1 and end your turn in Corner 2, that move only counts against Corner 1 and you STILL have to finish a turn in Corner 2. If you move out of Corner 2 at speed without stopping again in it, you will probably destroy your tires.

=== I Wasn't Able To Enter the Pits After Exiting A Corner ===

If you overshoot a corner, you are forced to travel in a straight line, so cars are unable to enter the pits on the same turn as overshooting a corner.

=== I Was Allowed To Change Lanes After Leaving A Corner ===

Some players have been confused by the line in the rules "When coming out a corner the car may not change lanes". Note that this line appears in the '''Overshooting''' section and is ''only'' intended to apply to cars that are overshooting a corner.

== Collisions ==

=== A Car Ended It's Move Next To Another Car But No Collision Was Rolled ===

Collisions are not rolled when a car ends its move IN FRONT of another car.

== Pit Stops ==

=== I Wasn't Able To Enter the Pits After Exiting A Corner ===

If you overshoot a corner, you are forced to travel in a straight line, so cars are unable to enter the pits on the same turn as overshooting a corner.

Bugsclarification formulad

2026-01-15T04:38:48Z

BaronFraser:

Bugsclarification formulad

2026-01-15T04:38:07Z

BaronFraser:

== Corners ==

=== I Stopped In A Corner But It Did Not Count ===

Did you fully stop in all previous corners? All corner stops are required. If you miss a stop in one corner and end your turn in a second corner, that stop counts ONLY AGAINST THE FIRST CORNER. You still need to stop in the second corner and if you move out of it without stopping again, you will be overshooting.

=== I Exited A Corner And Crashed - Why? ===

Did you fully stop in all previous corners? If you skip Corner 1 and end your turn in Corner 2, that move only counts against Corner 1 and you STILL have to finish a turn in Corner 2. If you move out of Corner 2 at speed without stopping again in it, you will probably destroy your tires.

=== I Wasn't Able To Enter the Pits After Exiting A Corner ===

If you overshoot a corner, you are forced to travel in a straight line, so cars are unable to enter the pits on the same turn as overshooting a corner.

=== I Was Allowed To Change Lanes After Leaving A Corner ===

Some players have been confused by the line in the rules "When coming out a corner the car may not change lanes". Note that this line appears in the '''Overshooting''' section and is ''only'' intended to apply to cars that are overshooting a corner.

=== A Car Ended It's Move Next To Another Car But No Collision Was Rolled ===

Collisions are not rolled when a car ends its move IN FRONT of another car.

Gamehelpformulad

2026-01-10T23:22:41Z

BaronFraser:

= 10-Second Explainer of Formula D =
New to Formula D?

This 10-second explainer will get you started:

# Your car will start in 1st gear.
# At the start of your turn, your first decision is whether to stay on your current gear, or go up 1 gear or go down. You can go down 1 gear without penalty.
# After choosing a gear, you will roll the appropriate "gear die". The higher the gear, the bigger the die.
# Once you have rolled, you must move the number of spaces rolled, although you may choose which path you take.
# Corners are areas marked in red. To drive around corners without penalty, you must finish at least 1 turn in them.
# Some corners are particularly slow and may require that you finish at least 2 or even 3 turns in them.

That's it! There's a lot more to it than that, but this covers the absolute basics of driving safely around the track.

= Important: BGA Rule Variations =

The BGA Adaptation of Formula D uses a number of variations from the Masters (Tournament) rules.

[[#BGA Rule Variations|At the end of these rules]], you will find a list of all differences from the published game rules.

=Adaptation Notes/Common Mistakes=

# The central area of your car is the colour of the pit box you must use (and your team if playing a team game)
# Your sidepods are your unique player color
# To enter the pitbox, you must move out of the pit lane and onto the coloured pit box. Stopping in the pit lane in front of your box is not a pit stop.
# To zoom the circuit in and out with a mouse, use Ctrl+Wheelmouse.

=Basic Rules=

== Aim of the game ==

FORMULA D is a car race. The aim is to win a race (of one lap) and be the first to cross the finishing line. There are all sorts of risks involved and you have to anticipate what will happen during the course of the race. You must decide on your strategy, trust to luck, keep to the rules and always keep an eye on the technical condition of your car.

== The gears ==

The cars have 6 gears. Each gear has its own die. The numbers on the dice tell you how many spaces to move the car. The higher the gear you choose, the faster and further the corresponding die will allow the car to travel. You are not allowed to skip gears when accelerating (e.g. changing straight from 1st to 3rd gear). You are allowed to skip 1, 2 or 3 gears when braking (e.g. from 6th to 4th or from 4th to 1st gear); however there is a penalty for doing this.

{|
!Gear!! Color||Die||Movement (Number of spaces)
!Face distribution
|-
|1||Yellow||d4||1-2
|1,1,2,2
|-
|2||Orange||d6||2-4
|2,3,3,4,4,4
|-
|3||Red||d8||4-8
|4,5,6,6,7,7,8,8
|-
|4||Green||d12||7-12
|2 of each
|-
|5||Purple||d20||11-20
|2 of each
|-
|6||Blue||d20||21-30
|2 of each
|}

==Driving ==

As in real life the car starts in 1st gear. Then you shift up to 2nd gear and so on up to 6th gear, in order to move as fast as possible. When it is a driver’s turn they announce which gear they have chosen, move the gear stick on their dashboard accordingly and then roll the die which corresponds to the chosen speed. They then move their car forward the number of spaces indicated on the die. When the move is finished the car “stops”. This notion is important especially in the corners.

'''Order of play''': In each round the drivers play according to their car position on the track.

Example: During a round of play car A overtakes car B which was in 1st position. When the next round starts, car A, now in 1st position, will play before car B.

Cars in the straight outside the pit lane will always move before cars in the pit lane. When two cars are level, the car in the highest gear goes first. When cars are level and in the same gear, the car that arrived in their current space first will go first.

==Driving Code ==

The cars drive in the track lanes. Different driving codes apply to corners and straights. It is generally not allowed to go over other cars – they must be driven round. Driving backwards is also not allowed.

===Driving code in the corners ===

To drive through a corner a car must stop a minimum number of times (indicated in the yellow box) within the limits of the corner. The number of filled red circles indicates the number of stops for that corner. After the requisite number of stops, the car may proceed and exit the corner on its next move.

To make it easier to drive through the corner, the driver should consider the indicated number of spaces. The number in the green box refer to the longest path, the numbers in the red box refer to the shortest path.

===Driving code on the straights ===

Straights are the portions of track between corners. Depending on the length of each straight, cars may need several rounds before entering the next corner.

'''Important''': The maneuver must be completed using the smallest number of spaces possible.

==Wear points (WP) ==

They reflect the capability of the car to stay on the track and survive events during the race. In the Basic Game, each car has 18 WP at the beginning of the race. The players use these points to survive various incidents and risky maneuvers.

==Preparation for play ==

===Start formation ===

Every player rolls the black die in order to determine the starting position of their car. Whoever rolls the highest number gains pole position. The other cars are positioned in decreasing order according to the numbers rolled. In the case of a tie, all involved players re-roll the die.

===Start ===

Before engaging 1st gear, every player rolls the black die to see how successfully they can start.

'''Number rolled: 1 – poor start'''. The player has stalled the motor of their car. They cannot engage 1st gear and so they have to wait till the next round. Then they can start in 1st gear without having to roll the black die again.

'''Number rolled: between 2 and 16''' – normal start. The player can start normally. They roll the die for 1st gear and moves their car forward according to the number rolled.

'''Number rolled: between 17 and 20''' – great start! The player makes a fantastic start. They moves their car forward 4 spaces immediately, although they is still in 1st gear. The car can change one or two lanes to avoid other cars. The driver may shift to 2nd gear in the next round.
==Overshooting==

If a car passes through a corner at the end of its turn without making the required number of stops, it overshoots the corner. The number of spaces the car overshot the corner by is deducted from the car’s WP as a penalty.

'''Corner with 2 stops''': If the car has made no stops, it is automatically removed from play.

'''Corner with 3 stops''': If the car has made no stops, or only one stop, it is automatically removed from play.

When coming out of a corner the car may not change lane, but must stay in the same lane. If the move ends in another corner, this stop does not count for the new corner. If the car is blocked by another car, they cannot drive round it and has to brake.

==Braking==

A player may use their WP at any time to avoid having to advance the full number of spaces shown on the die. In this way they can control their progress better, for example when the lanes are blocked by other cars.

==Changing down==

A driver can skip one, two or three gears when changing down, however this wears out their gearbox. The number of gears skipped equates to the number of WP their car loses as a result. Note: It is not possible to skip four gears (from 6th to 1st gear).

==Collision==

Whenever a car ends its move on a space next to or behind one or several cars, there is a risk of collision. A driver in this situation must roll the black die to see whether there is a collision or not. If they roll a number between 1 and 4 their car loses 1 WP.

==Motor damage==

If a player rolls a 20 in 5th gear or a 30 in 6th gear, this puts a strain on their engine. After their car has finished moving they must therefore roll the black die to test whether their engine has withstood the strain. All players who are driving in 5th or 6th gear at this moment must also roll the black die. If a number between 1 and 4 is rolled, the corresponding car loses 1 WP.

==Finish==

The player whose car passes the finishing line first has won the race. The race ends when all cars have crossed the finishing line, in order to enable ranking.

==Two-lap race==

For players who have already played several single-lap games.

Whoever crosses the finishing line first after two laps wins the game. Players may make a pit stop between the first and second laps to regain the WP points they lost during the first round.

==Pit stop==

At the end of the first lap a player may decide to make a pit stop to regain all the WP they have lost. There is no speed limit in the pit lanes. It is also not necessary to roll the exact number needed to reach one’s own pit.

In the BGA adaptation, your pit box matches the colour of your car's central strip.

===Entering pits===

To enter the pits it is sufficient to roll the minimum number required or higher using the die corresponding to the selected gear. The car receives all 18 WP back and awaits their next turn to start from the pits in 4th gear (maximum).

The rules for changing down gear, collision, braking and engine damage do not apply in the pit lane. Overtaking is not possible as it is a single lane. Drivers have to be patient and wait until the car ahead of them moves forward, regardless of selected gear and with no effect on the WP.

Cars in the pit lane must wait for their turn, until the cars on the circuit between pit exit and entry have had their turn.

There are minimum gears required in the pit lane:

* Once a player has entered the pit lane, they must choose a gear which would allow their car to enter their pit box on a maximum roll. If they cannot use such a gear, they must use the highest gear permitted by their previous move.

* Exiting the pits: 1st gear is prohibited to drivers from their pit box to the outlet of the pit lane, except when 2nd gear might be unsafe

=Advanced Rules=

==Basics==

===The gears===

The cars have 6 gears, each gear has its own die. The numbers on the dice tell you how many spaces to move the car. The higher the gear you choose, the faster and further the corresponding die will allow the car to travel. You are not allowed to skip gears when accelerating (e.g. changing straight from 1st to 3rd gear). You are allowed to skip 1, 2, or 3 gears when braking (e.g. from 6th to 4th or from 4th to 1st gear); however there is a penalty for doing this.

{|
!Gear!! Die Color||Die Size||Movement (Number of spaces)
|-
|1||Yellow||d4||1-2
|-
|2||Orange||d6||2-4
|-
|3||Red||d8||4-8
|-
|4||Green||d12||7-12
|-
|5||Purple||d20||11-20
|-
|6||Blue||d20||21-30
|}

===Driving===

As in real life, the car starts in 1st gear. Then you up shift to 2nd gear and so on up to 6th gear, in order to move as fast as possible. When it is a driver’s turn they announce which gear they have chosen, move the gear stick on their dashboard accordingly and then rolls the die which corresponds to the chosen speed. They then moves their car forward the number of spaces indicated on the die. When the move is finished the car “stops”. This notion is important especially in the corners.

====Order of play====

In each round the drivers play according to their car position on the track.

Example: During a round of play car A overtakes car B which was in 1st position. When the next round starts, car A, now in 1st position, will play before car B.

Cars in the straight outside the pit lane will always move before cars in the pit lane. When two cars are level, the car in the highest gear goes first. When cars are level and in the same gear, the car that arrived in their current space first will go first.

==== Same position====

If two cars on the track are level with each other, the driver with the highest gear plays first.

If both cars are in the same gear, the car that arrived first at their current space plays first.

===Driving Code===

The cars drive in the track lanes. Different driving codes apply to corners and straights. It is generally not allowed to go over other cars – they must be driven round. Driving backwards is also not allowed.

====Driving code in the corners====

To drive through a corner a car must stop a minimum number of times (indicated by the number of red stop lights in the corner information box) within the limits of the corner. After the requisite number of stops, the car may proceed and exit the corner on its next move.

To make it easier to drive through the corner, the driver should consider the indicated number of spaces. The number in the green box refer to the longest path, the numbers in the red box refer to the shortest path.

====Driving code on the straights====

Straights are the portions of track between corners. Depending on the length of each straight, cars may need several rounds before entering the next corner.

'''Important''': The maneuver must be completed using the smallest number of spaces possible.

=== Wear points (WP)===

Wear Points reflect the ability of the car to stay on the track and survive events during the race. Each car has a certain number of WP at the beginning of the race, which are divided up between six different categories. These points are distributed as follows in the game for advanced players:

{|
|WP tires:||6
|-
|WP brakes:||3
|-
|WP gearbox:||3
|-
|WP car body:||3
|-
|WP engine:||3
|-
|WP road handling:||2
|}

==Preparation for play==

===Start formation===

Every player rolls the black die in order to determine the starting position of their car. Whoever rolls the highest number gains pole position. The other cars are positioned in decreasing order according to the numbers rolled. (ln the case of a tie, all concerned players re-roll the die.)

===Start===

Before engaging 1st gear, every player rolls the black die to see how successfully they can start.

====Number rolled, 1 - poor start====

The player has stalled the motor of their car. They cannot engage 1st gear and so have to wait till the next round. Then they can start in 1st gear without having to roll the black die again.

====Number rolled: between 2 and 19 - normal start====

The player can start normally. They roll the die for 1st gear and moves their car forward according to the number rolled.

====Number rolled: 2O - great start!====

The player makes a fantastic start. They move their car forward 4 spaces immediately, although they is still in 1st gear. The car can change one or two lanes to avoid other cars. The driver may shift to 2nd gear in the next round.

==Overshooting==

If a car passes through a corner at the end of its turn without making the required number of stops, it overshoots the corner. The number of spaces the car overshot the corner by is deducted from the car’s tire WP as a penalty.

'''Corner with 2 stops''': If the car has made no stops, it is automatically removed from play.

'''Corner with 3 stops''': If the car has made no stops, or only one stop, it is automatically removed from play.

When coming out of a corner the car may not change lane, but must stay in the same lane. If the move ends in another corner, this stop does not count for the new corner. If the car is blocked by another car, they cannot drive round it and has to brake.

When a car loses their last tire WP by overshooting a corner, they spin round in a circle. The car is placed on the space where their move ended, pointing backwards. The player must turn their car round again and drive off in 1st gear when it is their next turn. In this adaptation, their Tire WPs are reset to 1.

If a car loses more tire WP than it possesses, it is eliminated from the race.

==Braking==

A player may use their brake WP at any time to avoid having to advance the full number of spaces shown on the die. This can help to prevent losing tire WP if they would otherwise overshoot a corner.

A driver can find themselves blocked by one or more cars which they are unable to overtake. After the driver has moved their car forward as many spaces as possible, they counts how many spaces they would have moved if they had not been blocked.

If the number of spaces short of the full number 4 or greater, they may use Emergency Braking. In this case, their first 3 spaces must be paid for with Brake WP. Each additional space after that may be paid by either Brake or Tire WP.

Braking is paid for *after* Overshooting, so any Tire WPs lost to Overshooting will not be available for Emergency Braking.

If a car doesn't have enough brake WP and tire WP to stop before a blockage, it is eliminated from the race.

==Gearing down==

A driver can skip one, two or three gears when changing down, however this wears out their gearbox.

As a result, the car then loses a certain number of brake WP, engine WP and gearbox WP. The table below lists the corresponding wear. Note: It is not possible to skip four gears (from 6th to 1st gear).

{|
!Gears skipped!!Gearbox WP!!Brake WP!!Engine WP
|-
|1 gear||1||0||0
|-
|2 gears||1||1||0
|-
|3 gears||1||1||1
|}

If a car has no gearbox WP left, the driver can only change clown one gear at a time until the game is over.

==Collision==

Whenever a car ends its move on a space next to or behind one or several cars, there is a risk of collision. A driver in this situation must roll the black die to see whether there is a collision or not. If they rolls a 1, their car loses 1 WP.

'''In this adaptation''' the car that did not just move rolls first. If it fails the roll and is eliminated from the race as a result, the car that moved will automatically fail its roll.

'''If a car loses its last car body WP, it is eliminated''' from the race.

==Motor damage==

If a player rolls a 20 in 5th gear or a 30 in 6th gear, this puts a strain on their engine. After their car has finished moving they must therefore roll the black die to test whether their engine has withstood the strain. All players who are driving in 5th or 6th gear at this moment must also roll the black die. If a number between 1 and 4 is rolled, the corresponding car loses 1 engine WP.

If a car loses its last engine WP, it is eliminated from the race.

==Damage and road handling==

Each time a car loses a car body WP or an engine WP, a damage marker is placed on the space where the move ended.

The same applies whenever a car is eliminated from the race for whatever reason. These spaces are judged to be "dangerous" from then on.

If a car passes over one of these spaces or lands on it, the driver must roll the black die. If the result is between 1 and 4, the car loses one road handling WP. The dangerous spaces can be avoided by changing lanes.

'''If a car loses its last road handling WP, it is eliminated from the race.'''

==Slipstreaming==

If a car drives in the wake of another car, this is called slipstreaming.

For the two concerned drivers, slipstreaming is possible from the 4th gear on.

The car must be driving as fast or faster than the car in front.

If a car wants to profit from slipstreaming after moving, it has to stop directly behind another car. From this position they can then add 3 spaces onto their last move. They can move forward 3 spaces in the following way:

*change a lane, overtake the car in front and return to the original lane.
*change a lane and move two spaces in a straight line.
*change two lanes and move one space in a straight line.

The player must move a total of three spaces in any case. (However, the driver may use brake WP in order to reduce this number of spaces.) If slipstreaming brings a car up immediately behind another car, they can carry on slipstreaming (and so on).

If a car is carried into a corner by slipstreaming, they lose a brake WP (without the number of spaces being reduced).

In a corner, a slipstreaming car must follow normal driving code (eg. following the arrows).

Braking in order to take advantage of slipstreaming in the wake of another player's car is not allowed.

Drivers do not have to slipstream!

Note that in this implementation, if your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

==Pit stop==

At the end of the first lap, a player may decide to make a pit stop to regain all the tire WP they have lost. There is no speed limit in the pit lanes. It is also not necessary to roll the exact number needed to reach one's own pit.

In the BGA adaptation, your pit box matches the central colour of your car.

To enter the pits it is necessary to roll the minimum number required or higher using the die corresponding to the selected gear. As soon as the car enters the pits, it receives all its tire WP back. The player now rolls the black die, in order to see how fast their mechanics work.

===Result between 1 and 10: quick pit stop===

The player divides the number shown on the black die by two (rounding it up if necessary). The result is the number of spaces the car is allowed to move when the car leaves the pit in 4th gear.

===Result between 11 and 20: slow pit stop===

The car remains in the pit until the next round. Then the car moves on in 4th gear (or a lower gear).

The rules for gearing down, collision, braking and engine damage do not apply in the pit lane. Overtaking is not possible as it is a single lane. Drivers have to be patient and wait until the car ahead of them moves forward, regardless of selected gear and with no effect on the WP.

Cars in the pit lane must wait for their turn, until the cars on the circuit between pit exit and entry have had their turn.

==Finish==

The player whose car passes the finishing line first has won the race. The race ends when all cars have crossed the finishing line, in order to enable ranking.

=Optional Rules=

All the following rules can be used of one another.

==Construction of one's own car==

Every player can distribute their 20 WP between the zones of their car at their own discretion. At least 1 WP must be assigned to each zone.

If using the Technical Pit Stops option, 2 addition WPs are available to assign, and players may assign 0-2 points to Repair points.

==Qualifying lap with a stopwatch==

All players drive a qualifying lap with stopwatch consecutively, in order to determine their start positions. The rules for moves and driving code remain unchanged during the qualifier, however the WP are not taken into account. The only exception is if a car overshoots a corner - this is penalized.

* The player whose turn it is to drive a qualifying lap places their car in the middle lane in front of the starting line.
* You may not apply the brakes at all during Qualifying. If a roll forces you to overshoot a corner, it cannot be avoided.
* You may freely Gear down any number of gears during Qualifying, with no cost or penalty.
* The player receives a total number of points over their lap:
**1 point for each round the player takes to complete the lap
**1 point for each space the player overshoots a corner by (soft tires will have their points doubled)
**1 point for every full real-time minute it takes the player to complete the lap

'''Note:''' The qualifying lap is over if the driver does not stop at all in corners where two or three stops are required. They then have to start the race at the back of the field from the last start position.

After that the order of starting is determined: the car which has completed the qualifying lap with the fewest points takes first position. The other cars follow on in decreasing order of points. If two drivers have the same number of points, the real time taken to complete the lap decides: the fastest player gets the better start position.

== Weather Conditions ==

There is a weather chart for each "Formula D" racing circuit, which is available to all players before the game so that they can inform themselves about weather conditions during the race and qualifying laps.

lf the weather rules are used, it is strongly recommended that the tire selection rules be used as well.

Before the qualifying laps begin, the black die is rolled and the weather chart consulted:

'''Good weather''' or '''Changable''': no problems for drivers
'''Rain''': The qualifying laps for all players take place in rain (see below).

Before the actual race begins, the black die is rolled again and the weather chart consulted:

'''Good weather''': no problem.
'''Changeable''': The sky is overcast at the beginning of the race, but is does not rain '''unless''' it rained during qualifying. Either way, this can change during the course of the race. Whenever a player in 5th gear throws a 20 or a 3O in 6th gear, at the end of the round they have to roll the black die and consult the weather chart:

If "good weather" comes up. the weather conditions are shifted one line upwards.
If "rain" is the result, the weather conditions are shifted one line downwards.
If the result is "changeable", the weather stays the same.

{|
|'''Weather'''||'''Effect on race'''
|-
|Good||None. The weather will no longer change.
|-
|Good (Temporary)||None.
|-
|Changable||This is the starting step and once the weather conditions shift up or down off Changeable, it will be skipped for the rest of the game.
|-
|Rain (Temporary)||Rain.
|-
|Rain||Rain. The weather will no longer change.
|}

=== Effect of rain ===

* '''Collision''': A result of 1 or 2 (instead of just a 1, as in good weather) means a collision occurs.
* '''Engine damage''': Occurs when result is between 1 and 3 (instead of between 1 and 4, as in good weather).
* '''Road handling''': The car loses one road handling WP for a result between 1 and 5 (instead of between 1 and 4, as in good weather)
* '''Skidding on corners''': Cars will skid on corners depending on their tire selection. See "Selection of tires", below.

== Selection of tires ==

The choice of tires is crucial not just for qualifying lap, but for the race itself. When weather conditions have been determined, each player can fit their car with special tires (see below). It is also possible to change tires between qualifying lap and the race.

=== Hard Tires ===

They are recommencled on a dry track and inefficient on a wet track.

* The game rules apply unchanged if the weather is good or changeable.
* If it is raining, the car moves three additional spaces on any turn which contributes to advancing a corner.

=== Soft Tires ===

They are recommended on a dry track and inefficient - if not handicapping - on a wet track.

* If the weather is changeable or good, the car can move one additional space during each move in the qualifying or race laps. This additional move is not compulsory. But if a car overshoots a corner, the penalty is doubled (loss of tire WP). if a driver does not change their tires during a pit stop after the first lap, they lose the bonus. If a driver does not change their tires during a pit stop after the second lap, the penalties for overshooting a corner are trebled.
* If it is raining, the car travels three spaces further on any turn which contributes to advancing a corner. If a driver cloes not change their tires during a pit stop before beginning the third lap, the penalties For overshooting a corner are trebled.

Note that in this implementation, if your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

=== Rain Tires ===

They are highly recommended if it is raining, but are otherwise very sensitive.

* If the weather is changeable or good, the penalties for overshooting a corner are doubled (loss of tire WP) for qualifying and the first two laps of the race. If a driver does not change their tires before the third race lap, the
penalties are trebled.
* If it is raining, the car travels one space further on any turn which contributes to advancing a corner.

== Technical Pit Stops ==

Your pit has 2 WP which can be used during the race to regain lost WP (with the exception of tire WP). Every time a driver makes a pit stop they can choose between two options:

* '''Tire pit stop''': As in the rules for advanced players, except that the driver may change the type of tire whenever they changes tires.
* '''Technlcal pit stop''': The driver can change their tires (see above) and in addition regain up to two WP in one or two zones (except the tires). This "reservoir" of 2 WP applies for the entire duration of the race, even if it lasts for more than two laps. In the next round, the car may not start higher than 4th gear. A car with soft tires does not profit from the bonus of an additional space when leaving the pits.

== Team Race ==

A game using these rules is appropriate for a large group with an even number of players. The players form teams each with two players; each colour corresponds to a racing team. Apart from the following two exceptions, the rules apply unchanged:

* '''Pit stop''': Each team has 4 WP to repair the cars. Both players must decide together how they want to use these points.
* '''Winner by points''': A team race is not necessarily won by the first car to cross the finishing line. Each car receives a certain number of winning points. The team with the highest number of total points wins the race.

{|
|'''Ranking''||'''No. of point'''
|-
|1||1000
|-
|2||720
|-
|3||600
|-
|4||480
|-
|5||400
|-
|6||320
|-
|7||240
|-
|8||160
|-
|9||80
|-
|10||40
|}

Note that these points differ from the published rules. If qualifying is enabled, qualifying points are also awarded equally to both members of the team.

== Nitro Fuel ==

When this option is chosen, all cars have a nitro Fuel injection, which allows instant acceleration. Players can use their nitro once a lap after rolling the corresponding gear die. They receive a movement bonus according to the gear they are using at that moment (1 space in 1st gear, 2 spaces in 2nd gear, etc.). This bonus must be used completely.

When a car pits, or crosses the finish line at the end of a lap, it replenishes its nitro fuel and may use it again.

Nitro may only be used if it is available when rolling the gear die. It does not become available during the same move where you complete a lap.

= BGA Rule Variations=

The BGA Adaptation of Formula D uses a number of variations from the Masters (Tournament) rules.

The differences from the rules you will find in your own copy of Formula D are:

==Round Order ==

In the original rules, if two cars are level with each other, the driver with the highest gear plays first. If both cars are in the same gear, the car nearest the inside with reference to the next (or the current) corner plays first.

In this adaptation, the higher gear continues to be first but if both cars are in the same gear *then the player who first arrived at their space* goes first. Corners no longer affect who goes first.

==Points ==

In this adaptation, points are awarded for race completion '''and''' for Qualifying (if enabled). The Qualifying points are minor by comparison and serve as a tie-break if two players are both eliminated and score 0 in the race.

{|
|'''Ranking'''||'''Race Points'''||'''Qualifying Points'''
|-
|1||1000||10
|-
|2||720||9
|-
|3||600||8
|-
|4||480||7
|-
|5||400||6
|-
|6||320||5
|-
|7||240||4
|-
|8||160||3
|-
|9||80||2
|-
|10||40||1
|}

To cover multiple players being eliminated during a game where there is not Qualifying, their distance travelled before being eliminated is used as the final tie-break (only in non-team games). If a player overshoots a corner or crashes into the back of other cars, their position at the '''start''' of the turn is used.

==Braking ==

The original rules provide a table that describes the outcome of "Emergency Braking" (when a car is blocked by one or more cars which they are unable to overtake). The table does not take Constructed Cars into account, so to clarify, the implemented rules are:

If a player performs Emergency Braking, they must move their car forward as many spaces as possible. If they need to brake more than 3 spaces, they are required to use Brake WPs for the first 3 spaces, and each subsequent space may be paid for using Brake WP *or* Tire WPs.

Braking is paid for *after* Overshooting, so any Tire WPs lost to Overshooting will not be available for Emergency Braking.

==Qualifying ==

Players do not roll the black starting die at the beginning of Qualifying: they just start in 1st gear.

The original rules simply state that "WP are not taken into account" during qualifying. However, the effect of this is clarified in this adaptation:

* You may not apply the brakes at all during Qualifying. If a roll forces you to overshoot a corner, it cannot be avoided.
* You may freely Gear down any number of gears during Qualifying, with no cost or penalty.

In this version, Qualifying awards points as long as you complete your lap:

{|
|'''Ranking''||'''No. of point'''
|-
|1||10
|-
|2||9
|-
|3||8
|-
|4||7
|-
|5||6
|-
|6||5
|-
|7||4
|-
|8||3
|-
|9||2
|-
|10||1
|}

==Collision Checks ==

In this adaptation, the active player checks for collisions only after all adjacent players have rolled. If an adjacent player fails their roll and is eliminated as a result, the active player will automatically fail their roll against that player.

==Weather Rolls ==

In the original rules, the Weather die is thrown immediately when a player rolls the maximum number in 5th or 6th gear. In this adaptation, this roll still occurs but it is deferred until the end of the round. This way, weather can only change between rounds and not in the middle of a player's turn. If multiple players roll the maximum number, the weather die will be rolled multiple times.

==Changeable Weather ==

The original rules have 4 steps for Changeable Weather (Good, Good - Changeable, Rain - Changeable, Rain).

In this adaptation, there are 5 steps: Good, Good - Temporary, Changeable, Rain - Temporary, Rain.

Changeable is only ever used at the start of a race, and by default is Good - with one exception: if it rained in qualifying then a changeable feature race will start Changeable but raining.

Weather will never be changeable in qualifying: it will be Good unless Rain is rolled.

==Spinning ==

The original rules state that if a car on 0 Tire WP overshoots a corner then it "will again spin round in a circle. If the car overshoots the corner by more than one space, it is out of the race". In this adaptation, a car with 0 Tire WP is eliminated if it overshoots a corner by more than 1 WP. Hence, even a single space overshoot will eliminate a 0 Tire WP car on soft tires.

Additionally, in this adaptation when you spin, your Tire WP are reset to 1 WP (instead of remaining at 0 WP).

==Skidding on Corners in the Rain ==

The original rules state that cars will skid in the rain "provided at least one space of the move lies within the limits of a corner". In this adaptation, skidding will only occur on any turn that counts towards a corner's completion. That means:

* Driving through a corner that you have already completed will ''not'' cause you to skid
* If you are on the final space in a corner and still need to land in it 1 more turn, you will skid on your next move even though you are driving into a straight

==Slipstreaming==

If your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

==Motor Damage Checks==

Motor damage checks are always performed in round order.

==Braking in the Pit Lane ==

The original rules state that the rules for braking do not apply in the pit lane. In this adaptation, there is no braking cost for stopping immediately behind another car, or in your pit box. However, there is a brake cost for travelling any distance shorter than that.

== Pit Boxes ==

In Individual Driver games, a single pit box will be reserved for each driver instead of drivers being assigned a pit box color. The box will be indicated with the player's avatar.

== Pit Lane ==

The rules for gearing down DO apply in the pit lane.

There are also minimum gears that may be used in the pit lane:

* Once a player has entered the pit lane, they must choose a gear which would allow their car to enter their pit box on a maximum roll. If they cannot use such a gear, they must use the highest gear permitted by their previous move.

* Exiting the pits: 1st gear is prohibited to drivers from their pit box to the outlet of the pit lane, except when 2nd gear might be unsafe

== Pit Stops ==

The soft tire bonus may not be used when moving after a Quick Pit Stop.

If Technical Pit Stops are enabled, players may always choose to take one (and thus finish their turn) even if they have no repair points or repairs to perform.

==Construction of one's own car ==

In this adaptation, if players have selected the option to Construct their own car then there are no limits to how many points they may assign to any given area.

In games that have also selected the Technical Pit Stop rules, then instead of having a fixed 2 WPs available for Pit repairs, a player will have 22 WPs to use in Construction and can choose how many repair points to make available, with a maximum of 2.

==Road Races ==

The Road Race rules, including Drivers with special abilities, are not used.

Where Road Race circuits are used, all non-standard rules are ignored.

Nitro Fuel Injection is available as an option for all races.

==Elimination ==

When a player is eliminated, the outcome is slightly different from the published rules.

*If the elimination was caused by the player overshooting corners, or driving over a damage marker, or quitting the car is immediately removed from the board and '''no damage marker is placed'''
*If the elimination was caused by the player failing a motor damage test, the car is immediately removed from the board and a damage marker is added.
*If the player is eliminated by any other reason, a damage marker is added and the car remains on the board until the end of the round, when it is removed.

Gamehelpformulad

2026-01-09T21:53:02Z

BaronFraser: /* Nitro Fuel */

= 10-Second Explainer of Formula D =
New to Formula D?

This 10-second explainer will get you started:

# Your car will start in 1st gear.
# At the start of your turn, your first decision is whether to stay on your current gear, or go up 1 gear or go down. You can go down 1 gear without penalty.
# After choosing a gear, you will roll the appropriate "gear die". The higher the gear, the bigger the die.
# Once you have rolled, you must move the number of spaces rolled, although you may choose which path you take.
# Corners are areas marked in red. To drive around corners without penalty, you must finish at least 1 turn in them.
# Some corners are particularly slow and may require that you finish at least 2 or even 3 turns in them.

That's it! There's a lot more to it than that, but this covers the absolute basics of driving safely around the track.

= Important: BGA Rule Variations =

The BGA Adaptation of Formula D uses a number of variations from the Masters (Tournament) rules.

[[#BGA Rule Variations|At the end of these rules]], you will find a list of all differences from the published game rules.

=Adaptation Notes/Common Mistakes=

# The central area of your car is the colour of the pit box you must use (and your team if playing a team game)
# Your sidepods are your unique player color
# To enter the pitbox, you must move out of the pit lane and onto the coloured pit box. Stopping in the pit lane in front of your box is not a pit stop.
# To zoom the circuit in and out with a mouse, use Ctrl+Wheelmouse.

=Basic Rules=

== Aim of the game ==

FORMULA D is a car race. The aim is to win a race (of one lap) and be the first to cross the finishing line. There are all sorts of risks involved and you have to anticipate what will happen during the course of the race. You must decide on your strategy, trust to luck, keep to the rules and always keep an eye on the technical condition of your car.

== The gears ==

The cars have 6 gears. Each gear has its own die. The numbers on the dice tell you how many spaces to move the car. The higher the gear you choose, the faster and further the corresponding die will allow the car to travel. You are not allowed to skip gears when accelerating (e.g. changing straight from 1st to 3rd gear). You are allowed to skip 1, 2 or 3 gears when braking (e.g. from 6th to 4th or from 4th to 1st gear); however there is a penalty for doing this.

{|
!Gear!! Color||Die||Movement (Number of spaces)
!Face distribution
|-
|1||Yellow||d4||1-2
|1,1,2,2
|-
|2||Orange||d6||2-4
|2,3,3,4,4,4
|-
|3||Red||d8||4-8
|4,5,6,6,7,7,8,8
|-
|4||Green||d12||7-12
|2 of each
|-
|5||Purple||d20||11-20
|2 of each
|-
|6||Blue||d20||21-30
|2 of each
|}

==Driving ==

As in real life the car starts in 1st gear. Then you shift up to 2nd gear and so on up to 6th gear, in order to move as fast as possible. When it is a driver’s turn they announce which gear they have chosen, move the gear stick on their dashboard accordingly and then roll the die which corresponds to the chosen speed. They then move their car forward the number of spaces indicated on the die. When the move is finished the car “stops”. This notion is important especially in the corners.

'''Order of play''': In each round the drivers play according to their car position on the track.

Example: During a round of play car A overtakes car B which was in 1st position. When the next round starts, car A, now in 1st position, will play before car B.

Cars in the straight outside the pit lane will always move before cars in the pit lane. When two cars are level, the car in the highest gear goes first. When cars are level and in the same gear, the car that arrived in their current space first will go first.

==Driving Code ==

The cars drive in the track lanes. Different driving codes apply to corners and straights. It is generally not allowed to go over other cars – they must be driven round. Driving backwards is also not allowed.

===Driving code in the corners ===

To drive through a corner a car must stop a minimum number of times (indicated in the yellow box) within the limits of the corner. The number of filled red circles indicates the number of stops for that corner. After the requisite number of stops, the car may proceed and exit the corner on its next move.

To make it easier to drive through the corner, the driver should consider the indicated number of spaces. The number in the green box refer to the longest path, the numbers in the red box refer to the shortest path.

===Driving code on the straights ===

Straights are the portions of track between corners. Depending on the length of each straight, cars may need several rounds before entering the next corner.

'''Important''': The maneuver must be completed using the smallest number of spaces possible.

==Wear points (WP) ==

They reflect the capability of the car to stay on the track and survive events during the race. In the Basic Game, each car has 18 WP at the beginning of the race. The players use these points to survive various incidents and risky maneuvers.

==Preparation for play ==

===Start formation ===

Every player rolls the black die in order to determine the starting position of their car. Whoever rolls the highest number gains pole position. The other cars are positioned in decreasing order according to the numbers rolled. In the case of a tie, all involved players re-roll the die.

===Start ===

Before engaging 1st gear, every player rolls the black die to see how successfully they can start.

'''Number rolled: 1 – poor start'''. The player has stalled the motor of their car. They cannot engage 1st gear and so they have to wait till the next round. Then they can start in 1st gear without having to roll the black die again.

'''Number rolled: between 2 and 16''' – normal start. The player can start normally. They roll the die for 1st gear and moves their car forward according to the number rolled.

'''Number rolled: between 17 and 20''' – great start! The player makes a fantastic start. They moves their car forward 4 spaces immediately, although they is still in 1st gear. The car can change one or two lanes to avoid other cars. The driver may shift to 2nd gear in the next round.
==Overshooting==

If a car passes through a corner at the end of its turn without making the required number of stops, it overshoots the corner. The number of spaces the car overshot the corner by is deducted from the car’s WP as a penalty.

'''Corner with 2 stops''': If the car has made no stops, it is automatically removed from play.

'''Corner with 3 stops''': If the car has made no stops, or only one stop, it is automatically removed from play.

When coming out of a corner the car may not change lane, but must stay in the same lane. If the move ends in another corner, this stop does not count for the new corner. If the car is blocked by another car, they cannot drive round it and has to brake.

==Braking==

A player may use their WP at any time to avoid having to advance the full number of spaces shown on the die. In this way they can control their progress better, for example when the lanes are blocked by other cars.

==Changing down==

A driver can skip one, two or three gears when changing down, however this wears out their gearbox. The number of gears skipped equates to the number of WP their car loses as a result. Note: It is not possible to skip four gears (from 6th to 1st gear).

==Collision==

Whenever a car ends its move on a space next to or behind one or several cars, there is a risk of collision. A driver in this situation must roll the black die to see whether there is a collision or not. If they roll a number between 1 and 4 their car loses 1 WP.

==Motor damage==

If a player rolls a 20 in 5th gear or a 30 in 6th gear, this puts a strain on their engine. After their car has finished moving they must therefore roll the black die to test whether their engine has withstood the strain. All players who are driving in 5th or 6th gear at this moment must also roll the black die. If a number between 1 and 4 is rolled, the corresponding car loses 1 WP.

==Finish==

The player whose car passes the finishing line first has won the race. The race ends when all cars have crossed the finishing line, in order to enable ranking.

==Two-lap race==

For players who have already played several single-lap games.

Whoever crosses the finishing line first after two laps wins the game. Players may make a pit stop between the first and second laps to regain the WP points they lost during the first round.

==Pit stop==

At the end of the first lap a player may decide to make a pit stop to regain all the WP they have lost. There is no speed limit in the pit lanes. It is also not necessary to roll the exact number needed to reach one’s own pit.

In the BGA adaptation, your pit box matches the colour of your car's central strip.

===Entering pits===

To enter the pits it is sufficient to roll the minimum number required or higher using the die corresponding to the selected gear. The car receives all 18 WP back and awaits their next turn to start from the pits in 4th gear (maximum).

The rules for changing down gear, collision, braking and engine damage do not apply in the pit lane. Overtaking is not possible as it is a single lane. Drivers have to be patient and wait until the car ahead of them moves forward, regardless of selected gear and with no effect on the WP.

Cars in the pit lane must wait for their turn, until the cars on the circuit between pit exit and entry have had their turn.

There are minimum gears required in the pit lane:

* Once a player has entered the pit lane, they must choose a gear which would allow their car to enter their pit box on a maximum roll. If they cannot use such a gear, they must use the highest gear permitted by their previous move.

* Exiting the pits: 1st gear is prohibited to drivers from their pit box to the outlet of the pit lane, except when 2nd gear might be unsafe

=Advanced Rules=

==Basics==

===The gears===

The cars have 6 gears, each gear has its own die. The numbers on the dice tell you how many spaces to move the car. The higher the gear you choose, the faster and further the corresponding die will allow the car to travel. You are not allowed to skip gears when accelerating (e.g. changing straight from 1st to 3rd gear). You are allowed to skip 1, 2, or 3 gears when braking (e.g. from 6th to 4th or from 4th to 1st gear); however there is a penalty for doing this.

{|
!Gear!! Die Color||Die Size||Movement (Number of spaces)
|-
|1||Yellow||d4||1-2
|-
|2||Orange||d6||2-4
|-
|3||Red||d8||4-8
|-
|4||Green||d12||7-12
|-
|5||Purple||d20||11-20
|-
|6||Blue||d20||21-30
|}

===Driving===

As in real life, the car starts in 1st gear. Then you up shift to 2nd gear and so on up to 6th gear, in order to move as fast as possible. When it is a driver’s turn they announce which gear they have chosen, move the gear stick on their dashboard accordingly and then rolls the die which corresponds to the chosen speed. They then moves their car forward the number of spaces indicated on the die. When the move is finished the car “stops”. This notion is important especially in the corners.

====Order of play====

In each round the drivers play according to their car position on the track.

Example: During a round of play car A overtakes car B which was in 1st position. When the next round starts, car A, now in 1st position, will play before car B.

Cars in the straight outside the pit lane will always move before cars in the pit lane. When two cars are level, the car in the highest gear goes first. When cars are level and in the same gear, the car that arrived in their current space first will go first.

==== Same position====

If two cars on the track are level with each other, the driver with the highest gear plays first.

If both cars are in the same gear, the car that arrived first at their current space plays first.

===Driving Code===

The cars drive in the track lanes. Different driving codes apply to corners and straights. It is generally not allowed to go over other cars – they must be driven round. Driving backwards is also not allowed.

====Driving code in the corners====

To drive through a corner a car must stop a minimum number of times (indicated by the number of red stop lights in the corner information box) within the limits of the corner. After the requisite number of stops, the car may proceed and exit the corner on its next move.

To make it easier to drive through the corner, the driver should consider the indicated number of spaces. The number in the green box refer to the longest path, the numbers in the red box refer to the shortest path.

====Driving code on the straights====

Straights are the portions of track between corners. Depending on the length of each straight, cars may need several rounds before entering the next corner.

'''Important''': The maneuver must be completed using the smallest number of spaces possible.

=== Wear points (WP)===

Wear Points reflect the ability of the car to stay on the track and survive events during the race. Each car has a certain number of WP at the beginning of the race, which are divided up between six different categories. These points are distributed as follows in the game for advanced players:

{|
|WP tires:||6
|-
|WP brakes:||3
|-
|WP gearbox:||3
|-
|WP car body:||3
|-
|WP engine:||3
|-
|WP road handling:||2
|}

==Preparation for play==

===Start formation===

Every player rolls the black die in order to determine the starting position of their car. Whoever rolls the highest number gains pole position. The other cars are positioned in decreasing order according to the numbers rolled. (ln the case of a tie, all concerned players re-roll the die.)

===Start===

Before engaging 1st gear, every player rolls the black die to see how successfully they can start.

====Number rolled, 1 - poor start====

The player has stalled the motor of their car. They cannot engage 1st gear and so have to wait till the next round. Then they can start in 1st gear without having to roll the black die again.

====Number rolled: between 2 and 19 - normal start====

The player can start normally. They roll the die for 1st gear and moves their car forward according to the number rolled.

====Number rolled: 2O - great start!====

The player makes a fantastic start. They move their car forward 4 spaces immediately, although they is still in 1st gear. The car can change one or two lanes to avoid other cars. The driver may shift to 2nd gear in the next round.

==Overshooting==

If a car passes through a corner at the end of its turn without making the required number of stops, it overshoots the corner. The number of spaces the car overshot the corner by is deducted from the car’s tire WP as a penalty.

'''Corner with 2 stops''': If the car has made no stops, it is automatically removed from play.

'''Corner with 3 stops''': If the car has made no stops, or only one stop, it is automatically removed from play.

When coming out of a corner the car may not change lane, but must stay in the same lane. If the move ends in another corner, this stop does not count for the new corner. If the car is blocked by another car, they cannot drive round it and has to brake.

When a car loses their last tire WP by overshooting a corner, they spin round in a circle. The car is placed on the space where their move ended, pointing backwards. The player must turn their car round again and drive off in 1st gear when it is their next turn. In this adaptation, their Tire WPs are reset to 1.

If a car loses more tire WP than it possesses, it is eliminated from the race.

==Braking==

A player may use their brake WP at any time to avoid having to advance the full number of spaces shown on the die. This can help to prevent losing tire WP if they would otherwise overshoot a corner.

A driver can find themselves blocked by one or more cars which they are unable to overtake. After the driver has moved their car forward as many spaces as possible, they counts how many spaces they would have moved if they had not been blocked.

If the number of spaces short of the full number 4 or greater, they may use Emergency Braking. In this case, their first 3 spaces must be paid for with Brake WP. Each additional space after that may be paid by either Brake or Tire WP.

Braking is paid for *after* Overshooting, so any Tire WPs lost to Overshooting will not be available for Emergency Braking.

If a car doesn't have enough brake WP and tire WP to stop before a blockage, it is eliminated from the race.

==Gearing down==

A driver can skip one, two or three gears when changing down, however this wears out their gearbox.

As a result, the car then loses a certain number of brake WP, engine WP and gearbox WP. The table below lists the corresponding wear. Note: It is not possible to skip four gears (from 6th to 1st gear).

{|
!Gears skipped!!Gearbox WP!!Brake WP!!Engine WP
|-
|1 gear||1||0||0
|-
|2 gears||1||1||0
|-
|3 gears||1||1||1
|}

If a car has no gearbox WP left, the driver can only change clown one gear at a time until the game is over.

==Collision==

Whenever a car ends its move on a space next to or behind one or several cars, there is a risk of collision. A driver in this situation must roll the black die to see whether there is a collision or not. If they rolls a 1, their car loses 1 WP.

'''In this adaptation''' the car that did not just move rolls first. If it fails the roll and is eliminated from the race as a result, the car that moved will automatically fail its roll.

'''If a car loses its last car body WP, it is eliminated''' from the race.

==Motor damage==

If a player rolls a 20 in 5th gear or a 30 in 6th gear, this puts a strain on their engine. After their car has finished moving they must therefore roll the black die to test whether their engine has withstood the strain. All players who are driving in 5th or 6th gear at this moment must also roll the black die. If a number between 1 and 4 is rolled, the corresponding car loses 1 engine WP.

If a car loses its last engine WP, it is eliminated from the race.

==Damage and road handling==

Each time a car loses a car body WP or an engine WP, a damage marker is placed on the space where the move ended.

The same applies whenever a car is eliminated from the race for whatever reason. These spaces are judged to be "dangerous" from then on.

If a car passes over one of these spaces or lands on it, the driver must roll the black die. If the result is between 1 and 4, the car loses one road handling WP. The dangerous spaces can be avoided by changing lanes.

'''If a car loses its last road handling WP, it is eliminated from the race.'''

==Slipstreaming==

If a car drives in the wake of another car, this is called slipstreaming.

For the two concerned drivers, slipstreaming is possible from the 4th gear on.

The car must be driving as fast or faster than the car in front.

If a car wants to profit from slipstreaming after moving, it has to stop directly behind another car. From this position they can then add 3 spaces onto their last move. They can move forward 3 spaces in the following way:

*change a lane, overtake the car in front and return to the original lane.
*change a lane and move two spaces in a straight line.
*change two lanes and move one space in a straight line.

The player must move a total of three spaces in any case. (However, the driver may use brake WP in order to reduce this number of spaces.) If slipstreaming brings a car up immediately behind another car, they can carry on slipstreaming (and so on).

If a car is carried into a corner by slipstreaming, they lose a brake WP (without the number of spaces being reduced).

In a corner, a slipstreaming car must follow normal driving code (eg. following the arrows).

Braking in order to take advantage of slipstreaming in the wake of another player's car is not allowed.

Drivers do not have to slipstream!

Note that in this implementation, if your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

==Pit stop==

At the end of the first lap, a player may decide to make a pit stop to regain all the tire WP they have lost. There is no speed limit in the pit lanes. It is also not necessary to roll the exact number needed to reach one's own pit.

In the BGA adaptation, your pit box matches the central colour of your car.

To enter the pits it is necessary to roll the minimum number required or higher using the die corresponding to the selected gear. As soon as the car enters the pits, it receives all its tire WP back. The player now rolls the black die, in order to see how fast their mechanics work.

===Result between 1 and 10: quick pit stop===

The player divides the number shown on the black die by two (rounding it up if necessary). The result is the number of spaces the car is allowed to move when the car leaves the pit in 4th gear.

===Result between 11 and 20: slow pit stop===

The car remains in the pit until the next round. Then the car moves on in 4th gear (or a lower gear).

The rules for gearing down, collision, braking and engine damage do not apply in the pit lane. Overtaking is not possible as it is a single lane. Drivers have to be patient and wait until the car ahead of them moves forward, regardless of selected gear and with no effect on the WP.

Cars in the pit lane must wait for their turn, until the cars on the circuit between pit exit and entry have had their turn.

==Finish==

The player whose car passes the finishing line first has won the race. The race ends when all cars have crossed the finishing line, in order to enable ranking.

=Optional Rules=

All the following rules can be used of one another.

==Construction of one's own car==

Every player can distribute their 20 WP between the zones of their car at their own discretion. At least 1 WP must be assigned to each zone.

If using the Technical Pit Stops option, 2 addition WPs are available to assign, and players may assign 0-2 points to Repair points.

==Qualifying lap with a stopwatch==

All players drive a qualifying lap with stopwatch consecutively, in order to determine their start positions. The rules for moves and driving code remain unchanged during the qualifier, however the WP are not taken into account. The only exception is if a car overshoots a corner - this is penalized.

* The player whose turn it is to drive a qualifying lap places their car in the middle lane in front of the starting line.
* You may not apply the brakes at all during Qualifying. If a roll forces you to overshoot a corner, it cannot be avoided.
* You may freely Gear down any number of gears during Qualifying, with no cost or penalty.
* The player receives a total number of points over their lap:
**1 point for each round the player takes to complete the lap
**1 point for each space the player overshoots a corner by (soft tires will have their points doubled)
**1 point for every full real-time minute it takes the player to complete the lap

'''Note:''' The qualifying lap is over if the driver does not stop at all in corners where two or three stops are required. They then have to start the race at the back of the field from the last start position.

After that the order of starting is determined: the car which has completed the qualifying lap with the fewest points takes first position. The other cars follow on in decreasing order of points. If two drivers have the same number of points, the real time taken to complete the lap decides: the fastest player gets the better start position.

== Weather Conditions ==

There is a weather chart for each "Formula D" racing circuit, which is available to all players before the game so that they can inform themselves about weather conditions during the race and qualifying laps.

lf the weather rules are used, it is strongly recommended that the tire selection rules be used as well.

Before the qualifying laps begin, the black die is rolled and the weather chart consulted:

'''Good weather''' or '''Changable''': no problems for drivers
'''Rain''': The qualifying laps for all players take place in rain (see below).

Before the actual race begins, the black die is rolled again and the weather chart consulted:

'''Good weather''': no problem.
'''Changeable''': The sky is overcast at the beginning of the race, but is does not rain '''unless''' it rained during qualifying. Either way, this can change during the course of the race. Whenever a player in 5th gear throws a 20 or a 3O in 6th gear, at the end of the round they have to roll the black die and consult the weather chart:

If "good weather" comes up. the weather conditions are shifted one line upwards.
If "rain" is the result, the weather conditions are shifted one line downwards.
If the result is "changeable", the weather stays the same.

{|
|'''Weather'''||'''Effect on race'''
|-
|Good||None. The weather will no longer change.
|-
|Good (Temporary)||None.
|-
|Changable||This is the starting step and once the weather conditions shift up or down off Changeable, it will be skipped for the rest of the game.
|-
|Rain (Temporary)||Rain.
|-
|Rain||Rain. The weather will no longer change.
|}

=== Effect of rain ===

* '''Collision''': A result of 1 or 2 (instead of just a 1, as in good weather) means a collision occurs.
* '''Engine damage''': Occurs when result is between 1 and 3 (instead of between 1 and 4, as in good weather).
* '''Road handling''': The car loses one road handling WP for a result between 1 and 5 (instead of between 1 and 4, as in good weather)
* '''Skidding on corners''': Cars will skid on corners depending on their tire selection. See "Selection of tires", below.

== Selection of tires ==

The choice of tires is crucial not just for qualifying lap, but for the race itself. When weather conditions have been determined, each player can fit their car with special tires (see below). It is also possible to change tires between qualifying lap and the race.

=== Hard Tires ===

They are recommencled on a dry track and inefficient on a wet track.

* The game rules apply unchanged if the weather is good or changeable.
* If it is raining, the car moves three additional spaces on any turn which contributes to advancing a corner.

=== Soft Tires ===

They are recommended on a dry track and inefficient - if not handicapping - on a wet track.

* If the weather is changeable or good, the car can move one additional space during each move in the qualifying or race laps. This additional move is not compulsory. But if a car overshoots a corner, the penalty is doubled (loss of tire WP). if a driver does not change their tires during a pit stop after the first lap, they lose the bonus. If a driver does not change their tires during a pit stop after the second lap, the penalties for overshooting a corner are trebled.
* If it is raining, the car travels three spaces further on any turn which contributes to advancing a corner. If a driver cloes not change their tires during a pit stop before beginning the third lap, the penalties For overshooting a corner are trebled.

Note that in this implementation, if your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

=== Rain Tires ===

They are highly recommended if it is raining, but are otherwise very sensitive.

* If the weather is changeable or good, the penalties for overshooting a corner are doubled (loss of tire WP) for qualifying and the first two laps of the race. If a driver does not change their tires before the third race lap, the
penalties are trebled.
* If it is raining, the car travels one space further on any turn which contributes to advancing a corner.

== Technical Pit Stops ==

Your pit has 2 WP which can be used during the race to regain lost WP (with the exception of tire WP). Every time a driver makes a pit stop they can choose between two options:

* '''Tire pit stop''': As in the rules for advanced players, except that the driver may change the type of tire whenever they changes tires.
* '''Technlcal pit stop''': The driver can change their tires (see above) and in addition regain up to two WP in one or two zones (except the tires). This "reservoir" of 2 WP applies for the entire duration of the race, even if it lasts for more than two laps. In the next round, the car may not start higher than 4th gear. A car with soft tires does not profit from the bonus of an additional space when leaving the pits.

== Team Race ==

A game using these rules is appropriate for a large group with an even number of players. The players form teams each with two players; each colour corresponds to a racing team. Apart from the following two exceptions, the rules apply unchanged:

* '''Pit stop''': Each team has 4 WP to repair the cars. Both players must decide together how they want to use these points.
* '''Winner by points''': A team race is not necessarily won by the first car to cross the finishing line. Each car receives a certain number of winning points. The team with the highest number of total points wins the race.

{|
|'''Ranking''||'''No. of point'''
|-
|1||1000
|-
|2||720
|-
|3||600
|-
|4||480
|-
|5||400
|-
|6||320
|-
|7||240
|-
|8||160
|-
|9||80
|-
|10||40
|}

Note that these points differ from the published rules. If qualifying is enabled, qualifying points are also awarded equally to both members of the team.

== Nitro Fuel ==

When this option is chosen, all cars have a nitro Fuel injection, which allows instant acceleration. Players can use their nitro once a lap after rolling the corresponding gear die. They receive a movement bonus according to the gear they are using at that moment (1 space in 1st gear, 2 spaces in 2nd gear, etc.). This bonus must be used completely.

When a car pits, or crosses the finish line at the end of a lap, it replenishes its nitro fuel and may use it again.

Nitro may only be used if it is available when rolling the gear die. It does not become available during the same move where you complete a lap.

= BGA Rule Variations=

The BGA Adaptation of Formula D uses a number of variations from the Masters (Tournament) rules.

The differences from the rules you will find in your own copy of Formula D are:

==Round Order ==

In the original rules, if two cars are level with each other, the driver with the highest gear plays first. If both cars are in the same gear, the car nearest the inside with reference to the next (or the current) corner plays first.

In this adaptation, the higher gear continues to be first but if both cars are in the same gear *then the player who first arrived at their space* goes first. Corners no longer affect who goes first.

==Points ==

In this adaptation, points are awarded for race completion '''and''' for Qualifying (if enabled). The Qualifying points are minor by comparison and serve as a tie-break if two players are both eliminated and score 0 in the race.

{|
|'''Ranking'''||'''Race Points'''||'''Qualifying Points'''
|-
|1||1000||10
|-
|2||720||9
|-
|3||600||8
|-
|4||480||7
|-
|5||400||6
|-
|6||320||5
|-
|7||240||4
|-
|8||160||3
|-
|9||80||2
|-
|10||40||1
|}

To cover multiple players being eliminated during a game where there is not Qualifying, their distance travelled before being eliminated is used as the final tie-break (only in non-team games). If a player overshoots a corner or crashes into the back of other cars, their position at the '''start''' of the turn is used.

==Braking ==

The original rules provide a table that describes the outcome of "Emergency Braking" (when a car is blocked by one or more cars which they are unable to overtake). The table does not take Constructed Cars into account, so to clarify, the implemented rules are:

If a player performs Emergency Braking, they must move their car forward as many spaces as possible. If they need to brake more than 3 spaces, they are required to use Brake WPs for the first 3 spaces, and each subsequent space may be paid for using Brake WP *or* Tire WPs.

Braking is paid for *after* Overshooting, so any Tire WPs lost to Overshooting will not be available for Emergency Braking.

==Qualifying ==

Players do not roll the black starting die at the beginning of Qualifying: they just start in 1st gear.

The original rules simply state that "WP are not taken into account" during qualifying. However, the effect of this is clarified in this adaptation:

* You may not apply the brakes at all during Qualifying. If a roll forces you to overshoot a corner, it cannot be avoided.
* You may freely Gear down any number of gears during Qualifying, with no cost or penalty.

In this version, Qualifying awards points as long as you complete your lap:

{|
|'''Ranking''||'''No. of point'''
|-
|1||10
|-
|2||9
|-
|3||8
|-
|4||7
|-
|5||6
|-
|6||5
|-
|7||4
|-
|8||3
|-
|9||2
|-
|10||1
|}

==Collision Checks ==

In this adaptation, the active player checks for collisions only after all adjacent players have rolled. If an adjacent player fails their roll and is eliminated as a result, the active player will automatically fail their roll against that player.

==Weather Rolls ==

In the original rules, the Weather die is thrown immediately when a player rolls the maximum number in 5th or 6th gear. In this adaptation, this roll still occurs but it is deferred until the end of the round. This way, weather can only change between rounds and not in the middle of a player's turn. If multiple players roll the maximum number, the weather die will be rolled multiple times.

==Changeable Weather ==

The original rules have 4 steps for Changeable Weather (Good, Good - Changeable, Rain - Changeable, Rain).

In this adaptation, there are 5 steps: Good, Good - Temporary, Changeable, Rain - Temporary, Rain.

Changeable is only ever used at the start of a race, and by default is Good - with one exception: if it rained in qualifying then a changeable feature race will start Changeable but raining.

Weather will never be changeable in qualifying: it will be Good unless Rain is rolled.

==Spinning ==

The original rules state that if a car on 0 Tire WP overshoots a corner then it "will again spin round in a circle. If the car overshoots the corner by more than one space, it is out of the race". In this adaptation, a car with 0 Tire WP is eliminated if it overshoots a corner by more than 1 WP. Hence, even a single space overshoot will eliminate a 0 Tire WP car on soft tires.

Additionally, in this adaptation when you spin, your Tire WP are reset to 1 WP (instead of remaining at 0 WP).

==Skidding on Corners in the Rain ==

The original rules state that cars will skid in the rain "provided at least one space of the move lies within the limits of a corner". In this adaptation, skidding will only occur on any turn that counts towards a corner's completion. That means:

* Driving through a corner that you have already completed will ''not'' cause you to skid
* If you are on the final space in a corner and still need to land in it 1 more turn, you will skid on your next move even though you are driving into a straight

==Slipstreaming==

If your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

==Motor Damage Checks==

Motor damage checks are always performed in round order.

==Braking in the Pit Lane ==

The original rules state that the rules for braking do not apply in the pit lane. In this adaptation, there is no braking cost for stopping immediately behind another car, or in your pit box. However, there is a brake cost for travelling any distance shorter than that.

== Pit Boxes ==

In Individual Driver games, a single pit box will be reserved for each driver instead of drivers being assigned a pit box color. The box will be indicated with the player's avatar.

== Pit Lane ==

The rules for gearing down DO apply in the pit lane.

There are also minimum gears that may be used in the pit lane:

* Once a player has entered the pit lane, they must choose a gear which would allow their car to enter their pit box on a maximum roll. If they cannot use such a gear, they must use the highest gear permitted by their previous move.

* Exiting the pits: 1st gear is prohibited to drivers from their pit box to the outlet of the pit lane, except when 2nd gear might be unsafe

== Pit Stops ==

The soft tire bonus may not be used when moving after a Quick Pit Stop.

If Technical Pit Stops are enabled, players may always choose to take one (and thus finish their turn) even if they have no repair points or repairs to perform.

==Construction of one's own car ==

In this adaptation, if players have selected the option to Construct their own car then there are no limits to how many points they may assign to any given area.

In games that have also selected the Technical Pit Stop rules, then instead of having a fixed 2 WPs available for Pit repairs, a player will have 22 WPs to use in Construction and can choose how many repair points to make available, with a maximum of 2.

==Road Races ==

The Road Race rules, including Drivers with special abilities, are not used.

Where Road Race circuits are used, all non-standard rules are ignored.

Nitro Fuel Injection is available as an option for all races.

==Elimination ==

When a player is eliminated, the outcome is slightly different from the published rules.

*If the elimination was caused by the player overshooting corners or driving over a damage marker, the car is immediately removed from the board and '''no damage marker is placed'''
*If the elimination was caused by the player failing a motor damage test, the car is immediately removed from the board and a damage marker is added.
*If the player is eliminated by any other reason, a damage marker is added and the car remains on the board until the end of the round, when it is removed.

Post-release phase

2026-01-09T01:05:08Z

BaronFraser: Added a "Documentation for Bug Reports" section as I can never remember how to do this (not sure it's documented except in Discord)

{{Studio_Framework_Navigation}}

Your game is now on BGA: congrats!

But what happened when there are some bugs to fix or when you want to optimize something?

Don't be afraid: you're still allowed to modify your game. You just have to pay attention to the points below.

== Bugs reporting ==

Bugs are reported on the [https://boardgamearena.com/bugs BGA bugs page].

During days after your game has been published and from time to time, please have a look at it to check if everything is fine.

== Documentation for Bug Reports ==
You can provide a wiki page for the attention of bug reporters.

To edit the page for your game, go to https://www.boardgamearena.com/bugs and click "Create a new report". Choose "About a game..." and then enter a table number where your game has been played, '''then tab away from the game number text box''' (important!).

You will be presented with an "Edit bug clarifications Wiki page" button, where you can edit the page.

When players who are not admins follow the same procedure, instead of being offered an "Edit bug clarifications Wiki page" button, they will be offered a "Make sure to read the game specific bug clarifications" link. To be fair, most of them won't follow it, but it may help reduce the number of reports you keep getting from players who don't understand the rules, and it does offer a page you can refer players back to when they do.

== How to submit changes? ==

There are steps to make your changes visible on BGA (from your game Control Panel, i.e. https://studio.boardgamearena.com/studiogame?game=mygamename):

* In Build a new release version section
** Enter some notes about the release (i.e. fixed bug xxx, added feature yyy)
** Press "Commit & build a new version now"
** Do not dismiss the build dialog right away, make sure it does not have Errors. If there are error build has failed.
* Deploy your new version in production
** Find your newly build version (should be latest, but check release note to make sure)
** Press "Deploy to production" button
** Do not dismiss the deploy dialog right away, make sure it does not have Errors. If there are error the deploy has failed.
* To check - the version of deployed game should be updated in "Online version" of control panel and also in section Credits page of the running game
* Go to Group page of your game and post update anouncement (usually using release notes from the deployment)

Note: if your game is very popular it will be pretty drammatic if it breaks, you can use two tricks to help your users
* [https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Disable_/_lock_table_creation_for_new_deploy Disable / lock table creation for new deploy]
* [https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Force_players_to_refresh_after_new_deploy Force players to refresh after new deploy]

== What can be modified after release? ==

Everything can be modified. BUT, some items requires a special attention, and you must inform us in some cases:

===Changes that breaks the games in progress===

Some changes will break the games in progress at the moment the release/the hotfix will be performed. Each time you make a change, you should ask you the question "it is safe to make this change in a game in progress", and if the answer is "no" you have to inform us.

Example of changes that break the games in progress:
* Changes in the database schema of the game (dbmodel.sql).
* New global variable or game option accessed during the game (if it's only used during setup, it should be safe).
* Change ID of existing game states (adding new game states is fine).
* Changing flow of game states (for example, if you change 1 -> 2 -> 3 -> 4 to 1 -> 3 -> 2 -> 4, players at state 2 will skip state 3)

Of course, as a rule of thumb, you should avoid to introduce changes that break a game in progress. Sometimes however, you do not have any other choice. In this case:
* Try to group all your updates in one version, thus we won't have to block your game several times.
* Tell us explicitly that you introduce some update that can break games in progress so we can block the game during a short time.

Note: in the near future, we will introduce the possibility for you to block/unblock a game directly from your Control Panel in order to perform all the process by yourself.

=== Updating game options ===

* If you add options, you should let us know which value should be used for the arena mode, so that we can update the arena configuration.
* If you remove an option or change a option ID, it will break the arena configuration and prevent creating new arena games, so you should let us know so that we can synchronize to update the configuration at the same time as you deploy the new version.
* Do not change option IDs once the game is in production, it will break ongoing games and audience option statistics.

=== Updating Statistics ===

You should be careful when updating a statistics:

* If you want to add a new statistic, please be aware that for ongoing games this statistic won't always be correct since it has not been counted from the start of that game.
* If you want to update a statistic, please update it and do not remove/create another one. Otherwise, the statistic won't keep the same ID and players will lose all the historical statistics data.
* If your game is published on BGA, please don't remove any statistics (historical data will be lost).

=== Updating the database schema ===

If you want to update the database schema of the game (dbmodel.sql) and your game is already open to everyone on BGA (from BETA onwards), you should inform us before releasing the new version (see "[[#Changes that breaks the games in progress|changes that breaks the games in progress]]").

Any modification in dbmodel.sql should also appear in your nameofyourgame.game.php, in a function

function upgradeTableDb( $from_version ){
<nowiki> </nowiki>
<nowiki> </nowiki>if( $from_version <= YYMMDDHHMM ){ // where your CURRENT version in production has number YYMMDD-HHMM
<nowiki> </nowiki>
<nowiki> </nowiki> // You DB schema update request.
<nowiki> </nowiki> // Note: all tables names should be prefixed by "DBPREFIX_" to be compatible with the applyDbUpgradeToAllDB method you should use below
<nowiki> </nowiki> $sql = "CREATE TABLE DBPREFIX_xxxxxxx ....";
<nowiki> </nowiki>
<nowiki> </nowiki> // The method below is applying your DB schema update request to all tables, including the BGA framework utility tables like "zz_replayXXXX" or "zz_savepointXXXX".
<nowiki> </nowiki> // You should really use this request, in conjunction with "DBPREFIX_" in your $sql, so ALL tables are updated. All utility tables MUST have the same schema than the main table, otherwise the game may be blocked.
<nowiki> </nowiki> self::applyDbUpgradeToAllDB( $sql );
<nowiki> </nowiki>}}

Note1: of course you need to change your dbmodel.sql accordingly, so that new games get your updated scheme.

Note2: this is always risky to modify the DB scheme, so:
* if your game is already open to everyone on BGA (from BETA onwards), it may be worth contacting us before, so we can stop the realtime games during the update (this way, only turn based games are concerned by the DB live upgrade).
* if you can avoid it... try to avoid it :)

Note3: testing on the studio is possible by following the following procedure:
* make sure the current state of your project is correctly committed
* revert to the revision currently in production using the version control tools ("Display commit log" -> find the revision matching the current version in production, then "Overwrite working copy with this revision" to get back the matching code)
* launch a game with this code
* revert to your code latest version using the version control tools (use "Overwrite working copy with this revision" with "head" for the revision)
* access the game database
* in the "global" table, find the row with id 300. Its value is 999999999 by default on the studio. Change it to the current production version number
* hit refresh to reload your game page. Your upgradeTableDb() function will be run and the global value will be updated again to the studio value
* check the database to see if your changes have been correctly applied.

Note4: consider that if your game has some undo support capability through 'db_undo_support' => true,' in the gameinfos.inc.php, calling the undoRestorePoint() could restore to a prior game version and the upgradeTableDb() could be called again. In that case, it's better to secure the SQL Alter Table Request with something like:
function upgradeTableDb( $from_version ){
if( $from_version <= YYMMDDHHMM )
{
// ! important ! Use DBPREFIX_<table_name> for all tables
// test first the new column existance since it can exists from a previous call to upgradeTableDb while an undo was performed
$result = self::getUniqueValueFromDB("SHOW COLUMNS FROM tablename LIKE 'new_column'");
if (empty($result))
self::applyDbUpgradeToAllDB("ALTER TABLE DBPREFIX_tablename ADD `new_column` tinyint(4) unsigned NOT NULL DEFAULT '0';");
}
}

=== Updating string to be translated ===

When you update a string that has been marked to be translatable, please keep in mind that all current translations done by the BGA community will be lost.

Consequently, when you are about to modify a string to be translated (after release), please ask you the following questions:
* Is it just an English misspelling? In this case, it is better to fix the English translation of the string than the original string to be translated.
* Has the meaning of the string changed? If yes, you HAVE to change the original string in order to invalidate all translations that has been done already.
* Is there a similar string already used elsewhere in my game? In this case, you'd better use it again to enjoy immediately all translations already available.

===Tell the community about your changes :)===

The player's community is always happy to know that someone is taking care of their preferred game :)

If your are the developer of game XXXX, you are also the administrator of player's group "XXXX's players", and you can publish some news in this group newsfeed.

When you fix a bug or add something, do not hesitate to tell the players about this in this group: you'll get the "thank you" you deserved :)

See for example Werewolves group:
https://boardgamearena.com/group?id=2465913
===Major changes===

If you do some major changes to your game like:
* Introducing a new expansion.
* Major code rewriting/refactoring.

... please tell us. In this case, we can:
* Make your game back from "gold" to "public beta", to incite player to report bugs.
* And eventually, publish a news about it :)

== Avoiding version mismatches ==
Be advised about the timing of deployments: Your new PHP backend code takes effect '''immediately''', but your new JS/HTML/CSS frontend code does not take effect unless current players reload the page (F5). This can lead to unexpected behavior and difficult-to-reproduce bugs caused by old JS client code interacting with new PHP server code.

Until the BGA framework handles this automatically for everyone (please upvote https://studio.boardgamearena.com/bug?id=106), your game should definitely implement something like [[BGA Studio Cookbook#Force players to refresh after new deploy]].
[[Category:Studio]]

Bugsclarification formulad

2026-01-09T00:57:48Z

BaronFraser:

Bugsclarification formulad

2025-12-21T02:13:41Z

BaronFraser:

== Corners ==

=== I Stopped In A Corner But It Did Not Count ===

Did you fully stop in all previous corners? All corner stops are required, so if you've missed one, your stop will have counted against a previous corner.

=== I Exited A Corner And Crashed - Why? ===

Did you fully stop in all previous corners? If you skip Corner 1 and end your turn in Corner 2, that move only counts against Corner 1 and you STILL have to finish a turn in Corner 2. If you move out of Corner 2 at speed without stopping again in it, you will probably destroy your tires.

=== I Was Allowed To Change Lanes After Leaving A Corner ===

Some players have been confused by the line in the rules "When coming out a corner the car may not change lanes". Note that this line appears in the '''Overshooting''' section and is ''only'' intended to apply to cars that are overshooting a corner.

Gamehelpformulad

2025-12-15T02:26:01Z

BaronFraser: /* Pit Lane */

= 10-Second Explainer of Formula D =
New to Formula D?

This 10-second explainer will get you started:

# Your car will start in 1st gear.
# At the start of your turn, your first decision is whether to stay on your current gear, or go up 1 gear or go down. You can go down 1 gear without penalty.
# After choosing a gear, you will roll the appropriate "gear die". The higher the gear, the bigger the die.
# Once you have rolled, you must move the number of spaces rolled, although you may choose which path you take.
# Corners are areas marked in red. To drive around corners without penalty, you must finish at least 1 turn in them.
# Some corners are particularly slow and may require that you finish at least 2 or even 3 turns in them.

That's it! There's a lot more to it than that, but this covers the absolute basics of driving safely around the track.

= Important: BGA Rule Variations =

The BGA Adaptation of Formula D uses a number of variations from the Masters (Tournament) rules.

[[Gamehelpformulad#BGA Rule Variations|At the end of these rules]], you will find a list of all differences from the published game rules.

=Adaptation Notes/Common Mistakes=

# The central area of your car is the colour of the pit box you must use (and your team if playing a team game)
# Your sidepods are your unique player color
# To enter the pitbox, you must move out of the pit lane and onto the coloured pit box. Stopping in the pit lane in front of your box is not a pit stop.
# To zoom the circuit in and out with a mouse, use Ctrl+Wheelmouse.

=Basic Rules=

== Aim of the game ==

FORMULA D is a car race. The aim is to win a race (of one lap) and be the first to cross the finishing line. There are all sorts of risks involved and you have to anticipate what will happen during the course of the race. You must decide on your strategy, trust to luck, keep to the rules and always keep an eye on the technical condition of your car.

== The gears ==

The cars have 6 gears. Each gear has its own die. The numbers on the dice tell you how many spaces to move the car. The higher the gear you choose, the faster and further the corresponding die will allow the car to travel. You are not allowed to skip gears when accelerating (e.g. changing straight from 1st to 3rd gear). You are allowed to skip 1, 2 or 3 gears when braking (e.g. from 6th to 4th or from 4th to 1st gear); however there is a penalty for doing this.

{|
!Gear!! Color||Die||Movement (Number of spaces)
!Face distribution
|-
|1||Yellow||d4||1-2
|1,1,2,2
|-
|2||Orange||d6||2-4
|2,3,3,4,4,4
|-
|3||Red||d8||4-8
|4,5,6,6,7,7,8,8
|-
|4||Green||d12||7-12
|2 of each
|-
|5||Purple||d20||11-20
|2 of each
|-
|6||Blue||d20||21-30
|2 of each
|}

==Driving ==

As in real life the car starts in 1st gear. Then you shift up to 2nd gear and so on up to 6th gear, in order to move as fast as possible. When it is a driver’s turn they announce which gear they have chosen, move the gear stick on their dashboard accordingly and then roll the die which corresponds to the chosen speed. They then move their car forward the number of spaces indicated on the die. When the move is finished the car “stops”. This notion is important especially in the corners.

'''Order of play''': In each round the drivers play according to their car position on the track.

Example: During a round of play car A overtakes car B which was in 1st position. When the next round starts, car A, now in 1st position, will play before car B.

Cars in the straight outside the pit lane will always move before cars in the pit lane. When two cars are level, the car in the highest gear goes first. When cars are level and in the same gear, the car that arrived in their current space first will go first.

==Driving Code ==

The cars drive in the track lanes. Different driving codes apply to corners and straights. It is generally not allowed to go over other cars – they must be driven round. Driving backwards is also not allowed.

===Driving code in the corners ===

To drive through a corner a car must stop a minimum number of times (indicated in the yellow box) within the limits of the corner. The number of filled red circles indicates the number of stops for that corner. After the requisite number of stops, the car may proceed and exit the corner on its next move.

To make it easier to drive through the corner, the driver should consider the indicated number of spaces. The number in the green box refer to the longest path, the numbers in the red box refer to the shortest path.

===Driving code on the straights ===

Straights are the portions of track between corners. Depending on the length of each straight, cars may need several rounds before entering the next corner.

'''Important''': The maneuver must be completed using the smallest number of spaces possible.

==Wear points (WP) ==

They reflect the capability of the car to stay on the track and survive events during the race. In the Basic Game, each car has 18 WP at the beginning of the race. The players use these points to survive various incidents and risky maneuvers.

==Preparation for play ==

===Start formation ===

Every player rolls the black die in order to determine the starting position of their car. Whoever rolls the highest number gains pole position. The other cars are positioned in decreasing order according to the numbers rolled. In the case of a tie, all involved players re-roll the die.

===Start ===

Before engaging 1st gear, every player rolls the black die to see how successfully they can start.

'''Number rolled: 1 – poor start'''. The player has stalled the motor of their car. They cannot engage 1st gear and so they have to wait till the next round. Then they can start in 1st gear without having to roll the black die again.

'''Number rolled: between 2 and 16''' – normal start. The player can start normally. They roll the die for 1st gear and moves their car forward according to the number rolled.

'''Number rolled: between 17 and 20''' – great start! The player makes a fantastic start. They moves their car forward 4 spaces immediately, although they is still in 1st gear. The car can change one or two lanes to avoid other cars. The driver may shift to 2nd gear in the next round.
==Overshooting==

If a car passes through a corner at the end of its turn without making the required number of stops, it overshoots the corner. The number of spaces the car overshot the corner by is deducted from the car’s WP as a penalty.

'''Corner with 2 stops''': If the car has made no stops, it is automatically removed from play.

'''Corner with 3 stops''': If the car has made no stops, or only one stop, it is automatically removed from play.

When coming out of a corner the car may not change lane, but must stay in the same lane. If the move ends in another corner, this stop does not count for the new corner. If the car is blocked by another car, they cannot drive round it and has to brake.

==Braking==

A player may use their WP at any time to avoid having to advance the full number of spaces shown on the die. In this way they can control their progress better, for example when the lanes are blocked by other cars.

==Changing down==

A driver can skip one, two or three gears when changing down, however this wears out their gearbox. The number of gears skipped equates to the number of WP their car loses as a result. Note: It is not possible to skip four gears (from 6th to 1st gear).

==Collision==

Whenever a car ends its move on a space next to or behind one or several cars, there is a risk of collision. A driver in this situation must roll the black die to see whether there is a collision or not. If they roll a number between 1 and 4 their car loses 1 WP.

==Motor damage==

If a player rolls a 20 in 5th gear or a 30 in 6th gear, this puts a strain on their engine. After their car has finished moving they must therefore roll the black die to test whether their engine has withstood the strain. All players who are driving in 5th or 6th gear at this moment must also roll the black die. If a number between 1 and 4 is rolled, the corresponding car loses 1 WP.

==Finish==

The player whose car passes the finishing line first has won the race. The race ends when all cars have crossed the finishing line, in order to enable ranking.

==Two-lap race==

For players who have already played several single-lap games.

Whoever crosses the finishing line first after two laps wins the game. Players may make a pit stop between the first and second laps to regain the WP points they lost during the first round.

==Pit stop==

At the end of the first lap a player may decide to make a pit stop to regain all the WP they have lost. There is no speed limit in the pit lanes. It is also not necessary to roll the exact number needed to reach one’s own pit.

In the BGA adaptation, your pit box matches the colour of your car's central strip.

===Entering pits===

To enter the pits it is sufficient to roll the minimum number required or higher using the die corresponding to the selected gear. The car receives all 18 WP back and awaits their next turn to start from the pits in 4th gear (maximum).

The rules for changing down gear, collision, braking and engine damage do not apply in the pit lane. Overtaking is not possible as it is a single lane. Drivers have to be patient and wait until the car ahead of them moves forward, regardless of selected gear and with no effect on the WP.

Cars in the pit lane must wait for their turn, until the cars on the circuit between pit exit and entry have had their turn.

There are minimum gears required in the pit lane:

* Once a player has entered the pit lane, they must choose a gear which would allow their car to enter their pit box on a maximum roll. If they cannot use such a gear, they must use the highest gear permitted by their previous move.

* Exiting the pits: 1st gear is prohibited to drivers from their pit box to the outlet of the pit lane, except when 2nd gear might be unsafe

=Advanced Rules=

==Basics==

===The gears===

The cars have 6 gears, each gear has its own die. The numbers on the dice tell you how many spaces to move the car. The higher the gear you choose, the faster and further the corresponding die will allow the car to travel. You are not allowed to skip gears when accelerating (e.g. changing straight from 1st to 3rd gear). You are allowed to skip 1, 2, or 3 gears when braking (e.g. from 6th to 4th or from 4th to 1st gear); however there is a penalty for doing this.

{|
!Gear!! Die Color||Die Size||Movement (Number of spaces)
|-
|1||Yellow||d4||1-2
|-
|2||Orange||d6||2-4
|-
|3||Red||d8||4-8
|-
|4||Green||d12||7-12
|-
|5||Purple||d20||11-20
|-
|6||Blue||d20||21-30
|}

===Driving===

As in real life, the car starts in 1st gear. Then you up shift to 2nd gear and so on up to 6th gear, in order to move as fast as possible. When it is a driver’s turn they announce which gear they have chosen, move the gear stick on their dashboard accordingly and then rolls the die which corresponds to the chosen speed. They then moves their car forward the number of spaces indicated on the die. When the move is finished the car “stops”. This notion is important especially in the corners.

====Order of play====

In each round the drivers play according to their car position on the track.

Example: During a round of play car A overtakes car B which was in 1st position. When the next round starts, car A, now in 1st position, will play before car B.

Cars in the straight outside the pit lane will always move before cars in the pit lane. When two cars are level, the car in the highest gear goes first. When cars are level and in the same gear, the car that arrived in their current space first will go first.

==== Same position====

If two cars on the track are level with each other, the driver with the highest gear plays first.

If both cars are in the same gear, the car that arrived first at their current space plays first.

===Driving Code===

The cars drive in the track lanes. Different driving codes apply to corners and straights. It is generally not allowed to go over other cars – they must be driven round. Driving backwards is also not allowed.

====Driving code in the corners====

To drive through a corner a car must stop a minimum number of times (indicated by the number of red stop lights in the corner information box) within the limits of the corner. After the requisite number of stops, the car may proceed and exit the corner on its next move.

To make it easier to drive through the corner, the driver should consider the indicated number of spaces. The number in the green box refer to the longest path, the numbers in the red box refer to the shortest path.

====Driving code on the straights====

Straights are the portions of track between corners. Depending on the length of each straight, cars may need several rounds before entering the next corner.

'''Important''': The maneuver must be completed using the smallest number of spaces possible.

=== Wear points (WP)===

Wear Points reflect the ability of the car to stay on the track and survive events during the race. Each car has a certain number of WP at the beginning of the race, which are divided up between six different categories. These points are distributed as follows in the game for advanced players:

{|
|WP tires:||6
|-
|WP brakes:||3
|-
|WP gearbox:||3
|-
|WP car body:||3
|-
|WP engine:||3
|-
|WP road handling:||2
|}

==Preparation for play==

===Start formation===

Every player rolls the black die in order to determine the starting position of their car. Whoever rolls the highest number gains pole position. The other cars are positioned in decreasing order according to the numbers rolled. (ln the case of a tie, all concerned players re-roll the die.)

===Start===

Before engaging 1st gear, every player rolls the black die to see how successfully they can start.

====Number rolled, 1 - poor start====

The player has stalled the motor of their car. They cannot engage 1st gear and so have to wait till the next round. Then they can start in 1st gear without having to roll the black die again.

====Number rolled: between 2 and 19 - normal start====

The player can start normally. They roll the die for 1st gear and moves their car forward according to the number rolled.

====Number rolled: 2O - great start!====

The player makes a fantastic start. They move their car forward 4 spaces immediately, although they is still in 1st gear. The car can change one or two lanes to avoid other cars. The driver may shift to 2nd gear in the next round.

==Overshooting==

If a car passes through a corner at the end of its turn without making the required number of stops, it overshoots the corner. The number of spaces the car overshot the corner by is deducted from the car’s tire WP as a penalty.

'''Corner with 2 stops''': If the car has made no stops, it is automatically removed from play.

'''Corner with 3 stops''': If the car has made no stops, or only one stop, it is automatically removed from play.

When coming out of a corner the car may not change lane, but must stay in the same lane. If the move ends in another corner, this stop does not count for the new corner. If the car is blocked by another car, they cannot drive round it and has to brake.

When a car loses their last tire WP by overshooting a corner, they spin round in a circle. The car is placed on the space where their move ended, pointing backwards. The player must turn their car round again and drive off in 1st gear when it is their next turn. In this adaptation, their Tire WPs are reset to 1.

If a car loses more tire WP than it possesses, it is eliminated from the race.

==Braking==

A player may use their brake WP at any time to avoid having to advance the full number of spaces shown on the die. This can help to prevent losing tire WP if they would otherwise overshoot a corner.

A driver can find themselves blocked by one or more cars which they are unable to overtake. After the driver has moved their car forward as many spaces as possible, they counts how many spaces they would have moved if they had not been blocked.

If the number of spaces short of the full number 4 or greater, they may use Emergency Braking. In this case, their first 3 spaces must be paid for with Brake WP. Each additional space after that may be paid by either Brake or Tire WP.

Braking is paid for *after* Overshooting, so any Tire WPs lost to Overshooting will not be available for Emergency Braking.

If a car doesn't have enough brake WP and tire WP to stop before a blockage, it is eliminated from the race.

==Gearing down==

A driver can skip one, two or three gears when changing down, however this wears out their gearbox.

As a result, the car then loses a certain number of brake WP, engine WP and gearbox WP. The table below lists the corresponding wear. Note: It is not possible to skip four gears (from 6th to 1st gear).

{|
!Gears skipped!!Gearbox WP!!Brake WP!!Engine WP
|-
|1 gear||1||0||0
|-
|2 gears||1||1||0
|-
|3 gears||1||1||1
|}

If a car has no gearbox WP left, the driver can only change clown one gear at a time until the game is over.

==Collision==

Whenever a car ends its move on a space next to or behind one or several cars, there is a risk of collision. A driver in this situation must roll the black die to see whether there is a collision or not. If they rolls a 1, their car loses 1 WP.

'''In this adaptation''' the car that did not just move rolls first. If it fails the roll and is eliminated from the race as a result, the car that moved will automatically fail its roll.

'''If a car loses its last car body WP, it is eliminated''' from the race.

==Motor damage==

If a player rolls a 20 in 5th gear or a 30 in 6th gear, this puts a strain on their engine. After their car has finished moving they must therefore roll the black die to test whether their engine has withstood the strain. All players who are driving in 5th or 6th gear at this moment must also roll the black die. If a number between 1 and 4 is rolled, the corresponding car loses 1 engine WP.

If a car loses its last engine WP, it is eliminated from the race.

==Damage and road handling==

Each time a car loses a car body WP or an engine WP, a damage marker is placed on the space where the move ended.

The same applies whenever a car is eliminated from the race for whatever reason. These spaces are judged to be "dangerous" from then on.

If a car passes over one of these spaces or lands on it, the driver must roll the black die. If the result is between 1 and 4, the car loses one road handling WP. The dangerous spaces can be avoided by changing lanes.

'''If a car loses its last road handling WP, it is eliminated from the race.'''

==Slipstreaming==

If a car drives in the wake of another car, this is called slipstreaming.

For the two concerned drivers, slipstreaming is possible from the 4th gear on.

The car must be driving as fast or faster than the car in front.

If a car wants to profit from slipstreaming after moving, it has to stop directly behind another car. From this position they can then add 3 spaces onto their last move. They can move forward 3 spaces in the following way:

*change a lane, overtake the car in front and return to the original lane.
*change a lane and move two spaces in a straight line.
*change two lanes and move one space in a straight line.

The player must move a total of three spaces in any case. (However, the driver may use brake WP in order to reduce this number of spaces.) If slipstreaming brings a car up immediately behind another car, they can carry on slipstreaming (and so on).

If a car is carried into a corner by slipstreaming, they lose a brake WP (without the number of spaces being reduced).

In a corner, a slipstreaming car must follow normal driving code (eg. following the arrows).

Braking in order to take advantage of slipstreaming in the wake of another player's car is not allowed.

Drivers do not have to slipstream!

Note that in this implementation, if your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

==Pit stop==

At the end of the first lap, a player may decide to make a pit stop to regain all the tire WP they have lost. There is no speed limit in the pit lanes. It is also not necessary to roll the exact number needed to reach one's own pit.

In the BGA adaptation, your pit box matches the central colour of your car.

To enter the pits it is necessary to roll the minimum number required or higher using the die corresponding to the selected gear. As soon as the car enters the pits, it receives all its tire WP back. The player now rolls the black die, in order to see how fast their mechanics work.

===Result between 1 and 10: quick pit stop===

The player divides the number shown on the black die by two (rounding it up if necessary). The result is the number of spaces the car is allowed to move when the car leaves the pit in 4th gear.

===Result between 11 and 20: slow pit stop===

The car remains in the pit until the next round. Then the car moves on in 4th gear (or a lower gear).

The rules for gearing down, collision, braking and engine damage do not apply in the pit lane. Overtaking is not possible as it is a single lane. Drivers have to be patient and wait until the car ahead of them moves forward, regardless of selected gear and with no effect on the WP.

Cars in the pit lane must wait for their turn, until the cars on the circuit between pit exit and entry have had their turn.

==Finish==

The player whose car passes the finishing line first has won the race. The race ends when all cars have crossed the finishing line, in order to enable ranking.

=Optional Rules=

All the following rules can be used of one another.

==Construction of one's own car==

Every player can distribute their 20 WP between the zones of their car at their own discretion. At least 1 WP must be assigned to each zone.

If using the Technical Pit Stops option, 2 addition WPs are available to assign, and players may assign 0-2 points to Repair points.

==Qualifying lap with a stopwatch==

All players drive a qualifying lap with stopwatch consecutively, in order to determine their start positions. The rules for moves and driving code remain unchanged during the qualifier, however the WP are not taken into account. The only exception is if a car overshoots a corner - this is penalized.

* The player whose turn it is to drive a qualifying lap places their car in the middle lane in front of the starting line.
* You may not apply the brakes at all during Qualifying. If a roll forces you to overshoot a corner, it cannot be avoided.
* You may freely Gear down any number of gears during Qualifying, with no cost or penalty.
* The player receives a total number of points over their lap:
**1 point for each round the player takes to complete the lap
**1 point for each space the player overshoots a corner by (soft tires will have their points doubled)
**1 point for every full real-time minute it takes the player to complete the lap

'''Note:''' The qualifying lap is over if the driver does not stop at all in corners where two or three stops are required. They then have to start the race at the back of the field from the last start position.

After that the order of starting is determined: the car which has completed the qualifying lap with the fewest points takes first position. The other cars follow on in decreasing order of points. If two drivers have the same number of points, the real time taken to complete the lap decides: the fastest player gets the better start position.

== Weather Conditions ==

There is a weather chart for each "Formula D" racing circuit, which is available to all players before the game so that they can inform themselves about weather conditions during the race and qualifying laps.

lf the weather rules are used, it is strongly recommended that the tire selection rules be used as well.

Before the qualifying laps begin, the black die is rolled and the weather chart consulted:

'''Good weather''' or '''Changable''': no problems for drivers
'''Rain''': The qualifying laps for all players take place in rain (see below).

Before the actual race begins, the black die is rolled again and the weather chart consulted:

'''Good weather''': no problem.
'''Changeable''': The sky is overcast at the beginning of the race, but is does not rain '''unless''' it rained during qualifying. Either way, this can change during the course of the race. Whenever a player in 5th gear throws a 20 or a 3O in 6th gear, at the end of the round they have to roll the black die and consult the weather chart:

If "good weather" comes up. the weather conditions are shifted one line upwards.
If "rain" is the result, the weather conditions are shifted one line downwards.
If the result is "changeable", the weather stays the same.

{|
|'''Weather'''||'''Effect on race'''
|-
|Good||None. The weather will no longer change.
|-
|Good (Temporary)||None.
|-
|Changable||This is the starting step and once the weather conditions shift up or down off Changeable, it will be skipped for the rest of the game.
|-
|Rain (Temporary)||Rain.
|-
|Rain||Rain. The weather will no longer change.
|}

=== Effect of rain ===

* '''Collision''': A result of 1 or 2 (instead of just a 1, as in good weather) means a collision occurs.
* '''Engine damage''': Occurs when result is between 1 and 3 (instead of between 1 and 4, as in good weather).
* '''Road handling''': The car loses one road handling WP for a result between 1 and 5 (instead of between 1 and 4, as in good weather)
* '''Skidding on corners''': Cars will skid on corners depending on their tire selection. See "Selection of tires", below.

== Selection of tires ==

The choice of tires is crucial not just for qualifying lap, but for the race itself. When weather conditions have been determined, each player can fit their car with special tires (see below). It is also possible to change tires between qualifying lap and the race.

=== Hard Tires ===

They are recommencled on a dry track and inefficient on a wet track.

* The game rules apply unchanged if the weather is good or changeable.
* If it is raining, the car moves three additional spaces on any turn which contributes to advancing a corner.

=== Soft Tires ===

They are recommended on a dry track and inefficient - if not handicapping - on a wet track.

* If the weather is changeable or good, the car can move one additional space during each move in the qualifying or race laps. This additional move is not compulsory. But if a car overshoots a corner, the penalty is doubled (loss of tire WP). if a driver does not change their tires during a pit stop after the first lap, they lose the bonus. If a driver does not change their tires during a pit stop after the second lap, the penalties for overshooting a corner are trebled.
* If it is raining, the car travels three spaces further on any turn which contributes to advancing a corner. If a driver cloes not change their tires during a pit stop before beginning the third lap, the penalties For overshooting a corner are trebled.

Note that in this implementation, if your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

=== Rain Tires ===

They are highly recommended if it is raining, but are otherwise very sensitive.

* If the weather is changeable or good, the penalties for overshooting a corner are doubled (loss of tire WP) for qualifying and the first two laps of the race. If a driver does not change their tires before the third race lap, the
penalties are trebled.
* If it is raining, the car travels one space further on any turn which contributes to advancing a corner.

== Technical Pit Stops ==

Your pit has 2 WP which can be used during the race to regain lost WP (with the exception of tire WP). Every time a driver makes a pit stop they can choose between two options:

* '''Tire pit stop''': As in the rules for advanced players, except that the driver may change the type of tire whenever they changes tires.
* '''Technlcal pit stop''': The driver can change their tires (see above) and in addition regain up to two WP in one or two zones (except the tires). This "reservoir" of 2 WP applies for the entire duration of the race, even if it lasts for more than two laps. In the next round, the car may not start higher than 4th gear. A car with soft tires does not profit from the bonus of an additional space when leaving the pits.

== Team Race ==

A game using these rules is appropriate for a large group with an even number of players. The players form teams each with two players; each colour corresponds to a racing team. Apart from the following two exceptions, the rules apply unchanged:

* '''Pit stop''': Each team has 4 WP to repair the cars. Both players must decide together how they want to use these points.
* '''Winner by points''': A team race is not necessarily won by the first car to cross the finishing line. Each car receives a certain number of winning points. The team with the highest number of total points wins the race.

{|
|'''Ranking''||'''No. of point'''
|-
|1||1000
|-
|2||720
|-
|3||600
|-
|4||480
|-
|5||400
|-
|6||320
|-
|7||240
|-
|8||160
|-
|9||80
|-
|10||40
|}

Note that these points differ from the published rules. If qualifying is enabled, qualifying points are also awarded equally to both members of the team.

== Nitro Fuel ==

When this option is chosen, all cars have a nitro Fuel injection, which allows instant acceleration. Players can use their nitro once a lap after rolling the corresponding gear die. They receive a movement bonus according to the gear they are using at that moment (1 space in 1st gear, 2 spaces in 2nd gear, etc.). This bonus must be used completely.

When a car completes a lap, it replenishes its nitro fuel and may use it again.

Nitro may only be used if it is available when rolling the gear die. It does not become available during the same move where you complete a lap.

= BGA Rule Variations=

The BGA Adaptation of Formula D uses a number of variations from the Masters (Tournament) rules.

The differences from the rules you will find in your own copy of Formula D are:

==Round Order ==

In the original rules, if two cars are level with each other, the driver with the highest gear plays first. If both cars are in the same gear, the car nearest the inside with reference to the next (or the current) corner plays first.

In this adaptation, the higher gear continues to be first but if both cars are in the same gear *then the player who first arrived at their space* goes first. Corners no longer affect who goes first.

==Points ==

In this adaptation, points are awarded for race completion '''and''' for Qualifying (if enabled). The Qualifying points are minor by comparison and serve as a tie-break if two players are both eliminated and score 0 in the race.

{|
|'''Ranking'''||'''Race Points'''||'''Qualifying Points'''
|-
|1||1000||10
|-
|2||720||9
|-
|3||600||8
|-
|4||480||7
|-
|5||400||6
|-
|6||320||5
|-
|7||240||4
|-
|8||160||3
|-
|9||80||2
|-
|10||40||1
|}

To cover multiple players being eliminated during a game where there is not Qualifying, their distance travelled before being eliminated is used as the final tie-break (only in non-team games). If a player overshoots a corner or crashes into the back of other cars, their position at the '''start''' of the turn is used.

==Braking ==

The original rules provide a table that describes the outcome of "Emergency Braking" (when a car is blocked by one or more cars which they are unable to overtake). The table does not take Constructed Cars into account, so to clarify, the implemented rules are:

If a player performs Emergency Braking, they must move their car forward as many spaces as possible. If they need to brake more than 3 spaces, they are required to use Brake WPs for the first 3 spaces, and each subsequent space may be paid for using Brake WP *or* Tire WPs.

Braking is paid for *after* Overshooting, so any Tire WPs lost to Overshooting will not be available for Emergency Braking.

==Qualifying ==

Players do not roll the black starting die at the beginning of Qualifying: they just start in 1st gear.

The original rules simply state that "WP are not taken into account" during qualifying. However, the effect of this is clarified in this adaptation:

* You may not apply the brakes at all during Qualifying. If a roll forces you to overshoot a corner, it cannot be avoided.
* You may freely Gear down any number of gears during Qualifying, with no cost or penalty.

In this version, Qualifying awards points as long as you complete your lap:

{|
|'''Ranking''||'''No. of point'''
|-
|1||10
|-
|2||9
|-
|3||8
|-
|4||7
|-
|5||6
|-
|6||5
|-
|7||4
|-
|8||3
|-
|9||2
|-
|10||1
|}

==Collision Checks ==

In this adaptation, the active player checks for collisions only after all adjacent players have rolled. If an adjacent player fails their roll and is eliminated as a result, the active player will automatically fail their roll against that player.

==Weather Rolls ==

In the original rules, the Weather die is thrown immediately when a player rolls the maximum number in 5th or 6th gear. In this adaptation, this roll still occurs but it is deferred until the end of the round. This way, weather can only change between rounds and not in the middle of a player's turn. If multiple players roll the maximum number, the weather die will be rolled multiple times.

==Changeable Weather ==

The original rules have 4 steps for Changeable Weather (Good, Good - Changeable, Rain - Changeable, Rain).

In this adaptation, there are 5 steps: Good, Good - Temporary, Changeable, Rain - Temporary, Rain.

Changeable is only ever used at the start of a race, and by default is Good - with one exception: if it rained in qualifying then a changeable feature race will start Changeable but raining.

Weather will never be changeable in qualifying: it will be Good unless Rain is rolled.

==Spinning ==

The original rules state that if a car on 0 Tire WP overshoots a corner then it "will again spin round in a circle. If the car overshoots the corner by more than one space, it is out of the race". In this adaptation, a car with 0 Tire WP is eliminated if it overshoots a corner by more than 1 WP. Hence, even a single space overshoot will eliminate a 0 Tire WP car on soft tires.

Additionally, in this adaptation when you spin, your Tire WP are reset to 1 WP (instead of remaining at 0 WP).

==Skidding on Corners in the Rain ==

The original rules state that cars will skid in the rain "provided at least one space of the move lies within the limits of a corner". In this adaptation, skidding will only occur on any turn that counts towards a corner's completion. That means:

* Driving through a corner that you have already completed will ''not'' cause you to skid
* If you are on the final space in a corner and still need to land in it 1 more turn, you will skid on your next move even though you are driving into a straight

==Slipstreaming==

If your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

==Motor Damage Checks==

Motor damage checks are always performed in round order.

==Braking in the Pit Lane ==

The original rules state that the rules for braking do not apply in the pit lane. In this adaptation, there is no braking cost for stopping immediately behind another car, or in your pit box. However, there is a brake cost for travelling any distance shorter than that.

== Pit Boxes ==

In Individual Driver games, a single pit box will be reserved for each driver instead of drivers being assigned a pit box color. The box will be indicated with the player's avatar.

== Pit Lane ==

The rules for gearing down DO apply in the pit lane.

There are also minimum gears that may be used in the pit lane:

* Once a player has entered the pit lane, they must choose a gear which would allow their car to enter their pit box on a maximum roll. If they cannot use such a gear, they must use the highest gear permitted by their previous move.

* Exiting the pits: 1st gear is prohibited to drivers from their pit box to the outlet of the pit lane, except when 2nd gear might be unsafe

== Pit Stops ==

The soft tire bonus may not be used when moving after a Quick Pit Stop.

If Technical Pit Stops are enabled, players may always choose to take one (and thus finish their turn) even if they have no repair points or repairs to perform.

==Construction of one's own car ==

In this adaptation, if players have selected the option to Construct their own car then there are no limits to how many points they may assign to any given area.

In games that have also selected the Technical Pit Stop rules, then instead of having a fixed 2 WPs available for Pit repairs, a player will have 22 WPs to use in Construction and can choose how many repair points to make available, with a maximum of 2.

==Road Races ==

The Road Race rules, including Drivers with special abilities, are not used.

Where Road Race circuits are used, all non-standard rules are ignored.

Nitro Fuel Injection is available as an option for all races.

==Elimination ==

When a player is eliminated, the outcome is slightly different from the published rules.

*If the elimination was caused by the player overshooting corners or driving over a damage marker, the car is immediately removed from the board and '''no damage marker is placed'''
*If the elimination was caused by the player failing a motor damage test, the car is immediately removed from the board and a damage marker is added.
*If the player is eliminated by any other reason, a damage marker is added and the car remains on the board until the end of the round, when it is removed.

Gamehelpformulad

2025-12-14T00:52:20Z

BaronFraser: /* BGA Rule Variations */

= 10-Second Explainer of Formula D =
New to Formula D?

This 10-second explainer will get you started:

# Your car will start in 1st gear.
# At the start of your turn, your first decision is whether to stay on your current gear, or go up 1 gear or go down. You can go down 1 gear without penalty.
# After choosing a gear, you will roll the appropriate "gear die". The higher the gear, the bigger the die.
# Once you have rolled, you must move the number of spaces rolled, although you may choose which path you take.
# Corners are areas marked in red. To drive around corners without penalty, you must finish at least 1 turn in them.
# Some corners are particularly slow and may require that you finish at least 2 or even 3 turns in them.

That's it! There's a lot more to it than that, but this covers the absolute basics of driving safely around the track.

= Important: BGA Rule Variations =

The BGA Adaptation of Formula D uses a number of variations from the Masters (Tournament) rules.

[[Gamehelpformulad#BGA Rule Variations|At the end of these rules]], you will find a list of all differences from the published game rules.

=Adaptation Notes/Common Mistakes=

# The central area of your car is the colour of the pit box you must use (and your team if playing a team game)
# Your sidepods are your unique player color
# To enter the pitbox, you must move out of the pit lane and onto the coloured pit box. Stopping in the pit lane in front of your box is not a pit stop.
# To zoom the circuit in and out with a mouse, use Ctrl+Wheelmouse.

=Basic Rules=

== Aim of the game ==

FORMULA D is a car race. The aim is to win a race (of one lap) and be the first to cross the finishing line. There are all sorts of risks involved and you have to anticipate what will happen during the course of the race. You must decide on your strategy, trust to luck, keep to the rules and always keep an eye on the technical condition of your car.

== The gears ==

The cars have 6 gears. Each gear has its own die. The numbers on the dice tell you how many spaces to move the car. The higher the gear you choose, the faster and further the corresponding die will allow the car to travel. You are not allowed to skip gears when accelerating (e.g. changing straight from 1st to 3rd gear). You are allowed to skip 1, 2 or 3 gears when braking (e.g. from 6th to 4th or from 4th to 1st gear); however there is a penalty for doing this.

{|
!Gear!! Color||Die||Movement (Number of spaces)
!Face distribution
|-
|1||Yellow||d4||1-2
|1,1,2,2
|-
|2||Orange||d6||2-4
|2,3,3,4,4,4
|-
|3||Red||d8||4-8
|4,5,6,6,7,7,8,8
|-
|4||Green||d12||7-12
|2 of each
|-
|5||Purple||d20||11-20
|2 of each
|-
|6||Blue||d20||21-30
|2 of each
|}

==Driving ==

As in real life the car starts in 1st gear. Then you shift up to 2nd gear and so on up to 6th gear, in order to move as fast as possible. When it is a driver’s turn they announce which gear they have chosen, move the gear stick on their dashboard accordingly and then roll the die which corresponds to the chosen speed. They then move their car forward the number of spaces indicated on the die. When the move is finished the car “stops”. This notion is important especially in the corners.

'''Order of play''': In each round the drivers play according to their car position on the track.

Example: During a round of play car A overtakes car B which was in 1st position. When the next round starts, car A, now in 1st position, will play before car B.

Cars in the straight outside the pit lane will always move before cars in the pit lane. When two cars are level, the car in the highest gear goes first. When cars are level and in the same gear, the car that arrived in their current space first will go first.

==Driving Code ==

The cars drive in the track lanes. Different driving codes apply to corners and straights. It is generally not allowed to go over other cars – they must be driven round. Driving backwards is also not allowed.

===Driving code in the corners ===

To drive through a corner a car must stop a minimum number of times (indicated in the yellow box) within the limits of the corner. The number of filled red circles indicates the number of stops for that corner. After the requisite number of stops, the car may proceed and exit the corner on its next move.

To make it easier to drive through the corner, the driver should consider the indicated number of spaces. The number in the green box refer to the longest path, the numbers in the red box refer to the shortest path.

===Driving code on the straights ===

Straights are the portions of track between corners. Depending on the length of each straight, cars may need several rounds before entering the next corner.

'''Important''': The maneuver must be completed using the smallest number of spaces possible.

==Wear points (WP) ==

They reflect the capability of the car to stay on the track and survive events during the race. In the Basic Game, each car has 18 WP at the beginning of the race. The players use these points to survive various incidents and risky maneuvers.

==Preparation for play ==

===Start formation ===

Every player rolls the black die in order to determine the starting position of their car. Whoever rolls the highest number gains pole position. The other cars are positioned in decreasing order according to the numbers rolled. In the case of a tie, all involved players re-roll the die.

===Start ===

Before engaging 1st gear, every player rolls the black die to see how successfully they can start.

'''Number rolled: 1 – poor start'''. The player has stalled the motor of their car. They cannot engage 1st gear and so they have to wait till the next round. Then they can start in 1st gear without having to roll the black die again.

'''Number rolled: between 2 and 16''' – normal start. The player can start normally. They roll the die for 1st gear and moves their car forward according to the number rolled.

'''Number rolled: between 17 and 20''' – great start! The player makes a fantastic start. They moves their car forward 4 spaces immediately, although they is still in 1st gear. The car can change one or two lanes to avoid other cars. The driver may shift to 2nd gear in the next round.
==Overshooting==

If a car passes through a corner at the end of its turn without making the required number of stops, it overshoots the corner. The number of spaces the car overshot the corner by is deducted from the car’s WP as a penalty.

'''Corner with 2 stops''': If the car has made no stops, it is automatically removed from play.

'''Corner with 3 stops''': If the car has made no stops, or only one stop, it is automatically removed from play.

When coming out of a corner the car may not change lane, but must stay in the same lane. If the move ends in another corner, this stop does not count for the new corner. If the car is blocked by another car, they cannot drive round it and has to brake.

==Braking==

A player may use their WP at any time to avoid having to advance the full number of spaces shown on the die. In this way they can control their progress better, for example when the lanes are blocked by other cars.

==Changing down==

A driver can skip one, two or three gears when changing down, however this wears out their gearbox. The number of gears skipped equates to the number of WP their car loses as a result. Note: It is not possible to skip four gears (from 6th to 1st gear).

==Collision==

Whenever a car ends its move on a space next to or behind one or several cars, there is a risk of collision. A driver in this situation must roll the black die to see whether there is a collision or not. If they roll a number between 1 and 4 their car loses 1 WP.

==Motor damage==

If a player rolls a 20 in 5th gear or a 30 in 6th gear, this puts a strain on their engine. After their car has finished moving they must therefore roll the black die to test whether their engine has withstood the strain. All players who are driving in 5th or 6th gear at this moment must also roll the black die. If a number between 1 and 4 is rolled, the corresponding car loses 1 WP.

==Finish==

The player whose car passes the finishing line first has won the race. The race ends when all cars have crossed the finishing line, in order to enable ranking.

==Two-lap race==

For players who have already played several single-lap games.

Whoever crosses the finishing line first after two laps wins the game. Players may make a pit stop between the first and second laps to regain the WP points they lost during the first round.

==Pit stop==

At the end of the first lap a player may decide to make a pit stop to regain all the WP they have lost. There is no speed limit in the pit lanes. It is also not necessary to roll the exact number needed to reach one’s own pit.

In the BGA adaptation, your pit box matches the colour of your car's central strip.

===Entering pits===

To enter the pits it is sufficient to roll the minimum number required or higher using the die corresponding to the selected gear. The car receives all 18 WP back and awaits their next turn to start from the pits in 4th gear (maximum).

The rules for changing down gear, collision, braking and engine damage do not apply in the pit lane. Overtaking is not possible as it is a single lane. Drivers have to be patient and wait until the car ahead of them moves forward, regardless of selected gear and with no effect on the WP.

Cars in the pit lane must wait for their turn, until the cars on the circuit between pit exit and entry have had their turn.

=Advanced Rules=

==Basics==

===The gears===

The cars have 6 gears, each gear has its own die. The numbers on the dice tell you how many spaces to move the car. The higher the gear you choose, the faster and further the corresponding die will allow the car to travel. You are not allowed to skip gears when accelerating (e.g. changing straight from 1st to 3rd gear). You are allowed to skip 1, 2, or 3 gears when braking (e.g. from 6th to 4th or from 4th to 1st gear); however there is a penalty for doing this.

{|
!Gear!! Die Color||Die Size||Movement (Number of spaces)
|-
|1||Yellow||d4||1-2
|-
|2||Orange||d6||2-4
|-
|3||Red||d8||4-8
|-
|4||Green||d12||7-12
|-
|5||Purple||d20||11-20
|-
|6||Blue||d20||21-30
|}

===Driving===

As in real life, the car starts in 1st gear. Then you up shift to 2nd gear and so on up to 6th gear, in order to move as fast as possible. When it is a driver’s turn they announce which gear they have chosen, move the gear stick on their dashboard accordingly and then rolls the die which corresponds to the chosen speed. They then moves their car forward the number of spaces indicated on the die. When the move is finished the car “stops”. This notion is important especially in the corners.

====Order of play====

In each round the drivers play according to their car position on the track.

Example: During a round of play car A overtakes car B which was in 1st position. When the next round starts, car A, now in 1st position, will play before car B.

Cars in the straight outside the pit lane will always move before cars in the pit lane. When two cars are level, the car in the highest gear goes first. When cars are level and in the same gear, the car that arrived in their current space first will go first.

==== Same position====

If two cars on the track are level with each other, the driver with the highest gear plays first.

If both cars are in the same gear, the car that arrived first at their current space plays first.

===Driving Code===

The cars drive in the track lanes. Different driving codes apply to corners and straights. It is generally not allowed to go over other cars – they must be driven round. Driving backwards is also not allowed.

====Driving code in the corners====

To drive through a corner a car must stop a minimum number of times (indicated by the number of red stop lights in the corner information box) within the limits of the corner. After the requisite number of stops, the car may proceed and exit the corner on its next move.

To make it easier to drive through the corner, the driver should consider the indicated number of spaces. The number in the green box refer to the longest path, the numbers in the red box refer to the shortest path.

====Driving code on the straights====

Straights are the portions of track between corners. Depending on the length of each straight, cars may need several rounds before entering the next corner.

'''Important''': The maneuver must be completed using the smallest number of spaces possible.

=== Wear points (WP)===

Wear Points reflect the ability of the car to stay on the track and survive events during the race. Each car has a certain number of WP at the beginning of the race, which are divided up between six different categories. These points are distributed as follows in the game for advanced players:

{|
|WP tires:||6
|-
|WP brakes:||3
|-
|WP gearbox:||3
|-
|WP car body:||3
|-
|WP engine:||3
|-
|WP road handling:||2
|}

==Preparation for play==

===Start formation===

Every player rolls the black die in order to determine the starting position of their car. Whoever rolls the highest number gains pole position. The other cars are positioned in decreasing order according to the numbers rolled. (ln the case of a tie, all concerned players re-roll the die.)

===Start===

Before engaging 1st gear, every player rolls the black die to see how successfully they can start.

====Number rolled, 1 - poor start====

The player has stalled the motor of their car. They cannot engage 1st gear and so have to wait till the next round. Then they can start in 1st gear without having to roll the black die again.

====Number rolled: between 2 and 19 - normal start====

The player can start normally. They roll the die for 1st gear and moves their car forward according to the number rolled.

====Number rolled: 2O - great start!====

The player makes a fantastic start. They move their car forward 4 spaces immediately, although they is still in 1st gear. The car can change one or two lanes to avoid other cars. The driver may shift to 2nd gear in the next round.

==Overshooting==

If a car passes through a corner at the end of its turn without making the required number of stops, it overshoots the corner. The number of spaces the car overshot the corner by is deducted from the car’s tire WP as a penalty.

'''Corner with 2 stops''': If the car has made no stops, it is automatically removed from play.

'''Corner with 3 stops''': If the car has made no stops, or only one stop, it is automatically removed from play.

When coming out of a corner the car may not change lane, but must stay in the same lane. If the move ends in another corner, this stop does not count for the new corner. If the car is blocked by another car, they cannot drive round it and has to brake.

When a car loses their last tire WP by overshooting a corner, they spin round in a circle. The car is placed on the space where their move ended, pointing backwards. The player must turn their car round again and drive off in 1st gear when it is their next turn. In this adaptation, their Tire WPs are reset to 1.

If a car loses more tire WP than it possesses, it is eliminated from the race.

==Braking==

A player may use their brake WP at any time to avoid having to advance the full number of spaces shown on the die. This can help to prevent losing tire WP if they would otherwise overshoot a corner.

A driver can find themselves blocked by one or more cars which they are unable to overtake. After the driver has moved their car forward as many spaces as possible, they counts how many spaces they would have moved if they had not been blocked.

If the number of spaces short of the full number 4 or greater, they may use Emergency Braking. In this case, their first 3 spaces must be paid for with Brake WP. Each additional space after that may be paid by either Brake or Tire WP.

Braking is paid for *after* Overshooting, so any Tire WPs lost to Overshooting will not be available for Emergency Braking.

If a car doesn't have enough brake WP and tire WP to stop before a blockage, it is eliminated from the race.

==Gearing down==

A driver can skip one, two or three gears when changing down, however this wears out their gearbox.

As a result, the car then loses a certain number of brake WP, engine WP and gearbox WP. The table below lists the corresponding wear. Note: It is not possible to skip four gears (from 6th to 1st gear).

{|
!Gears skipped!!Gearbox WP!!Brake WP!!Engine WP
|-
|1 gear||1||0||0
|-
|2 gears||1||1||0
|-
|3 gears||1||1||1
|}

If a car has no gearbox WP left, the driver can only change clown one gear at a time until the game is over.

==Collision==

Whenever a car ends its move on a space next to or behind one or several cars, there is a risk of collision. A driver in this situation must roll the black die to see whether there is a collision or not. If they rolls a 1, their car loses 1 WP.

'''In this adaptation''' the car that did not just move rolls first. If it fails the roll and is eliminated from the race as a result, the car that moved will automatically fail its roll.

'''If a car loses its last car body WP, it is eliminated''' from the race.

==Motor damage==

If a player rolls a 20 in 5th gear or a 30 in 6th gear, this puts a strain on their engine. After their car has finished moving they must therefore roll the black die to test whether their engine has withstood the strain. All players who are driving in 5th or 6th gear at this moment must also roll the black die. If a number between 1 and 4 is rolled, the corresponding car loses 1 engine WP.

If a car loses its last engine WP, it is eliminated from the race.

==Damage and road handling==

Each time a car loses a car body WP or an engine WP, a damage marker is placed on the space where the move ended.

The same applies whenever a car is eliminated from the race for whatever reason. These spaces are judged to be "dangerous" from then on.

If a car passes over one of these spaces or lands on it, the driver must roll the black die. If the result is between 1 and 4, the car loses one road handling WP. The dangerous spaces can be avoided by changing lanes.

'''If a car loses its last road handling WP, it is eliminated from the race.'''

==Slipstreaming==

If a car drives in the wake of another car, this is called slipstreaming.

For the two concerned drivers, slipstreaming is possible from the 4th gear on.

The car must be driving as fast or faster than the car in front.

If a car wants to profit from slipstreaming after moving, it has to stop directly behind another car. From this position they can then add 3 spaces onto their last move. They can move forward 3 spaces in the following way:

*change a lane, overtake the car in front and return to the original lane.
*change a lane and move two spaces in a straight line.
*change two lanes and move one space in a straight line.

The player must move a total of three spaces in any case. (However, the driver may use brake WP in order to reduce this number of spaces.) If slipstreaming brings a car up immediately behind another car, they can carry on slipstreaming (and so on).

If a car is carried into a corner by slipstreaming, they lose a brake WP (without the number of spaces being reduced).

In a corner, a slipstreaming car must follow normal driving code (eg. following the arrows).

Braking in order to take advantage of slipstreaming in the wake of another player's car is not allowed.

Drivers do not have to slipstream!

Note that in this implementation, if your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

==Pit stop==

At the end of the first lap, a player may decide to make a pit stop to regain all the tire WP they have lost. There is no speed limit in the pit lanes. It is also not necessary to roll the exact number needed to reach one's own pit.

In the BGA adaptation, your pit box matches the central colour of your car.

To enter the pits it is necessary to roll the minimum number required or higher using the die corresponding to the selected gear. As soon as the car enters the pits, it receives all its tire WP back. The player now rolls the black die, in order to see how fast their mechanics work.

===Result between 1 and 10: quick pit stop===

The player divides the number shown on the black die by two (rounding it up if necessary). The result is the number of spaces the car is allowed to move when the car leaves the pit in 4th gear.

===Result between 11 and 20: slow pit stop===

The car remains in the pit until the next round. Then the car moves on in 4th gear (or a lower gear).

The rules for gearing down, collision, braking and engine damage do not apply in the pit lane. Overtaking is not possible as it is a single lane. Drivers have to be patient and wait until the car ahead of them moves forward, regardless of selected gear and with no effect on the WP.

Cars in the pit lane must wait for their turn, until the cars on the circuit between pit exit and entry have had their turn.

==Finish==

The player whose car passes the finishing line first has won the race. The race ends when all cars have crossed the finishing line, in order to enable ranking.

=Optional Rules=

All the following rules can be used of one another.

==Construction of one's own car==

Every player can distribute their 20 WP between the zones of their car at their own discretion. At least 1 WP must be assigned to each zone.

If using the Technical Pit Stops option, 2 addition WPs are available to assign, and players may assign 0-2 points to Repair points.

==Qualifying lap with a stopwatch==

All players drive a qualifying lap with stopwatch consecutively, in order to determine their start positions. The rules for moves and driving code remain unchanged during the qualifier, however the WP are not taken into account. The only exception is if a car overshoots a corner - this is penalized.

* The player whose turn it is to drive a qualifying lap places their car in the middle lane in front of the starting line.
* You may not apply the brakes at all during Qualifying. If a roll forces you to overshoot a corner, it cannot be avoided.
* You may freely Gear down any number of gears during Qualifying, with no cost or penalty.
* The player receives a total number of points over their lap:
**1 point for each round the player takes to complete the lap
**1 point for each space the player overshoots a corner by (soft tires will have their points doubled)
**1 point for every full real-time minute it takes the player to complete the lap

'''Note:''' The qualifying lap is over if the driver does not stop at all in corners where two or three stops are required. They then have to start the race at the back of the field from the last start position.

After that the order of starting is determined: the car which has completed the qualifying lap with the fewest points takes first position. The other cars follow on in decreasing order of points. If two drivers have the same number of points, the real time taken to complete the lap decides: the fastest player gets the better start position.

== Weather Conditions ==

There is a weather chart for each "Formula D" racing circuit, which is available to all players before the game so that they can inform themselves about weather conditions during the race and qualifying laps.

lf the weather rules are used, it is strongly recommended that the tire selection rules be used as well.

Before the qualifying laps begin, the black die is rolled and the weather chart consulted:

'''Good weather''' or '''Changable''': no problems for drivers
'''Rain''': The qualifying laps for all players take place in rain (see below).

Before the actual race begins, the black die is rolled again and the weather chart consulted:

'''Good weather''': no problem.
'''Changeable''': The sky is overcast at the beginning of the race, but is does not rain '''unless''' it rained during qualifying. Either way, this can change during the course of the race. Whenever a player in 5th gear throws a 20 or a 3O in 6th gear, at the end of the round they have to roll the black die and consult the weather chart:

If "good weather" comes up. the weather conditions are shifted one line upwards.
If "rain" is the result, the weather conditions are shifted one line downwards.
If the result is "changeable", the weather stays the same.

{|
|'''Weather'''||'''Effect on race'''
|-
|Good||None. The weather will no longer change.
|-
|Good (Temporary)||None.
|-
|Changable||This is the starting step and once the weather conditions shift up or down off Changeable, it will be skipped for the rest of the game.
|-
|Rain (Temporary)||Rain.
|-
|Rain||Rain. The weather will no longer change.
|}

=== Effect of rain ===

* '''Collision''': A result of 1 or 2 (instead of just a 1, as in good weather) means a collision occurs.
* '''Engine damage''': Occurs when result is between 1 and 3 (instead of between 1 and 4, as in good weather).
* '''Road handling''': The car loses one road handling WP for a result between 1 and 5 (instead of between 1 and 4, as in good weather)
* '''Skidding on corners''': Cars will skid on corners depending on their tire selection. See "Selection of tires", below.

== Selection of tires ==

The choice of tires is crucial not just for qualifying lap, but for the race itself. When weather conditions have been determined, each player can fit their car with special tires (see below). It is also possible to change tires between qualifying lap and the race.

=== Hard Tires ===

They are recommencled on a dry track and inefficient on a wet track.

* The game rules apply unchanged if the weather is good or changeable.
* If it is raining, the car moves three additional spaces on any turn which contributes to advancing a corner.

=== Soft Tires ===

They are recommended on a dry track and inefficient - if not handicapping - on a wet track.

* If the weather is changeable or good, the car can move one additional space during each move in the qualifying or race laps. This additional move is not compulsory. But if a car overshoots a corner, the penalty is doubled (loss of tire WP). if a driver does not change their tires during a pit stop after the first lap, they lose the bonus. If a driver does not change their tires during a pit stop after the second lap, the penalties for overshooting a corner are trebled.
* If it is raining, the car travels three spaces further on any turn which contributes to advancing a corner. If a driver cloes not change their tires during a pit stop before beginning the third lap, the penalties For overshooting a corner are trebled.

Note that in this implementation, if your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

=== Rain Tires ===

They are highly recommended if it is raining, but are otherwise very sensitive.

* If the weather is changeable or good, the penalties for overshooting a corner are doubled (loss of tire WP) for qualifying and the first two laps of the race. If a driver does not change their tires before the third race lap, the
penalties are trebled.
* If it is raining, the car travels one space further on any turn which contributes to advancing a corner.

== Technical Pit Stops ==

Your pit has 2 WP which can be used during the race to regain lost WP (with the exception of tire WP). Every time a driver makes a pit stop they can choose between two options:

* '''Tire pit stop''': As in the rules for advanced players, except that the driver may change the type of tire whenever they changes tires.
* '''Technlcal pit stop''': The driver can change their tires (see above) and in addition regain up to two WP in one or two zones (except the tires). This "reservoir" of 2 WP applies for the entire duration of the race, even if it lasts for more than two laps. In the next round, the car may not start higher than 4th gear. A car with soft tires does not profit from the bonus of an additional space when leaving the pits.

== Team Race ==

A game using these rules is appropriate for a large group with an even number of players. The players form teams each with two players; each colour corresponds to a racing team. Apart from the following two exceptions, the rules apply unchanged:

* '''Pit stop''': Each team has 4 WP to repair the cars. Both players must decide together how they want to use these points.
* '''Winner by points''': A team race is not necessarily won by the first car to cross the finishing line. Each car receives a certain number of winning points. The team with the highest number of total points wins the race.

{|
|'''Ranking''||'''No. of point'''
|-
|1||1000
|-
|2||720
|-
|3||600
|-
|4||480
|-
|5||400
|-
|6||320
|-
|7||240
|-
|8||160
|-
|9||80
|-
|10||40
|}

Note that these points differ from the published rules. If qualifying is enabled, qualifying points are also awarded equally to both members of the team.

== Nitro Fuel ==

When this option is chosen, all cars have a nitro Fuel injection, which allows instant acceleration. Players can use their nitro once a lap after rolling the corresponding gear die. They receive a movement bonus according to the gear they are using at that moment (1 space in 1st gear, 2 spaces in 2nd gear, etc.). This bonus must be used completely.

When a car completes a lap, it replenishes its nitro fuel and may use it again.

Nitro may only be used if it is available when rolling the gear die. It does not become available during the same move where you complete a lap.

= BGA Rule Variations=

The BGA Adaptation of Formula D uses a number of variations from the Masters (Tournament) rules.

The differences from the rules you will find in your own copy of Formula D are:

==Round Order ==

In the original rules, if two cars are level with each other, the driver with the highest gear plays first. If both cars are in the same gear, the car nearest the inside with reference to the next (or the current) corner plays first.

In this adaptation, the higher gear continues to be first but if both cars are in the same gear *then the player who first arrived at their space* goes first. Corners no longer affect who goes first.

==Points ==

In this adaptation, points are awarded for race completion '''and''' for Qualifying (if enabled). The Qualifying points are minor by comparison and serve as a tie-break if two players are both eliminated and score 0 in the race.

{|
|'''Ranking'''||'''Race Points'''||'''Qualifying Points'''
|-
|1||1000||10
|-
|2||720||9
|-
|3||600||8
|-
|4||480||7
|-
|5||400||6
|-
|6||320||5
|-
|7||240||4
|-
|8||160||3
|-
|9||80||2
|-
|10||40||1
|}

To cover multiple players being eliminated during a game where there is not Qualifying, their distance travelled before being eliminated is used as the final tie-break (only in non-team games). If a player overshoots a corner or crashes into the back of other cars, their position at the '''start''' of the turn is used.

==Braking ==

The original rules provide a table that describes the outcome of "Emergency Braking" (when a car is blocked by one or more cars which they are unable to overtake). The table does not take Constructed Cars into account, so to clarify, the implemented rules are:

If a player performs Emergency Braking, they must move their car forward as many spaces as possible. If they need to brake more than 3 spaces, they are required to use Brake WPs for the first 3 spaces, and each subsequent space may be paid for using Brake WP *or* Tire WPs.

Braking is paid for *after* Overshooting, so any Tire WPs lost to Overshooting will not be available for Emergency Braking.

==Qualifying ==

Players do not roll the black starting die at the beginning of Qualifying: they just start in 1st gear.

The original rules simply state that "WP are not taken into account" during qualifying. However, the effect of this is clarified in this adaptation:

* You may not apply the brakes at all during Qualifying. If a roll forces you to overshoot a corner, it cannot be avoided.
* You may freely Gear down any number of gears during Qualifying, with no cost or penalty.

In this version, Qualifying awards points as long as you complete your lap:

{|
|'''Ranking''||'''No. of point'''
|-
|1||10
|-
|2||9
|-
|3||8
|-
|4||7
|-
|5||6
|-
|6||5
|-
|7||4
|-
|8||3
|-
|9||2
|-
|10||1
|}

==Collision Checks ==

In this adaptation, the active player checks for collisions only after all adjacent players have rolled. If an adjacent player fails their roll and is eliminated as a result, the active player will automatically fail their roll against that player.

==Weather Rolls ==

In the original rules, the Weather die is thrown immediately when a player rolls the maximum number in 5th or 6th gear. In this adaptation, this roll still occurs but it is deferred until the end of the round. This way, weather can only change between rounds and not in the middle of a player's turn. If multiple players roll the maximum number, the weather die will be rolled multiple times.

==Changeable Weather ==

The original rules have 4 steps for Changeable Weather (Good, Good - Changeable, Rain - Changeable, Rain).

In this adaptation, there are 5 steps: Good, Good - Temporary, Changeable, Rain - Temporary, Rain.

Changeable is only ever used at the start of a race, and by default is Good - with one exception: if it rained in qualifying then a changeable feature race will start Changeable but raining.

Weather will never be changeable in qualifying: it will be Good unless Rain is rolled.

==Spinning ==

The original rules state that if a car on 0 Tire WP overshoots a corner then it "will again spin round in a circle. If the car overshoots the corner by more than one space, it is out of the race". In this adaptation, a car with 0 Tire WP is eliminated if it overshoots a corner by more than 1 WP. Hence, even a single space overshoot will eliminate a 0 Tire WP car on soft tires.

Additionally, in this adaptation when you spin, your Tire WP are reset to 1 WP (instead of remaining at 0 WP).

==Skidding on Corners in the Rain ==

The original rules state that cars will skid in the rain "provided at least one space of the move lies within the limits of a corner". In this adaptation, skidding will only occur on any turn that counts towards a corner's completion. That means:

* Driving through a corner that you have already completed will ''not'' cause you to skid
* If you are on the final space in a corner and still need to land in it 1 more turn, you will skid on your next move even though you are driving into a straight

==Slipstreaming==

If your car has soft tires and you slipstream at the end of a move where you did not use them (but could have), you may move one additional space during your slipstream.

==Motor Damage Checks==

Motor damage checks are always performed in round order.

==Braking in the Pit Lane ==

The original rules state that the rules for braking do not apply in the pit lane. In this adaptation, there is no braking cost for stopping immediately behind another car, or in your pit box. However, there is a brake cost for travelling any distance shorter than that.

== Pit Boxes ==

In Individual Driver games, a single pit box will be reserved for each driver instead of drivers being assigned a pit box color. The box will be indicated with the player's avatar.

== Pit Lane ==

The rules for gearing down DO apply in the pit lane.

== Pit Stops ==

The soft tire bonus may not be used when moving after a Quick Pit Stop.

If Technical Pit Stops are enabled, players may always choose to take one (and thus finish their turn) even if they have no repair points or repairs to perform.

==Construction of one's own car ==

In this adaptation, if players have selected the option to Construct their own car then there are no limits to how many points they may assign to any given area.

In games that have also selected the Technical Pit Stop rules, then instead of having a fixed 2 WPs available for Pit repairs, a player will have 22 WPs to use in Construction and can choose how many repair points to make available, with a maximum of 2.

==Road Races ==

The Road Race rules, including Drivers with special abilities, are not used.

Where Road Race circuits are used, all non-standard rules are ignored.

Nitro Fuel Injection is available as an option for all races.

==Elimination ==

When a player is eliminated, the outcome is slightly different from the published rules.

*If the elimination was caused by the player overshooting corners or driving over a damage marker, the car is immediately removed from the board and '''no damage marker is placed'''
*If the elimination was caused by the player failing a motor damage test, the car is immediately removed from the board and a damage marker is added.
*If the player is eliminated by any other reason, a damage marker is added and the car remains on the board until the end of the round, when it is removed.

Using Typescript and Scss

2025-08-20T04:54:49Z

BaronFraser: /* Auto-upload generated files */

This page will help you set up your project to use Typescript client file and Scss style files, and automatically build Javascript (in ES5) files and CSS files so your project stay compatible to BGA framework requirements.
You can use only TS or only SCSS part if you want, they are not linked.

The following document is geared towards setting up a custom project where you will be in charge of typing all components that you want to use.
There is also untested 3rd party project that aims to automate some of the steps below, you can look at this instead [[BGA Type Safe Template]].

== Install and configure ==

=== Install dev stack ===
Install node/npm. Here is an example to activate auto-build in Visual Studio Code, if you use another tool I strongly recommend to find an equivalent so you don't have to launch build manually after each modification.

=== Configure package.json and tsconfig.json ===

Create a file named <code>package.json</code> on the root folder, not on the src folder.

'''package.json'''

{
"name": "yourgamename",
"version": "1.0.0",
"description": "",
"main": "YourGameName.js",
"scripts": {
"build:ts": "tsc",
"build:scss": "sass --no-source-map src/yourgamename.scss yourgamename.css",
"watch:ts": "tsc --watch",
"watch:scss": "sass --watch src/yourgamename.scss yourgamename.css",
"watch": "npm run watch:ts && npm run watch:scss",
"build": "npm run build:ts && npm run build:scss"
},
"author": "yourname",
"license": "MIT",
"devDependencies": {
"sass": "^1.32.6",
"typescript": "^4.1.3"
}
}

Note: if you not using scss - remove corresponding scripts and deps.

When package.json is created, run <code>npm i</code> on the root folder to install builders (will generate a node_modules folder).

IMPORTANT: exclude node_modules/ subfolder from auto-sync to remote folder (whatever system you use for that).

For Typescript compilation we also need to set up a <code>tsconfig.json</code> on the root folder.

'''tsconfig.json'''

{
"rootDir": ".",
"compilerOptions": {
"target": "es5",
"module": "none",
"lib": ["dom", "esnext"],
"sourceMap": false,
"typeRoots": ["src/types", "./types", "./node_modules/@types"],
"outFile": "YourGameName.js"
},
"files": [
"bga-framework.d.ts",
"src/yourgamename.d.ts",
"src/yourgamename.ts",
"src/define.ts"
]
}

Note: it only works now with es5

If you want to split your code onto multiple files, just add them in the file list (order is important for dependencies, new subpart should go on top of the list). No need to import classes or types from one file to another. In fact, you can't with this configuration.

== Create skeleton ==
When you create your game in BGA Studio, a JS and CSS file are generated. As we will overwrite them with autobuild. You can put the TS/SCSS files on a <code>src</code> folder to separate them from built files, but that's not mandatory.
Note to myself: check if 'src' dir will be svn version control, if not cannot really use it (even if duplicated in git).

=== Typescript file skeleton ===
Typescript example here have been stripped down of all comments for clarity.
Your TS code can be splitted in multiple files, you can have a look at [https://studio.boardgamearena.com/projects castlecombo] code for inspiration.
To make this page concise, I removed comments and code samples. If it's your first game, well - don't do it if your first game - you won't be able to apply other code samples from docs, they all using dojo style and have to completely rewritten.

'''src/yourgamename.d.ts'''

<pre>
interface YourGameNamePlayer extends Player {
cards: Card[]; // any information you add on each result['players']
}

interface YourGameNameGamedatas extends Gamedatas<YourGameNamePlayer> {
// Add here variables you set up in getAllDatas
discardedCards: { [row: number]: Card[] };
remainingCardsInDecks: { [row: number]: number };
tableCards: { [row: number]: Card[] };
}
</pre>
Not: the Generic typing is optional.

'''src/yourgamename.ts'''

<pre>
// @ts-ignore
GameGui = (function () { // this hack required so we fake extend GameGui
function GameGui() {}
return GameGui;
})();

// Note: it does not really extend it in es6 way, you cannot call super you have to use dojo way
class YourGameName<YourGameNameGamedatas> extends GameGui {
constructor() {}

public setup(gamedatas: any) {
this.setupNotifications();
}
public onEnteringState(stateName: string, args: any) {}
public onLeavingState(stateName: string) {}
public onUpdateActionButtons(stateName: string, args: any) {}
public setupNotifications() {}
}
</pre>

To plug the class with BGA framework, we'll also create another file:

'''src/define.ts'''

define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock"
],
function (dojo, declare) {
return declare("bgagame.yourgamename", ebg.core.gamegui, new YourGameName());
});
Copy <code>bgagame.yourgamename</code> from original JS to avoid name mistakes with letter case.

Don't forget to sync the bga-framework.d.ts from your FTP folder regularly to get the last version.

=== SCSS file ===
Nothing special here, just write classic SCSS (will be compiled by Dart scss) and name it '''src/yourgamename.scss'''.

Example:
<pre>
@use 'variables' as v;

/* the other files */
@use "./Animations";
@use "./Board";

#ebd-body {
background-image: url(img/woodbg.jpg);
background-repeat: repeat;
}
@each $key, $val in v.$colors-list {
.fgcolor#{$key} {
color: #{$val};
}

</pre>

Your SCSS code can be (should be) splitted in multiple files, for example:

'''variables.scss'''
<pre>
$colors-list: (
_6cd0f6: #6cd0f6, // blue
_ef58a2: #ef58a2, // pink
_ffcc02: #ffcc02, // yellow
_a0d28c: #a0d28c // green
);
</pre>

== Auto build and auto upload ==

=== Auto build JS and CSS files ===

To build and watch (i.e. re-build continuously changed files) run in terminal:
npm run watch

Alternately you can make vscode to do it for you by installing Run on Save extension, see details in [[Setting_up_BGA_Development_environment_using_VSCode]]

Note: to build without watch
npm run build

=== Auto-upload generated files ===
You can setup standard file sync or use vscode SFTP extension, see details in [[Setting_up_BGA_Development_environment_using_VSCode]]

Make sure that your sftp.json file has a "watcher" section to detect and upload changes made outside of the VSCode IDE.

<pre>
"watcher": {
"files": "**/*.{js,css}",
"autoUpload": true,
"autoDelete": true
}
</pre>

=== Exclusions from auto-upload ===
Make sure <code>.vscode</code> and <code>node_modules</code> are in <code>.gitignore</code> if you commit your project somewhere.

=== Code completion ===
To have a code completion for framework classes, dojo, stock, etc, you'll need to make sure bga-framework.d.ts file is added to your tsconfig.

== Using the new libs ==
To use the new front libs (bga-autofit, bga-score-sheet, ...), you will need to add a little trick as the game class is not declared inside the define function.
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
getLibUrl('bga-score-sheet', '1.0.0'),
],
function (dojo, declare, gamegui, counter, BgaScoreSheet) {
(window as any).BgaScoreSheet = BgaScoreSheet; // add this to make the variable accessible from anywhere
return declare("bgagame.castlecombo", ebg.core.gamegui, new CastleCombo());
});
When you will call <code>this.scoreSheet = new BgaScoreSheet.ScoreSheet(...)</code>, as it will be inside the Game class setup, the added line will be already executed and <code>BgaScoreSheet</code> will be available globally.

To add the lib typing to your project, follow the [[BgaScoreSheet#Using%20with%20TypeScript|Using with TypeScript]] section of the corresponding lib.

== Referenced Projects ==

* https://github.com/thoun/bga-ts-example
* https://github.com/elaskavaia/bga-dojoless
* https://github.com/NevinAF/bga-ts-template

[[Category:Studio]]