Board Game Arena - User contributions [en]

Game replay

2026-10-14T10:30:21Z

Draasill: /* How videos are generated */

{{Studio_Framework_Navigation}}

Game replay is managed by the framework. You do not need to do anything special about it in your code, except taking care of updating the client interface through the framework notification system (and not for example, by using the callback function of an ajaxcall / the promise of the bgaPerformAction method).

The game replay works like this:
* The static files for the game at the time of the game start are archived
* All notifications sent to the browser are added to the archive
* When replaying, the static files are loaded in the browser, then notifications are sent back to replay the game moves.

So in essence, the replay works like an exact recording.

NB: the game replay feature is now available on the studio (since December 2020). Please note that there may be a delay before the replay becomes available.

===Preview Videos===
Example games are periodically selected from which videos are generated to show off the game on the game panel.

Wingspan: https://x.boardgamearena.net/data/gamepreviews/1635/en-w640.webm

===How videos are generated ===

Videos are using a selected replay, the one you can click in the preview video on the game page, see screenshot below:
[[File:Table Link preview.png|none|thumb|Click here to show the replay which will be used to generate the preview]]

The replay is run with the added query parameters: <code>&autoplay&target=video</code> and recorded after 10s at 1280x800, for 30s.

===Hiding UI elements from preview video===

Some games have pop-up modals which are displayed in some cases, these should be hidden for the replay video so you can show off the gameplay right from the game page!

[[File:Mycity-with-modal.png|500px]]

Previews are generated with a query variable set <code>target=video</code>. You can check for this query param in the following way:

const searchParams = new URLSearchParams(window.location.search);
if (searchParams) {
const target = searchParams.get('target');
if (target === "video") {
// Hide modal popups...
}
}

[[Category:Studio]]

Game replay

2026-10-14T10:28:43Z

Draasill:

{{Studio_Framework_Navigation}}

Game replay is managed by the framework. You do not need to do anything special about it in your code, except taking care of updating the client interface through the framework notification system (and not for example, by using the callback function of an ajaxcall / the promise of the bgaPerformAction method).

The game replay works like this:
* The static files for the game at the time of the game start are archived
* All notifications sent to the browser are added to the archive
* When replaying, the static files are loaded in the browser, then notifications are sent back to replay the game moves.

So in essence, the replay works like an exact recording.

NB: the game replay feature is now available on the studio (since December 2020). Please note that there may be a delay before the replay becomes available.

===Preview Videos===
Example games are periodically selected from which videos are generated to show off the game on the game panel.

Wingspan: https://x.boardgamearena.net/data/gamepreviews/1635/en-w640.webm

===How videos are generated ===

Videos are using a selected replay, the one you can click in the preview video on the game page, see screenshot below:
[[File:Table Link preview.png|none|thumb|Click here to show the replay which will be used to generate the preview]]

The replay is run with the added query parameters: &autoplay&target=video and recorded after 10s at 1280x800, for 30s.

===Hiding UI elements from preview video===

Some games have pop-up modals which are displayed in some cases, these should be hidden for the replay video so you can show off the gameplay right from the game page!

[[File:Mycity-with-modal.png|500px]]

Previews are generated with a query variable set <code>target=video</code>. You can check for this query param in the following way:

const searchParams = new URLSearchParams(window.location.search);
if (searchParams) {
const target = searchParams.get('target');
if (target === "video") {
// Hide modal popups...
}
}

[[Category:Studio]]

File:Table Link preview.png

2026-10-14T10:22:31Z

Draasill:

Click here to show the replay which will be used to generate the preview

Gamehelphanabi

2026-07-21T08:08:51Z

Draasill: Undo revision 30703 by Mesentery (talk)

= Original Hanabi =
== Contents ==

* 50 cards, numbered 1, 1, 1, 2, 2, 3, 3, 4, 4, 5 for each of red, yellow, green, blue and white
* 8 Clue tokens

== Objective ==

Hanabi is a cooperative game, that is, a game where the players do not play against each other, but work as a team to achieve a common goal. The players of Hanabi become one of the people in charge of an impressive fireworks display. However, they were distracted and got the gunpowder, fuses and rockets mixed up. The show is about to start and panic is spreading. You must join forces to prevent the show from being a disaster!

The cunning pyrotechnicians must put together the fireworks in 5 series (1 white, 1 red, 1 blue, 1 yellow, 1 green), arranging the cards by colour and in ascending order (1, 2, 3, 4, 5).

== The Game ==

The players then take their turn going in a clockwise direction. On their turn, a player must complete one, and only one, of the following three actions (and they are not allowed to skip their turn):

# Give one piece of information.
# Discard a card.
# Play a card.

NOTE: When it is a player's turn, their teammates cannot comment or try to influence them. This is highly dishonorable and will bring great shame upon you.

=== 1. Giving a piece of information ===

In order to carry out this task, the player has to flip over a Clue token on the table so it is now face down. They can then tell one teammate something about the cards in front of that teammate.

Two types of information can be given and the player giving the information chooses only one type to give:

# Information about one specific COLOR (and only one)
# Information about one specific VALUE (and only one)

:'''IMPORTANT''': The player must give complete information. If a player has two green cards, the informer cannot only indicate to one of them, BOTH green cards will be indicated.

:'''NOTE''': The action cannot be performed if there are no Clue tokens face up in the right-hand area. In that case, the player has to choose to perform a different action.

=== 2. Discarding a card ===

The player then places a card from their hand in the discard pile. This moves a Clue token from the left-hand area to the right-hand area. They then take a new card from the draw pile and add it to their hand without looking at it.

:'''NOTE''': This action cannot be performed if all the Clue tokens are in the right-hand area. The player must perform a different action.

=== 3. Playing a card ===

The player takes a card from their hand and plays it to the center of the table. Two options are possible:

1. The card either begins, adds to, or completes a firework and it is then added to the appropriate color firework.
1. The card doesn't begin, add to or complete any firework. Discard the card out of the game. The fuse counter increases by one; the fuse is burning shorter and time is running out.

After playing their card, they then take a new card from the draw pile if one is available and add it to their hand without looking at it.

=== How the fireworks are built ===

* There can only be one firework of each color. The cards for a firework have to be placed in rising order (1, 2, 3, 4 and finally 5).
* There can only be one card of each value in each firework (so 5 cards in total).

=== BONUS for completing a firework ===

When a player completes a firework - i.e. they successfully play the card with a value of 5 - flip a face down Clue token back to face up on the table. This addition is free; the player does not need to discard a card. This bonus is lost if all of the Clue tokens are face up on the table.

=== End of the game ===

There are 3 ways to end the game of Hanabi:

# The game ends immediately and is lost if the third Fuse is consumed (thus revealing the explosion).
# The game ends immediately and it is a stunning victory if the firework makers manage to make the 5 fireworks before the cards run out. The players are then awarded the maximum score of 25 points.
# The game ends if a player takes the last card from the pile: each player plays one more time, including the player who picked up the last card. The players cannot pick up cards during this last round (as the pile is empty).

Once this last round is complete, the game ends and the players can then add up their score.

=== Score ===

In order to calculate their score, the players add up the largest value card for each of the fireworks.

Artistic impression is determined by the Artisan League Of Fireworks Technicians reference scale:

{| class="wikitable"
|+ Score breakdown
|-
! Points !! Overall Impression
|-
| <= 5 || Horrible, booed by the crowd...
|-
| 6-10 || Mediocre, just a hint of scattered applause...
|-
| 11-15 || Honorable attempt, but quickly forgotten...
|-
| 16-20 || Excellent, crowd pleasing.
|-
| 21-24 || Amazing, they will be talking about it for weeks!
|-
| 25 || Legendary, everyone left speechless, stars in their eyes!
|}

== Multicolor Variants ==

# Add the 6th suit to the game and attempt to create all 6 fireworks. In this variant, the multicolor suit is not wild, it's a separate firework.
# Same as Variant 1, except use only one card of each number (1, 2, 3, 4, 5) for the multicolor suit.
# Add the 6th suit to the game and these cards are now wild. In this variant, you cannot call out the multicolor suit. Instead of the multicolor cards always count as the color in your clue. But when playing the card, it counts and builds as the 6th (multicolor) firework.
# The game does not end after the round where the last card is picked up. It continues until the players are defeated (3 Fuses used up OR if an indispensable card has been discarded) or until the players are victorious (all the fireworks are completed). The players can then find themselves with fewer cards in their hand at the end of the game and the score scale is not used: the fireworks display has to be perfect. (Can also combine this with any one other variant.)

== Black Powder Variant ==

This variant adds 10 black cards to the pile. The players must form a sixth fireworks series, which will be placed on the table next to the other ones. Black cards are played in reverse order to coloured cards; that is, in descending order, from 5 to 1. When the black fireworks series is completed (with the number 1 card), players get a Clue token as a bonus, just like with the other colours.

Black cards have no colour. It is forbidden to give information about their colour. Players can only give information about their value.

:'''Note''': It is also forbidden to say “You have no black cards.”

Black cards do not score like the other colours. You’ll have to subtract 1 point from your final score for each card missing in the black fireworks display. The maximum score is still 25 points. You will be able to add the Black Powder Award to your final score, even if you don’t complete the series!

:'''Example''': at the end of the game, the black fireworks display is formed by the cards valued 5, 4 and 3. Players will subtract 2 points from their final score. Therefore, their total score will be 16 points with the Black Powder Award.

Logos for printing

2026-02-12T10:23:43Z

Draasill: fix link

= Board Game Arena Logo & QR Code Usage Guidelines =
''For Game Boxes, Rulebooks, and Printed Materials''
[[File:Logo examples displayed.png|left|thumb|923x923px]]

== 2. Why These Guidelines Exist ==
These guidelines ensure Board Game Arena branding is:

* Clear
* Consistent
* Friendly
* Easy to recognize

They also help build confidence for customers by highlighting the availability of '''online tutorials and digital versions''' of physical games.

== 4. Our Brand at a Glance ==

=== 4.1 Board Game Arena TAG Logo ===
The TAG logo is the official visual signature of Board Game Arena.
[[File:Tag example.png|left|thumb|802x802px]]

'''Rules'''

* Use '''only official logo files'''
* Do not recreate or modify the logo

'''Asset Location'''

Official files are available here:

https://content.asmodee.com/share/E6F49F19-85B6-4F20-9E9BA958ED614124/

'''Available Formats'''

* Vector: PSD
* Raster: PSD, PNG (transparent background)

'''Translations'''

* For unsupported languages, send requests or proposals to: '''publishing@boardgamearena.com'''

----

=== 4.2 QR Code Usage ===
'''Purpose'''

QR codes link directly to the game’s public page on Board Game Arena.[[File:TAG and QR code logo example.png|left|thumb]]

'''Example URL'''

<nowiki>https://boardgamearena.com/gamepanel?game=tickettoride</nowiki>

'''Generation Rules'''

* QR code must be:
** Readable
** Static (no expiration)
** Free of ads or third-party tracking

'''Recommended Generator'''

[[/www.adobe.com/express/feature/image/qr-code-generator|https://www.adobe.com/express/feature/image/qr-code-generator]]

'''If No Game Page Exists Yet'''

* Use a '''shortlink''' that can be updated later
* Temporarily redirect to the main BGA page

'''Tracking & Editable Links'''

* Contact '''publishers@boardgamearena.com''' to request:
** Trackable links
** Editable shortlinks

----

== 5. When to Use the TAG ==

=== 5.1 TAG Logo Only ===
Recommended when:

* Space is limited
* The BGA website URL is already visible
* Context is informational rather than promotional

'''Typical Placements'''

* Rulebook cover or credits page
* Box side or bottom
* Legal or publisher information sections

----

=== 5.2 TAG + QR Code ===
Recommended when:

* Inviting players to discover more content
* Targeting new players
* Supporting onboarding or promotion

'''Ideal Placements'''

* Back of the game box
* Last page of the rulebook
* Flyers, inserts, or bonus materials

----

== 6. Placement Best Practices ==

=== 6.1 Recommended Placement ===
'''General Principles'''
[[File:TAG and QR CODE placement.png|left|thumb|479x479px]]

* Keep branding visible but secondary
* The BGA logo should act as a '''helpful signpost''', not a headline
* Use both TAG and QR code where possible for awareness + action

'''Box Placement (Maximum 2 options)'''

* '''Front''': TAG only, bottom-left or bottom-right
* '''Sides''':
** Bottom for vertical sides
** Right side for horizontal sides
* '''Back''': TAG or TAG + QR code, preferably bottom-left near the barcode
* '''Post-print stickers''': Lower areas only

'''Rulebook Placement (Maximum 2 options)'''

* '''Front page''': Lower-right corner
* '''Inside pages''': Near components list or before setup (TAG only + explanation)
* '''Last page''': TAG or TAG + QR code

----

=== 6.2 Breathing Room (Clear Space) ===

* Maintain at least '''5% of the logo width''' as clear space
* No text, images, folds, or edges in this area
* Background continuity is allowed if QR readability is preserved

== 7. Size & Readability ==

=== 7.1 Minimum Sizes ===

* '''Logo minimum width''': 30 mm / 500 px at 300 dpi
* '''QR code minimum size''': 30 × 30 mm
* '''Screen usage''': Minimum 200 px width at 72 dpi

'''Testing Recommendation'''

* Test QR codes at final print scale using a basic printer and smartphone

=== 7.2 Scaling Rules ===

* Always scale proportionally
* No stretching, squashing, or distortion
* QR code width must match TAG width

== 8. Colors & Backgrounds ==

=== 8.1 Approved Versions ===

* Three TAG versions per language
* Three standard color schemes available
* Text must not be altered
* New translations require validation

'''QR Code Exception'''

* QR code colors may be inverted '''only''' to improve contrast

=== 8.2 Background Guidelines ===

* Use clean, high-contrast backgrounds
* Avoid busy textures or patterns
* QR code must be placed on:
** Solid black '''or''' solid white background
* Avoid glossy or varnished finishes

== 9. Supporting Text (Optional) ==
Optional friendly copy may be added '''before''' the logo or QR code:

Examples:

* “Discover more games, content, and updates!”
* “Scan the QR code to discover our tutorial!”

Guidelines:

* Keep text secondary
* Let the logo and QR code remain the focus

== 10. What to Avoid ==
Do '''not''':

* Change logo colors outside approved versions
* Add shadows, outlines, gradients, or effects
* Rotate or skew logos or QR codes
* Place on cluttered or low-contrast backgrounds
* Use multiple localized QR codes for language purposes

<blockquote>Note: Multiple QR codes may be used '''only for sales tracking''', not localization.</blockquote>

== 11. Promotional Uses (Advert) ==
The BGA TAG and QR code may also be used:

* As buttons on websites or product pages
* On banners or printed materials at events
* In videos showcasing final packaging
* Alongside other platform tags (Apple Store, Google Play, etc.)

== 12. Need Help? ==
If you are unsure about placement, sizing, or new use cases, contact us.

'''Contact'''

publishers@boardgamearena.com

Logos for printing

2026-02-12T10:22:50Z

Draasill: Protected "Logos for printing" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

= Board Game Arena Logo & QR Code Usage Guidelines =
''For Game Boxes, Rulebooks, and Printed Materials''
[[File:Logo examples displayed.png|left|thumb|923x923px]]

== 2. Why These Guidelines Exist ==
These guidelines ensure Board Game Arena branding is:

* Clear
* Consistent
* Friendly
* Easy to recognize

They also help build confidence for customers by highlighting the availability of '''online tutorials and digital versions''' of physical games.

== 4. Our Brand at a Glance ==

=== 4.1 Board Game Arena TAG Logo ===
The TAG logo is the official visual signature of Board Game Arena.
[[File:Tag example.png|left|thumb|802x802px]]

'''Rules'''

* Use '''only official logo files'''
* Do not recreate or modify the logo

'''Asset Location'''

Official files are available here:

[[/content.asmodee.com/share/E6F49F19-85B6-4F20-9E9BA958ED614124/|https://content.asmodee.com/share/E6F49F19-85B6-4F20-9E9BA958ED614124/]]

'''Available Formats'''

* Vector: PSD
* Raster: PSD, PNG (transparent background)

'''Translations'''

* For unsupported languages, send requests or proposals to: '''publishing@boardgamearena.com'''

----

=== 4.2 QR Code Usage ===
'''Purpose'''

QR codes link directly to the game’s public page on Board Game Arena.[[File:TAG and QR code logo example.png|left|thumb]]

'''Example URL'''

<nowiki>https://boardgamearena.com/gamepanel?game=tickettoride</nowiki>

'''Generation Rules'''

* QR code must be:
** Readable
** Static (no expiration)
** Free of ads or third-party tracking

'''Recommended Generator'''

[[/www.adobe.com/express/feature/image/qr-code-generator|https://www.adobe.com/express/feature/image/qr-code-generator]]

'''If No Game Page Exists Yet'''

* Use a '''shortlink''' that can be updated later
* Temporarily redirect to the main BGA page

'''Tracking & Editable Links'''

* Contact '''publishers@boardgamearena.com''' to request:
** Trackable links
** Editable shortlinks

----

== 5. When to Use the TAG ==

=== 5.1 TAG Logo Only ===
Recommended when:

* Space is limited
* The BGA website URL is already visible
* Context is informational rather than promotional

'''Typical Placements'''

* Rulebook cover or credits page
* Box side or bottom
* Legal or publisher information sections

----

=== 5.2 TAG + QR Code ===
Recommended when:

* Inviting players to discover more content
* Targeting new players
* Supporting onboarding or promotion

'''Ideal Placements'''

* Back of the game box
* Last page of the rulebook
* Flyers, inserts, or bonus materials

----

== 6. Placement Best Practices ==

=== 6.1 Recommended Placement ===
'''General Principles'''
[[File:TAG and QR CODE placement.png|left|thumb|479x479px]]

* Keep branding visible but secondary
* The BGA logo should act as a '''helpful signpost''', not a headline
* Use both TAG and QR code where possible for awareness + action

'''Box Placement (Maximum 2 options)'''

* '''Front''': TAG only, bottom-left or bottom-right
* '''Sides''':
** Bottom for vertical sides
** Right side for horizontal sides
* '''Back''': TAG or TAG + QR code, preferably bottom-left near the barcode
* '''Post-print stickers''': Lower areas only

'''Rulebook Placement (Maximum 2 options)'''

* '''Front page''': Lower-right corner
* '''Inside pages''': Near components list or before setup (TAG only + explanation)
* '''Last page''': TAG or TAG + QR code

----

=== 6.2 Breathing Room (Clear Space) ===

* Maintain at least '''5% of the logo width''' as clear space
* No text, images, folds, or edges in this area
* Background continuity is allowed if QR readability is preserved

== 7. Size & Readability ==

=== 7.1 Minimum Sizes ===

* '''Logo minimum width''': 30 mm / 500 px at 300 dpi
* '''QR code minimum size''': 30 × 30 mm
* '''Screen usage''': Minimum 200 px width at 72 dpi

'''Testing Recommendation'''

* Test QR codes at final print scale using a basic printer and smartphone

=== 7.2 Scaling Rules ===

* Always scale proportionally
* No stretching, squashing, or distortion
* QR code width must match TAG width

== 8. Colors & Backgrounds ==

=== 8.1 Approved Versions ===

* Three TAG versions per language
* Three standard color schemes available
* Text must not be altered
* New translations require validation

'''QR Code Exception'''

* QR code colors may be inverted '''only''' to improve contrast

=== 8.2 Background Guidelines ===

* Use clean, high-contrast backgrounds
* Avoid busy textures or patterns
* QR code must be placed on:
** Solid black '''or''' solid white background
* Avoid glossy or varnished finishes

== 9. Supporting Text (Optional) ==
Optional friendly copy may be added '''before''' the logo or QR code:

Examples:

* “Discover more games, content, and updates!”
* “Scan the QR code to discover our tutorial!”

Guidelines:

* Keep text secondary
* Let the logo and QR code remain the focus

== 10. What to Avoid ==
Do '''not''':

* Change logo colors outside approved versions
* Add shadows, outlines, gradients, or effects
* Rotate or skew logos or QR codes
* Place on cluttered or low-contrast backgrounds
* Use multiple localized QR codes for language purposes

<blockquote>Note: Multiple QR codes may be used '''only for sales tracking''', not localization.</blockquote>

== 11. Promotional Uses (Advert) ==
The BGA TAG and QR code may also be used:

* As buttons on websites or product pages
* On banners or printed materials at events
* In videos showcasing final packaging
* Alongside other platform tags (Apple Store, Google Play, etc.)

== 12. Need Help? ==
If you are unsure about placement, sizing, or new use cases, contact us.

'''Contact'''

publishers@boardgamearena.com

Logos

2026-01-09T16:53:54Z

Draasill: Protected "Logos" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

On this page you can find brand assets for Board Game Arena and easy way to create links to BGA.

Please use "right click + save image as" to download needed images.

=== '''LOGOS and GUIDELINES for printing can be found on this page''' : [[Logos for printing]] ===

= BGA buttons =

You can use buttons below as links to BGA website.

If you need a button that is not on the list please contact us (contact@boardgamearena.com).

These buttons should be used on Websites/Printed materials

'''Colors and text shouldn't be altered.'''

You can find the all-purposes PSD files by clicking the link below:

https://content.asmodee.com/share/E6F49F19-85B6-4F20-9E9BA958ED614124/
== English ==
[[File:Logo yellow eng.png|left|thumb]]

[[File:Logo red eng.png|left|thumb]]

[[File:Logo blue eng.png|left|thumb]]

These buttons should be used on Websites/Printed materials

'''Colors and text shouldn't be altered.'''

You can find the all-purposes PSD files by clicking the link below:

https://content.asmodee.com/share/E6F49F19-85B6-4F20-9E9BA958ED614124/

-

== French ==
[[File:Logo Yellow.png|left|thumb]]

[[File:Logo Red.png|left|thumb]]

[[File:Logo Blue.png|left|thumb]]

Ces boutons doivent être utilisés sur les sites Web/supports imprimés.

'''Les couleurs et le texte ne doivent pas être modifiés'''.

Vous trouverez les fichiers PSD polyvalents en cliquant sur le lien ci-dessous :

https://content.asmodee.com/share/E6F49F19-85B6-4F20-9E9BA958ED614124/

-

== German ==

[[File:Logo yellow ger.png|left|thumb]]

[[File:Logo red ger.png|left|thumb]]

[[File:Logo blue ger.png|left|thumb]]

Diese Schaltflächen müssen auf Websites/in Druckerzeugnissen verwendet werden.

'''Die Farben und der Text dürfen nicht verändert werden.'''

Die vielseitigen PSD-Dateien finden Sie unter dem folgenden Link:

https://content.asmodee.com/share/E6F49F19-85B6-4F20-9E9BA958ED614124/

= BGA logos =

== BGA horizontal logo ==

Should be used on a white background and submitted to our team for final approval.

[[File:BGA LARGEHORIZONTAL LOGO.png|left|thumb]]

[[:File:BGA LARGEHORIZONTAL LOGO.png]]

== BGA horizontal short logo ==

Should be used on a white background and submitted to our team for final approval.
[[File:BGA Transparent short logo.png|left|thumb]]

[[:File:BGA Transparent short logo.png]]

== BGA Icon logo ==
[[File:BOARDGAME ARENA ICON RGB.png|left|thumb]]

[[:File:BOARDGAME ARENA ICON RGB.png]]

Should be used on a white background and submitted to our team for final approval.

= BGA QRCODE Examples =

Please ask us whenever you need to use your own QR code.

The link should always be linked to your game page - Example: [https://boardgamearena.com/gamepanel?game=yourgame https://boardgamearena.com/gamepanel?game=YOURGAME]

If you want to get a shortlink to get it tracked, please send us an email.

[[File:Qrcode adobe example.png|left|thumb]]

We would preferably ask you to use the Adobe QR Code generator, available there: https://www.adobe.com/express/feature/image/qr-code-generator Set the styling as the example below:

== English (default) ==
[[File:Qrcode example eng.png|left|thumb|554x554px]]

QR Code examples for printing on game boxes/rulebooks.

== French ==
[[File:Qrcode example french.png|left|thumb|547x547px]]

QR Code examples for printing on game boxes/rulebooks.

== German ==
[[File:Qrcode example ger.png|left|thumb|551x551px]]

QR Code examples for printing on game boxes/rulebooks.

File:ImageTestTof.png

2025-03-13T15:50:23Z

Draasill:

just a test

Gamehelparknova

2024-03-26T10:19:19Z

Draasill:

Welcome to Ark Nova! In this game, you'll manage a modern zoo. In addition to building enclosures and putting popular and well-liked animals into them, you'll also gain sponsors and support conservation projects. You'll do this by taking one of five actions each turn, with each of them having strength related to their position in the line - the longer it's been since the last time you took that action, the more powerful it'll be. Your score is measured by both your Appeal (ticket icon) and Conservation (green shield icon), and when they cross each other on the scoring track, the endgame is triggered. After one more round the player with the most points, as measured by how far apart these two trackers are from each other, wins the game!

==What To Do On Your Turn==
When it's your turn, you'll choose one of the five action cards in front of you. This action has a strength associated with it, based on its position along the bottom of your board, ranging from 1 to 5. You'll be able to add to this value by spending X-tokens. After performing that action, it moves to the far left position, at strength 1, pushing all other action cards one space to the right.

Upon achieving certain conditions, you'll be able to upgrade these action cards as well by flipping them to the pink side, where they will remain for the rest of the game. These upgraded actions will allow you to use these actions more efficiently, but otherwise follow the same rules as their basic form.

===The Build Action===
The basic Build action allows you to build one new enclosure or special building 1 to 5 tiles in size. You need to build enclosures in order to place animals in your zoo. To do this, you'll pay 2 money per hex (for example, you would pay 6 money for a size 3 enclosure or for a Petting Zoo special building). All enclosures and buildings must be placed touching already-existing enclosures or buildings in your zoo. Enclosures and buildings cannot overlap, and no tiles can be placed on top of the rock or water spaces already printed on your zoo map.

Some spaces have a purple shovel and a "II" - these cannot be built upon until you upgrade your Build action.

Tiles with other icons on them are "placement bonuses" - upon building on these spaces, you gain the bonuses pictured on them.

At any point, you can see all the possible basic enclosure and building shapes in a tab by clicking the little shovel icon near the top right corner of your map.

==== Special buildings ====

A Kiosk is a dark gray building of size 1. A Kiosk gives you money each break during the income phase -- 1 money for each adjacent building or occupied enclosure.

A Pavilion is a pink building of size 1. Upon placing a Pavilion, you gain 1 appeal.

A Petting Zoo is a special enclosure of size 3. Some animals must be placed in a Petting Zoo, but multiple animals can coexist in the building. You can only build one Petting Zoo.

==== The Upgraded Build Action: ====

# Allows you to build multiple '''different''' enclosures and/or buildings with a total size no more than the action strength - for example at strength 5, you could build a size 3 enclosure, size 1 enclosure, and a kiosk all at once (but not a size 3 enclosure and two kiosks; they must all be different);
# Allows you to build on spaces requiring the upgraded Build action;
# Allows you to build a Reptile House and a Large Bird Aviary. Much like the Petting Zoo, these buildings can house multiple animals of a particular type. When you build a Reptile House or Large Bird Aviary, if you have an animal that could be housed in one of these special buildings, you may immediately move it to the building, freeing up that enclosure for another animal.

=== The Cards Action ===

The Cards action allows you to draw more cards. Depending on the strength of this action, you'll draw one or more cards from the top of the deck and possibly discard cards from your hand (possibly including ones you just drew). At strength 5, you may instead "snap" one card from the board directly to your hand. Keep in mind that the hand limit (3, or 5 if you've acquired the appropriate University) will be enforced during Breaks. Additionally note that using the Cards action moves the Break counter up by 2.

==== The Upgraded Cards Action ====

# Allows you to draw cards directly from the board within your reputation range (to the left of your reputation marker);
# Allows you to "snap" cards from the board at strength 3 or more;
# Allows your reputation range to reach levels higher than 9, with associated bonuses;
# Allows you to draw more cards overall at a given strength and discard fewer cards.

===The Animals Action===

The Animals action allows you to play animal cards into your zoo. Each animal has a money cost and also requires an enclosure of a specific size or higher. Some may also need to border the rocks/or water. Be sure to note any other prerequisites which are listed on the left side, such as having a particular icon (e.g. Australia, Predators, or Research) in your zoo. Prerequisites for playing the card will always be on its left edge.

When you play a new animal card, you gain the bonuses listed on the bottom edge of the card. The most common things this gives are

# Appeal points (ticket icon)
# Conservation points (green shield icon)
# Reputation points (black mortarboard cap icon)

Most animal cards will have at least one animal type - Reptiles, Birds, Bears, etc. - and a region - Americas, Africa, Europe, etc. (Petting Zoo animals do not have a region.) These icons are very important for deciding which Conservation Projects you can score later.

==== The Upgraded Animals Action ====

# Allows you to play multiple animal cards at a lower strength;
# Allows you to play animals from your reputation range (to the left of your reputation marker) and not just your hand;
# Allows you to play certain animals that list Animals (II) as a prerequisite on their left edge.

===The Sponsors Action===

The basic Sponsors action allows you to play a sponsor (blue) card from your hand. The minimum action strength required for each Sponsor card is listed at its top-left corner. These typically don't cost any money to play, but may have other requirements. Sponsor cards are color-coded to tell you whether they will give you benefits now, later, and/or at the end of the game:

# A yellow box lists what you get immediately when the card is played;
# A purple box lists what you get on each break;
# A blue box lists what you get upon another condition such as playing or getting certain icons;
# A brown box lists what you will get at the end of the game.
If you don't have any Sponsor cards you want to play, you can also use the Sponsors action to both gain money and move the Break up by an amount equal to the action's strength.

==== The Upgraded Sponsors Action ====

# Allows you to play sponsors from the board within reputation range (to the left of your reputation marker) instead of from your hand;
# Allows you to, instead of playing a Sponsor card, gain money equal to the twice the action's strength (and Break equal to the action's strength);
# Allows you to play sponsors that list Sponsors (II) as a requirement;
# Allows you to play multiple sponsors with a single action;
# Allows you to play sponsors of 1 greater strength than the strength of the action.

===The Association Action===

The Association action allows you to send your worker(s) to the association board to take actions there. You start with just one worker, but can gain more workers as the game progresses. Workers return to your supply only at Breaks. When you use the Association action, you may do one of four things depending on the strength of the action:

* Strength 2: Gain 2 reputation (one of the most straightforward ways to get reputation);
* Strength 3: Gain a partner zoo (handshake icon). Playing animals from that continent permanently costs 3 less money per continent icon they have, and you gain an icon of that type. Place this on the right side of your board (starting at the bottom) -- you gain any bonus this covers up.
* Strength 4: Gain a partner university (gray monument icon) -- these will give reputation, research icons, or an improved hand size limit;
* Strength 5: You can support a conservation project (existing or from hand) -- these will typically be some milestone, for example requiring a number of Africa icons or Reptile icons.
Other players' workers do not affect your ability to place your workers; there is unlimited space on each section of the Association board. However, choosing the same Association action a second time before the Break will cost you two workers instead of one (for a total of three). All the partner zoo and university tiles will be replenished at each Break.

==== Conservation Projects ====

Typically conservation projects will give you all-important conservation points, and possibly other benefits. To score a conservation project, your Association action must be at 5 strength. When you take the action, take one of the cubes from the left side of your player board and place it on the conservation project. Whatever space the cube comes off is the benefit you'll get. If it comes from the yellow section, you'll get the benefit immediately but only once, and if it comes from the purple/yellow section, you get the bonus immediately and also at each Break. Note that you typically can't claim more than one level of a particular conservation project, so you'll have to judge when it's time to take the action vs waiting until you have more of the appropriate icons.

If a conservation project requires you to "release an animal", you'll be discarding a previously played animal, losing its appeal points and icons, as well as emptying an enclosure of the same size as the animal required. However you'll still have the conservation points and can reuse the enclosure. Therefore, it can be beneficial to release animals with icons for which you've already scored the relevant conservation project.

Base conservation cards are drawn at the beginning of the game and known to every player. They involve collection species or habitat icons. There are additional conservation project cards in the cards deck that can be played from your hand when performing supporting a conservation project with the Association action.

==== The Upgraded Association Action: ====

* Allows you to split the actions' strength between multiple actions;
* Allows you to have more partner zoos;
* Allows you to donate money directly to get conservation points! The first person who uses this pays only 2 money for a conservation point, but every person who uses it thereafter must pay more and more, to a maximum of 12 money for a conservation point;
* Allows you to play conservation project cards from the board within reputation range (to the left of your reputation marker).

===The X-Token action===

If you can't or don't want to take any of the other actions, you may take one X-Token from the supply. Recall that you can spend X-tokens to increase the strength of any action by 1 (per token). After taking the X-token, move any action card to strength 1 of your board, pushing the other cards to the right. This is not usually an efficient choice, but can be a good way to gain X-tokens.

== Upgrading Action cards ==

There are four ways to upgrade an action card. Since there are five actions cards, at least one will not be upgraded each game. The four ways to upgrade a card are:
# Advancing your conservation score to 2 (this gives the option of either upgrading a card ''or'' gaining an additional association worker);
# Advancing your reputation to 5;
# Playing a second university;
# Playing a second partner zoo.

== Gaining additional Association workers ==

Recall that each association action requires an association worker, and if you have already taken that association action since the last break, it requires two association workers. Your association workers are returned to you when the Break occurs. You start the game with one worker, and can gain up to three more. Depending on which map you are using, there also may be a conservation point bonus for obtaining your fourth conservation worker.

The ways to obtain additional conservation workers are:
# Advancing your conservation score to 2 (this gives a choice between getting an association worker ''or'' upgrading a card);
# Advancing your reputation score to 8;
# If an association worker is one of the bonuses that may be chosen when you support a conservation project (except when using map 0, where instead a conservation worker may be obtained by covering a specific spot on your zoo map)
# Gaining a third partner zoo (this requires that the association action has been upgraded)
# Certain animals (usually bears) and sponsors have the ''Full-Throated'' ability, which gains you an association worker when played.

== Tracks ==

=== Break Track ===

Players continue taking actions, some of which generate Break, until the Break track meets or exceeds 15. The player who triggered the Break receives one X-token. Then, the following steps happen:

# All players discard down to their hand limit (starting hand limit is 3, but having the relevant University ups it to 5);
# Take any multiplier tokens off action cards, and any venom/constriction tokens off cards, if any exist;
# Return all Association workers to the players and replenish the partner zoos and partner universities;
# Discard the two leftmost cards of the card display, slide the remaining cards left, and replenishing the display;
# All players receive income from base zoo appeal, kiosks, sponsors, and possibly spaces on the left side of the board from which cubes have been removed to contribute to conservation projects.

Then the Break track marker resets and the next player can take their turn as normal.

=== Appeal Track and Conservation Track ===

To track how many Appeal points and Conservation points players have, you have two tokens that start from opposite ends of a long track. (On boardgamearena, you can click the appeal + conservation icon in the top right to see this.) Note that conservation points are more valuable than appeal (one conservation is roughly equal to three appeal), but also more difficult to gain.

Moving your marker further on the appeal (tickets icon) track increases the amount of income you get per turn.

Moving your marker to certain key points on the Conservation track (green shield icon) gives the effects in pentagons:

* (At 2 points) You may either upgrade an action or gain an Association worker;
* (At 5 and 8 points) You may gain a benefit chosen for that particular game, each shown in a yellow pentagon. (Everyone can get the 5 money bonus, but only one player can get each of the others);
* (At 10 points) '''All players''' discard one of their bonus cards from the game start. (This only happens the first time this is reached.)

=== Reputation Track ===

The Reputation track is largely used for drawing and playing cards from within reputation range. By playing directly from the display, players can more efficiently play animals, sponsors, and conservation projects. Note that playing directly from reputation range has an additional cost equal to the card's location in the display -- playing an animal at the 6th folder would cost 6 additional money.

As with the conservation track, there are bonus effects when crossing certain levels on the Reputation track, most of which are near the end of the track. Keep in mind players will need the upgraded Cards action to gain more than 9 reputation.

==Game End==

If at the end of your turn or during a break your Conservation counter and Appeal counter are ever in the same scoring area, or if they have passed one another, the end of the game is triggered. If a player triggers the end during their turn, all '''other''' players will take one more turn. If the end of the game is triggered during a Break, '''all''' players will take one more turn.

At the end of the game, you still get conservation points or appeal from your Final Scoring card(s), as well as from all your cards with end-of-game scoring (generally the brown section on Sponsors cards).

==Score==
Scoring is different to the original game: All conservation point spaces feature a small number. To determine your score, you must add your appeal to the number of the space with your conservation point marker on it. No more calculating the distance between your 2 markers. The numbers are calculated in such a way that having your 2 markers reach each other will score you exactly 100 points. If your markers cross, your score will be above 100; if they don't, it will be below. Therefore, 100 is the point threshold to end the game. In case of a tie, the tied player who supported the most Conservation Projects wins the game.
==Maps==

'''Map 1 (Observation Tower):''' The enclosure must be adjacent to the space with the tower, not merely to any one of the other 3 rock spaces. The platform has no effect on special enclosures. If you release an animal into the wild (and thus flip an occupied enclosure back to the empty side) and then accommodate a new animal in this enclosure, you gain the 2 appeal again. The Observation Tower itself does not count as a building (e. g. for kiosks).

'''Map 2 (Outdoor Areas):''' The enclosure must be adjacent to the space with the Outdoor Area, not merely to any one of the other 4 water spaces. The Outdoor Area has no effect on special enclosures. Treat any standard enclosure adjacent to the Outdoor Areas as if it were 2 spaces larger (after it is placed there). The Outdoor Area itself is not considered a building (e. g. for kiosks). Example: If you have built a standard 1-space enclosure adjacent to the Outdoor Area, you may accommodate an animal there that requires an enclosure of 1, 2, or 3 spaces.

'''Map 4 (Commercial Harbor):''' The Commercial Harbor is considered to be connected as soon as you have placed a building on the adjacent building space. You may build your first building directly adjacent to the Commercial Harbor, but you do not have to. You may use the ability at any time during your turn, before, after, or during an action. However, you may only discard 1 card with the Commercial Harbor per turn. You may not use the ability during a break or someone else’s turn. The Commercial Harbor itself does not count as a building (e. g. for kiosks).

'''Map 5 (Park Restaurant):''' During the break, you gain income of 1 money for each space adjacent to the Park Restaurant with a building on it. It does not matter if these are single buildings or if several spaces belong to the same building. It also doesn’t matter what kind of buildings you build there and whether enclosures are occupied or not. The Park Restaurant itself does not count as a building.

'''Map 6 (Research Institute):''' The Research Institute is considered connected as soon as you have placed a building on the adjacent building space. You may build your first building directly adjacent to the Research Institute, but you do not have to. Once active, you can play Animal cards even when you are 1 condition short; you must still fulfill all other conditions. You cannot ignore rock or water requirements.

'''Map 7 (Ice Cream Parlors):''' If you have covered all bonus spots granting kiosks, you gain 1 additional money for each kiosk on your zoo map as income during the break. It does not matter if these kiosks were built as placement bonuses or by other means. It also does not matter if they generate income without this bonus or not.

'''Map 8 (Hollywood Hills):''' Spaces with an 'H' may be covered like any other space. This is similar to a placement bonus, but does not count as one (e. g. for card 221). Every time you place a building on an H, reveal cards from the deck one by one until you reveal a Sponsor card. Add this card to your hand and put all other revealed cards onto the discard pile. Once you have covered all 3 spaces, the level of each Sponsor card you play is 1 lower.

== Quick Synopsis aka TL:DR ==

There are six (6) actions can perform, dependent on the position is the strength of that action, rightmost being five (5). Once you use an action it moves to the 1st position and everything to the left of its prior position increases by one (1).

1. Association: These allow you to use an associate (start with one) to being more academic, connecting up with zoo to reduce your costs of animals, associating with an institution which offers research, more academia or allowing more cards after a break

2. Build: Allows you to make an enclosure for an animal, the size must meet the requirement of the animal, or you can increase appeal (+1 income) or vendor booth (+1 income for filled exhibits and such). There are also special
enclosures that allow you to house animals more efficiently or are requirements.

3. Draw Card: Allows you to draw an amount of cards into your hand you may need to discard at the end. You may also be able to "snap" cards available from the board based on your current academia level (and Draw Card strength). You also may also be able to play these cards directly if you have the level 2 of an action.

4. Play Animals: Play an animal or animals from your hand (and sometimes from available choices) they must meet the requirements on the left in order to be played (It will also tell you if you can play them)

5. Sponsor: Play a sponsor from your hand (or available choices - like animals). These give you various bonuses sometimes immediately, sometimes between breaks, sometime when doing things.

6. Get a +1 strength, multiple (up to 5) may be used to increase a weaker action to the level you need it at. This also forces you to move an action to the left

During breaks you get an amount of money equivalent to how attractive your zoo is, possibly sponsors, possibly vending stalls.

Options and preferences: gameoptions.json, gamepreferences.json

2022-11-07T15:47:17Z

Draasill: /* option display */

{{Studio_Framework_Navigation}}

In this file, you can define your game options (i.e. game variants) and user preferences.

Note: If your game has no variants or preferences, you don't have to modify this file.

'''IMPORTANT:''' after you edited this file and syncronized to ftp folder you have to go to the control panel and press "Reload game options configuration" for your changes '''to take effect'''.

Make sure you understand difference between options and preferences:
* Game options - something usually in the rule book defined as "variant" (except for 2,3,X people - that is automatically handled - you can query it)
* User preferences - personal choices of each player only visible to that specific player - i.e. layout, either or not to prompt for action, either or not auto-opt in in some actions, etc

__TOC__

== Game Options ==

Game options are selected by the table creator and usually correspond to game variants, for example if the game includes expansions or certain special rules.

These variants are defined in gameoptions.inc.php as the $game_options variable:

$game_options = [ // exactly named that
// options start with 100
100 => [ /*option description array for option 100*/ ],
101 => [ /*option description array for option 101*/ ],
// etc
];

All options defined in this file should have a corresponding "game state label" with the same ID (see "initGameStateLabels" in yourgame.game.php)

self::initGameStateLabels ([
...
"my_game_variant" => 100,
]);

Numbers have to be exactly from 100 to 199 (there can be gaps).

That is how you access them during runtime:

public function isSecondVariant() {
return $this->getGameStateValue('my_game_variant') == 2;
}

Or this
$this->gamestate->table_globals[100]

The following are the parameters of option description array:
* '''name''' - '''mandatory'''. The name of the option visible for table creator. Value must be wrapped in totranslate function.
* '''values''' - '''mandatory'''. The array (map) of values with additional parameters per value.
** '''name''' - '''mandatory'''. String representation of the numeric value visible to table creator. Value must be wrapped in totranslate function.
** '''description''' - String description of this value to use when the name of the option is not self-explanatory. Displayed at the table under the option when this value is selected.
** '''tmdisplay''' - String representation of the option visible in the table description in the lobby. Usually if a variant values are On and Off (default), the tmdisplay would be same as description name when On, and nothing (empty string) when Off. ('''Warning''': due to some caching, a change in tmdisplay may not be effective immediately in the studio, even after forcing a reload of gameoptions.inc.php.) '''Pro Tip:''' You can use this as a pre-game communication by adding fake options that just do nothing in the game but make it easier to find other player wanted the same game configuration (see the crew deep sea for example).
** '''nobeginner''' - Set to true if not recommended for beginners
** '''firstgameonly''' - Set to true if this option is recommended only for the first game (discovery option)
** '''beta''' - Set to true to indicate that this option is in "beta" development stage (there will be a warning for players starting the game)
** '''alpha''' - Set to true to indicate that this option is in "alpha" development stage (there will be a warning, and starting the game will be allowed only in training mode except for the developer)
** '''premium''' - Option can be only used by premium members
* '''default''' - indicates the default value to use for this option (optional, if not present the first value listed is the default)
* '''displaycondition''' - checks the conditions before displaying the option for selection. All conditions must be true for the option to display. Supported condition types:
** ''minplayers'' condition ensures at least this many players (Note: if your game works with a disjoint interval of player counts, you can supply an array of valid counts instead of a single value)
** ''maxplayers'' conditions ensure at most this many players
** ''otheroption'' condition ensures another option is set to this given values.
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given values
* '''displayconditionoperand''' - can be 'and' (this is the default) or 'or'. Allows to change the behaviour to display the option if one of the conditions is true instead of all of them.
* '''startcondition''' - checks the conditions (on options VALUES) before starting the game. All conditions must be true for the game to start, otherwise players will get a red error message when attempting to begin the game. Supported condition types:
** ''minplayers'' condition ensures at least this many players (Note: if your game works with a disjoint interval of player counts, you can supply an array of valid counts instead of a single value)
** ''maxplayers'' conditions ensure at most this many players
** ''otheroption'' conditions ensure another option is set to this given values. That works the same as in '''displaycondition'''.
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given value. That works the same as in '''displaycondition'''.
*: For all these condition types, a ''gamestartonly'' boolean option can be added, if you have options that are exclusive. Setting this boolean to ''true'' will defer the evaluation of the startcondition to the game creation, instead of preventing the player to select options that are exclusive at all. See [[#gamestartonly|below]] for an example.
* '''notdisplayedmessage''' - if option is not suppose to be visible because of displaycondition but this is set, the text will be visible instead of combo drop down
* '''level''' - what kind of option it is: ''base'', ''major'', or ''additional''. See [[#option_level|below]] for more informations.

Common options for all tables (reserved range 200-299):
*201 (const GAMESTATE_RATING_MODE) - ELO OFF (aka Training mode),
*200 (const GAMESTATE_CLOCK_MODE) - game speed profile, array(0,1,2) - realtime (technically <10 realtime but you cannot define range in php), values >=10 - turn based (currently 10..21)

Example:
<pre>
$game_options = array(
100 => array(
'name' => totranslate('my game option'),
'values' => array(
// A simple value for this option:
1 => array(
'name' => totranslate('option 1')
),

// A simple value for this option.
// If this value is chosen, the value of "tmdisplay" is displayed in the game lobby
2 => array(
'name' => totranslate('option 2'),
'tmdisplay' => totranslate('option 2')
),

// Another value, with other options:
// beta=true => this option is in beta version right now.
// nobeginner=true => this option is not recommended for beginners
3 => array(
'name' => totranslate('option 3'),
'beta' => true,
'nobeginner' => true
),
),
'default' => 1
),

101 => array(
'name' => totranslate('Draft variant'),
'values' => array(
1 => array(
'name' => totranslate('No draft')
),
2 => array(
'name' => totranslate('Draft'),
'tmdisplay' => totranslate('Draft'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100, // Game specific option defined in the same array above
'value' => array(2, 3, 4)
),
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1 // 1 if OFF
)
),

'startcondition' => array(
1 => array(),
2 => array(
array(
'type' => 'maxplayers',
'value' => 3,
'message' => totranslate('Draft option is available for 3 players maximum.')
)
),
),
),

102 => array(
'name' => totranslate('Takeovers'),
'values' => array(
2 => array(
'name' => totranslate('No takeover')
),
1 => array(
'name' => totranslate('Allow takeovers'),
'tmdisplay' => totranslate('Takeovers'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array( // Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100,
'value' => array(3, 4)
)
),
'startcondition' => array(
2 => array(),
1 => array(
array(
'type' => 'maxplayers',
'value' => 2,
'message' => totranslate('Rebel vs Imperium Takeover Scenario is available for 2 players only.')
)
),
),
)
);
</pre>

Example of option that condition on ELO off

<pre>
$game_options = array(

100 => array(
'name' => totranslate('Learning Game (No Research)'),
'values' => array(

1 => array( 'name' => totranslate('Off'), 'tmdisplay' => totranslate('') ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Learning Game') ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1, // 1 if OFF

)
),
'notdisplayedmessage' => totranslate('Learning variant available only with ELO off')
),

);
</pre>

Example of condition that is only available for REALTIME game mode
<pre>
'displaycondition' => array(
// Note: do not display this option until these conditions are met - game speed is selected as realtime
array( 'type' => 'otheroption', 'id' => GAMESTATE_CLOCK_MODE, 'value' => array(0,1,2) )
),
</pre>

Example of using condition on your own option
<pre>
102 => array(
'name' => totranslate('Scenarios'),
'values' => array(
1 => array( 'name' => totranslate('Off'),
'nobeginner' => false ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Scenarios'),
'nobeginner' => true ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroptionisnot',
'id' => 100, // learning variant
'value' => 2, // 1 if OFF,2 is ON

)
),
'notdisplayedmessage' => totranslate('Scenarios variant is not available if Learning variant is chosen')
),
</pre>

Example of handling solo vs multiplayer options:

<pre>
$game_options = array(

100 => array(
'name' => totranslate('Board setup'),
'values' => array(
1 => array(
'name' => totranslate( 'Mirror setup' ),
'description' => totranslate( 'The starting player shuffles their 6 Farm Cards and randomly lays a card face up in each of the round spaces of their Fruit Island Board. The other players then lay their cards in exactly the same way, copying the order of the starting player.' ),
'tmdisplay' => totranslate( 'Mirror setup' ),
),
2 => array(
'name' => totranslate( 'Random setup' ),
'description' => totranslate( 'Instead of every player copying the same card configuration as the starting player, every player shuffles their Farm Cards and lays down the cards randomly on their Fruit Island Board.' ),
'tmdisplay' => totranslate( 'Random setup' ),
),
),
'displaycondition' => array(
// Note: only display for non-solo mode
array(
'type' => 'minplayers',
'value' => array (2, 3, 4),
),
),
),

102 => array(
'name' => totranslate('Solo difficulty'),
'values' => array(
0 => array(
'name' => totranslate( 'Banan-apprentice' ),
'description' => totranslate( 'Do not remove any seed before starting the game.' ),
'tmdisplay' => totranslate( 'Banan-apprentice' ),
),
1 => array(
'name' => totranslate( 'Pear to the Throne' ),
'description' => totranslate( 'Remove 1 seed before starting the game.' ),
'tmdisplay' => totranslate( 'Pear to the Throne' ),
)
),
'displaycondition' => array(
// Note: only display for solo mode
array(
'type' => 'maxplayers',
'value' => 1
),
),
),

);
</pre>

==== displaycondition vs startcondition ====

<code>displaycondition</code> should be used when an option should not be present in the list under certain conditions.

For example, displaying the option which is consistent with the player count.

* 2 player maps: A B C D
* 3 player maps: E F G H
* 4 player maps: I J K L

<code>startcondition</code> should be used when a specific combination of option values is invalid, but the option itself still makes sense to show.

For example:

* Player 1 faction: A, B, C, D, E, F, G
* Player 2 faction: A, B, C, D, E, F, G
* startcondition: both players can't be the same faction

These options should both be displayed at all times, but there are some invalid configurations.

==== gamestartonly ====

On the table configuration page, it won't let you select a combination which is invalid according to <code>startcondition</code>. Doing so will show a red warning, and will revert the option to the previous value. This means you could end up in a situation where you can't easily change between certain options (requiring you to set or unset options in a specific order).

The consequence of the <code>gamestartonly</code> flag is that the player _can_ select an invalid combination. However, when clicking "Start", an invalid combination will produce an error.

Probably the easiest way to see what the difference is is with an example.

With a _Clans of Caledonia_ table:
* set to training mode
* set player count to 1
* try setting "Clan Auction" to one of the "On" options
* try starting the game, there's an error! Ie. <code>"gamestartonly" => true</code>

Then, with a _Sushi Go Party!_ table:
* set number of players to 7
* try setting "Sushi Go! / Sushi Go Party!" to "Sushi Go!"
* you can't set the option! Ie. <code>"gamestartonly" => false</code>

In code:

<pre>
$game_options = array(
100 => array(
'name' => totranslate('Option name'),
'values' => array( ... ),
'startcondition' => array(
1 => array(
array(
'type' => 'maxplayers',
'value' => 2,
'message' => totranslate('This option is available for 2 players only.'),
'gamestartonly' => true, // true = check only on gamestart, false = don't allow player to even select this combination
)
),
),
),
);
</pre>

==== option level ====

<pre>
$game_options = array(
100 => array(
'name' => totranslate('Option name'),
'values' => array( ... ),
'level' => 'base'
)
);
</pre>

* ''base'' is the default value (you don't need to specify it).
* ''major'' denotes a major option, which will always be displayed on top, and with a specific UI.
* ''additional'' means this option will not be displayed by default, to unclutter the option panel.

About major options:
* a game can only have '''1 major option''', and of course, it must be a important game changer.
* the pictures will default to the standard Game Box, and can be set independently for each value, from the [[Game metadata manager]] (in the "Major Variants" section).
* the major option can have more than 2 values (there will then be an arrow to slide to the other values, carousel-like)

About additional options:
* please set each option that concerns small details in this category: advanced players will find this option anyway, and it will simplify the interface of the page of your game.

[[File:Option-levels.png|800px|Option levels]]

==== option display ====

An option can be displayed as a '''Checkbox''' instead of a selector.

This is the case for options which:
* have only '''2 values'''
* values are either (case insensitive):
** ''yes'' and ''no''
** ''on'' and ''off''
** ''enabled'' and ''disabled''

The "default" value still has to be specified, and can be "on" or "off" (it's actually just a difference in display).

[[File:Option-display.png|800px|Example of checkbox display]]

== User Preferences ==

User preferences is something cosmetic about the game interface which however can create user wars, so you can satisfy all users
by giving them individual preferences. You should use this only if it significantly improves the interface for a large proportion of users.
These preferences appear in the three-line hamburger menu in the top corner of the bga menu. "Display game logs" and Display tooltips" are baked-in by default, but you can extend this list as below.

[[File:century_preferences_menu.PNG|400px|The user preferences menu for the game Century]]

<blockquote>
''These preferences are a good place to put accessibility options - as Century did for its Colorblind Support.''
</blockquote>

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Colorblind Support'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'None' ), 'cssPref' => 'colorblind_off' ),
2 => array( 'name' => totranslate( 'Numbers' ), 'cssPref' => 'colorblind_on' ),
3 => array( 'name' => totranslate( 'Shapes' ), 'cssPref' => 'colorblind_shapes' )
),
'default' => 1
),
);
</pre>

There is two ways to check/apply this. In java Script

if (this.prefs[100].value == 2) ...

This checks if preferences 100 has selected value 2.

Second, if cssPref specified it will be applied to the '''<html>''' tag. So you can use different css styling for the preference. Note: it seems needed to set needReload to true for that class change to be effective.

As user you have to select them from the Gear menu when game is started. On studio only user0 will have it actually working (bug?).

The following are the parameters of preferences description array:
* '''name''' - '''mandatory'''. The name of the preference. Value will be automatically wrapped in totranslate if you don't.
* '''needReload''' - If set to true, the game interface will auto-reload after a change of the preference.
* '''values''' - '''mandatory'''. The array (map) of values with additional parameters per value.
** '''name''' - '''mandatory'''. String representation of the numeric value. Value will be automatically wrapped in totranslate if you don't.
** '''cssPref''' - CSS class to add to the '''<html>''' tag. Currently it is added or removed only after a reload (see needReload).
* '''default''' - Indicates the default value to use for this preference (optional, if not present the first value listed is the default).

=== Listening for preference changes ===

The BGA framework lacks any callback to notify your game when a user preference is changed (see [https://studio.boardgamearena.com/bug?id=36 proposal #36]), but you can create your own if you need to run some UI code in response to a preference change.

; In ggg.js
<pre>
setup: function (gamedatas) {
// your setup code here ...

this.initPreferencesObserver();
},

initPreferencesObserver: function () {
// Call onPreferenceChange() when any value changes
dojo.query('.preference_control').on('change', (e) => {
const match = e.target.id.match(/^preference_[cf]ontrol_(\d+)$/);
if (!match) {
return;
}
const pref = match[1];
const newValue = e.target.value;
this.prefs[pref].value = newValue;
this.onPreferenceChange(pref, newValue);
});
},

onPreferenceChange: function (prefId, prefValue) {
console.log("Preference changed", prefId, prefValue);
// your code here to handle the change
},
</pre>

=== Updating preference from code ===
The BGA framework lacks any method to update a user preference from the code (see [https://studio.boardgamearena.com/bug?id=36 proposal #36]), but you can create your own if you need to.

; In ggg.js
<pre>
updatePreference: function(prefId, newValue) {
// Select preference value in control:
dojo.query('#preference_control_' + prefId + ' > option[value="' + newValue
// Also select fontrol to fix a BGA framework bug:
+ '"], #preference_fontrol_' + prefId + ' > option[value="' + newValue
+ '"]').forEach((value) => dojo.attr(value, 'selected', true));
// Generate change event on control to trigger callbacks:
const newEvt = document.createEvent('HTMLEvents');
newEvt.initEvent('change', false, true);
$('preference_control_' + prefId).dispatchEvent(newEvt);
},
</pre>

=== Accessing User Preferences on the server ===
PHP has a variable called $this->player_preferences.
This contains a table of player preferences, ONLY accessible in setupNewGame().
You can use this to populate a table that you manage yourself.
You have to update the table when a player changes preference (and you have to hook up a listener and initiate an AJAX call out-of-turn).
Check the code of Agricola for details but this should work:

; In dbmodel.sql
<pre>
CREATE TABLE IF NOT EXISTS `user_preferences` (
`player_id` int(10) NOT NULL,
`pref_id` int(10) NOT NULL,
`pref_value` int(10) NOT NULL,
PRIMARY KEY (`player_id`, `pref_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

; In ggg.game.php
<pre>
protected function setupNewGame($players, $options = array())
{
// TODO: Save $this->player_preferences: key is player_id, value is array with pref_id as key and pref_value as value
}
</pre>

; In ggg.js

<pre>

// use code for initPreferencesObserver from above example

onPreferenceChange(prefId, prefValue) {
prefId = parseInt(prefId);
if (prefId === 101 /*TODO: You probably want to send only some preferences*/) {
// TODO: Code your own action in ggg.action.php and send it prefId and prefValue
// The on the server side you can save it all in the user_preferences
// table you created above.
}
},
</pre>

[[Category:Studio]]

Options and preferences: gameoptions.json, gamepreferences.json

2022-11-07T15:45:40Z

Draasill: /* option level */

{{Studio_Framework_Navigation}}

In this file, you can define your game options (i.e. game variants) and user preferences.

Note: If your game has no variants or preferences, you don't have to modify this file.

'''IMPORTANT:''' after you edited this file and syncronized to ftp folder you have to go to the control panel and press "Reload game options configuration" for your changes '''to take effect'''.

Make sure you understand difference between options and preferences:
* Game options - something usually in the rule book defined as "variant" (except for 2,3,X people - that is automatically handled - you can query it)
* User preferences - personal choices of each player only visible to that specific player - i.e. layout, either or not to prompt for action, either or not auto-opt in in some actions, etc

__TOC__

== Game Options ==

Game options are selected by the table creator and usually correspond to game variants, for example if the game includes expansions or certain special rules.

These variants are defined in gameoptions.inc.php as the $game_options variable:

$game_options = [ // exactly named that
// options start with 100
100 => [ /*option description array for option 100*/ ],
101 => [ /*option description array for option 101*/ ],
// etc
];

All options defined in this file should have a corresponding "game state label" with the same ID (see "initGameStateLabels" in yourgame.game.php)

self::initGameStateLabels ([
...
"my_game_variant" => 100,
]);

Numbers have to be exactly from 100 to 199 (there can be gaps).

That is how you access them during runtime:

public function isSecondVariant() {
return $this->getGameStateValue('my_game_variant') == 2;
}

Or this
$this->gamestate->table_globals[100]

The following are the parameters of option description array:
* '''name''' - '''mandatory'''. The name of the option visible for table creator. Value must be wrapped in totranslate function.
* '''values''' - '''mandatory'''. The array (map) of values with additional parameters per value.
** '''name''' - '''mandatory'''. String representation of the numeric value visible to table creator. Value must be wrapped in totranslate function.
** '''description''' - String description of this value to use when the name of the option is not self-explanatory. Displayed at the table under the option when this value is selected.
** '''tmdisplay''' - String representation of the option visible in the table description in the lobby. Usually if a variant values are On and Off (default), the tmdisplay would be same as description name when On, and nothing (empty string) when Off. ('''Warning''': due to some caching, a change in tmdisplay may not be effective immediately in the studio, even after forcing a reload of gameoptions.inc.php.) '''Pro Tip:''' You can use this as a pre-game communication by adding fake options that just do nothing in the game but make it easier to find other player wanted the same game configuration (see the crew deep sea for example).
** '''nobeginner''' - Set to true if not recommended for beginners
** '''firstgameonly''' - Set to true if this option is recommended only for the first game (discovery option)
** '''beta''' - Set to true to indicate that this option is in "beta" development stage (there will be a warning for players starting the game)
** '''alpha''' - Set to true to indicate that this option is in "alpha" development stage (there will be a warning, and starting the game will be allowed only in training mode except for the developer)
** '''premium''' - Option can be only used by premium members
* '''default''' - indicates the default value to use for this option (optional, if not present the first value listed is the default)
* '''displaycondition''' - checks the conditions before displaying the option for selection. All conditions must be true for the option to display. Supported condition types:
** ''minplayers'' condition ensures at least this many players (Note: if your game works with a disjoint interval of player counts, you can supply an array of valid counts instead of a single value)
** ''maxplayers'' conditions ensure at most this many players
** ''otheroption'' condition ensures another option is set to this given values.
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given values
* '''displayconditionoperand''' - can be 'and' (this is the default) or 'or'. Allows to change the behaviour to display the option if one of the conditions is true instead of all of them.
* '''startcondition''' - checks the conditions (on options VALUES) before starting the game. All conditions must be true for the game to start, otherwise players will get a red error message when attempting to begin the game. Supported condition types:
** ''minplayers'' condition ensures at least this many players (Note: if your game works with a disjoint interval of player counts, you can supply an array of valid counts instead of a single value)
** ''maxplayers'' conditions ensure at most this many players
** ''otheroption'' conditions ensure another option is set to this given values. That works the same as in '''displaycondition'''.
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given value. That works the same as in '''displaycondition'''.
*: For all these condition types, a ''gamestartonly'' boolean option can be added, if you have options that are exclusive. Setting this boolean to ''true'' will defer the evaluation of the startcondition to the game creation, instead of preventing the player to select options that are exclusive at all. See [[#gamestartonly|below]] for an example.
* '''notdisplayedmessage''' - if option is not suppose to be visible because of displaycondition but this is set, the text will be visible instead of combo drop down
* '''level''' - what kind of option it is: ''base'', ''major'', or ''additional''. See [[#option_level|below]] for more informations.

Common options for all tables (reserved range 200-299):
*201 (const GAMESTATE_RATING_MODE) - ELO OFF (aka Training mode),
*200 (const GAMESTATE_CLOCK_MODE) - game speed profile, array(0,1,2) - realtime (technically <10 realtime but you cannot define range in php), values >=10 - turn based (currently 10..21)

Example:
<pre>
$game_options = array(
100 => array(
'name' => totranslate('my game option'),
'values' => array(
// A simple value for this option:
1 => array(
'name' => totranslate('option 1')
),

// A simple value for this option.
// If this value is chosen, the value of "tmdisplay" is displayed in the game lobby
2 => array(
'name' => totranslate('option 2'),
'tmdisplay' => totranslate('option 2')
),

// Another value, with other options:
// beta=true => this option is in beta version right now.
// nobeginner=true => this option is not recommended for beginners
3 => array(
'name' => totranslate('option 3'),
'beta' => true,
'nobeginner' => true
),
),
'default' => 1
),

101 => array(
'name' => totranslate('Draft variant'),
'values' => array(
1 => array(
'name' => totranslate('No draft')
),
2 => array(
'name' => totranslate('Draft'),
'tmdisplay' => totranslate('Draft'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100, // Game specific option defined in the same array above
'value' => array(2, 3, 4)
),
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1 // 1 if OFF
)
),

'startcondition' => array(
1 => array(),
2 => array(
array(
'type' => 'maxplayers',
'value' => 3,
'message' => totranslate('Draft option is available for 3 players maximum.')
)
),
),
),

102 => array(
'name' => totranslate('Takeovers'),
'values' => array(
2 => array(
'name' => totranslate('No takeover')
),
1 => array(
'name' => totranslate('Allow takeovers'),
'tmdisplay' => totranslate('Takeovers'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array( // Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100,
'value' => array(3, 4)
)
),
'startcondition' => array(
2 => array(),
1 => array(
array(
'type' => 'maxplayers',
'value' => 2,
'message' => totranslate('Rebel vs Imperium Takeover Scenario is available for 2 players only.')
)
),
),
)
);
</pre>

Example of option that condition on ELO off

<pre>
$game_options = array(

100 => array(
'name' => totranslate('Learning Game (No Research)'),
'values' => array(

1 => array( 'name' => totranslate('Off'), 'tmdisplay' => totranslate('') ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Learning Game') ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1, // 1 if OFF

)
),
'notdisplayedmessage' => totranslate('Learning variant available only with ELO off')
),

);
</pre>

Example of condition that is only available for REALTIME game mode
<pre>
'displaycondition' => array(
// Note: do not display this option until these conditions are met - game speed is selected as realtime
array( 'type' => 'otheroption', 'id' => GAMESTATE_CLOCK_MODE, 'value' => array(0,1,2) )
),
</pre>

Example of using condition on your own option
<pre>
102 => array(
'name' => totranslate('Scenarios'),
'values' => array(
1 => array( 'name' => totranslate('Off'),
'nobeginner' => false ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Scenarios'),
'nobeginner' => true ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroptionisnot',
'id' => 100, // learning variant
'value' => 2, // 1 if OFF,2 is ON

)
),
'notdisplayedmessage' => totranslate('Scenarios variant is not available if Learning variant is chosen')
),
</pre>

Example of handling solo vs multiplayer options:

<pre>
$game_options = array(

100 => array(
'name' => totranslate('Board setup'),
'values' => array(
1 => array(
'name' => totranslate( 'Mirror setup' ),
'description' => totranslate( 'The starting player shuffles their 6 Farm Cards and randomly lays a card face up in each of the round spaces of their Fruit Island Board. The other players then lay their cards in exactly the same way, copying the order of the starting player.' ),
'tmdisplay' => totranslate( 'Mirror setup' ),
),
2 => array(
'name' => totranslate( 'Random setup' ),
'description' => totranslate( 'Instead of every player copying the same card configuration as the starting player, every player shuffles their Farm Cards and lays down the cards randomly on their Fruit Island Board.' ),
'tmdisplay' => totranslate( 'Random setup' ),
),
),
'displaycondition' => array(
// Note: only display for non-solo mode
array(
'type' => 'minplayers',
'value' => array (2, 3, 4),
),
),
),

102 => array(
'name' => totranslate('Solo difficulty'),
'values' => array(
0 => array(
'name' => totranslate( 'Banan-apprentice' ),
'description' => totranslate( 'Do not remove any seed before starting the game.' ),
'tmdisplay' => totranslate( 'Banan-apprentice' ),
),
1 => array(
'name' => totranslate( 'Pear to the Throne' ),
'description' => totranslate( 'Remove 1 seed before starting the game.' ),
'tmdisplay' => totranslate( 'Pear to the Throne' ),
)
),
'displaycondition' => array(
// Note: only display for solo mode
array(
'type' => 'maxplayers',
'value' => 1
),
),
),

);
</pre>

==== displaycondition vs startcondition ====

<code>displaycondition</code> should be used when an option should not be present in the list under certain conditions.

For example, displaying the option which is consistent with the player count.

* 2 player maps: A B C D
* 3 player maps: E F G H
* 4 player maps: I J K L

<code>startcondition</code> should be used when a specific combination of option values is invalid, but the option itself still makes sense to show.

For example:

* Player 1 faction: A, B, C, D, E, F, G
* Player 2 faction: A, B, C, D, E, F, G
* startcondition: both players can't be the same faction

These options should both be displayed at all times, but there are some invalid configurations.

==== gamestartonly ====

On the table configuration page, it won't let you select a combination which is invalid according to <code>startcondition</code>. Doing so will show a red warning, and will revert the option to the previous value. This means you could end up in a situation where you can't easily change between certain options (requiring you to set or unset options in a specific order).

The consequence of the <code>gamestartonly</code> flag is that the player _can_ select an invalid combination. However, when clicking "Start", an invalid combination will produce an error.

Probably the easiest way to see what the difference is is with an example.

With a _Clans of Caledonia_ table:
* set to training mode
* set player count to 1
* try setting "Clan Auction" to one of the "On" options
* try starting the game, there's an error! Ie. <code>"gamestartonly" => true</code>

Then, with a _Sushi Go Party!_ table:
* set number of players to 7
* try setting "Sushi Go! / Sushi Go Party!" to "Sushi Go!"
* you can't set the option! Ie. <code>"gamestartonly" => false</code>

In code:

<pre>
$game_options = array(
100 => array(
'name' => totranslate('Option name'),
'values' => array( ... ),
'startcondition' => array(
1 => array(
array(
'type' => 'maxplayers',
'value' => 2,
'message' => totranslate('This option is available for 2 players only.'),
'gamestartonly' => true, // true = check only on gamestart, false = don't allow player to even select this combination
)
),
),
),
);
</pre>

==== option level ====

<pre>
$game_options = array(
100 => array(
'name' => totranslate('Option name'),
'values' => array( ... ),
'level' => 'base'
)
);
</pre>

* ''base'' is the default value (you don't need to specify it).
* ''major'' denotes a major option, which will always be displayed on top, and with a specific UI.
* ''additional'' means this option will not be displayed by default, to unclutter the option panel.

About major options:
* a game can only have '''1 major option''', and of course, it must be a important game changer.
* the pictures will default to the standard Game Box, and can be set independently for each value, from the [[Game metadata manager]] (in the "Major Variants" section).
* the major option can have more than 2 values (there will then be an arrow to slide to the other values, carousel-like)

About additional options:
* please set each option that concerns small details in this category: advanced players will find this option anyway, and it will simplify the interface of the page of your game.

[[File:Option-levels.png|800px|Option levels]]

==== option display ====

An option can be displayed as a '''Checkbox''' instead of a selector.

This is the case for options which:
* have only '''2 values'''
* values are either (case insensitive):
** ''yes'' and ''no''
** ''on'' and ''off''
** ''enabled'' and ''disabled''

[[File:Option-display.png|800px|Example of checkbox display]]

== User Preferences ==

User preferences is something cosmetic about the game interface which however can create user wars, so you can satisfy all users
by giving them individual preferences. You should use this only if it significantly improves the interface for a large proportion of users.
These preferences appear in the three-line hamburger menu in the top corner of the bga menu. "Display game logs" and Display tooltips" are baked-in by default, but you can extend this list as below.

[[File:century_preferences_menu.PNG|400px|The user preferences menu for the game Century]]

<blockquote>
''These preferences are a good place to put accessibility options - as Century did for its Colorblind Support.''
</blockquote>

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Colorblind Support'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'None' ), 'cssPref' => 'colorblind_off' ),
2 => array( 'name' => totranslate( 'Numbers' ), 'cssPref' => 'colorblind_on' ),
3 => array( 'name' => totranslate( 'Shapes' ), 'cssPref' => 'colorblind_shapes' )
),
'default' => 1
),
);
</pre>

There is two ways to check/apply this. In java Script

if (this.prefs[100].value == 2) ...

This checks if preferences 100 has selected value 2.

Second, if cssPref specified it will be applied to the '''<html>''' tag. So you can use different css styling for the preference. Note: it seems needed to set needReload to true for that class change to be effective.

As user you have to select them from the Gear menu when game is started. On studio only user0 will have it actually working (bug?).

The following are the parameters of preferences description array:
* '''name''' - '''mandatory'''. The name of the preference. Value will be automatically wrapped in totranslate if you don't.
* '''needReload''' - If set to true, the game interface will auto-reload after a change of the preference.
* '''values''' - '''mandatory'''. The array (map) of values with additional parameters per value.
** '''name''' - '''mandatory'''. String representation of the numeric value. Value will be automatically wrapped in totranslate if you don't.
** '''cssPref''' - CSS class to add to the '''<html>''' tag. Currently it is added or removed only after a reload (see needReload).
* '''default''' - Indicates the default value to use for this preference (optional, if not present the first value listed is the default).

=== Listening for preference changes ===

The BGA framework lacks any callback to notify your game when a user preference is changed (see [https://studio.boardgamearena.com/bug?id=36 proposal #36]), but you can create your own if you need to run some UI code in response to a preference change.

; In ggg.js
<pre>
setup: function (gamedatas) {
// your setup code here ...

this.initPreferencesObserver();
},

initPreferencesObserver: function () {
// Call onPreferenceChange() when any value changes
dojo.query('.preference_control').on('change', (e) => {
const match = e.target.id.match(/^preference_[cf]ontrol_(\d+)$/);
if (!match) {
return;
}
const pref = match[1];
const newValue = e.target.value;
this.prefs[pref].value = newValue;
this.onPreferenceChange(pref, newValue);
});
},

onPreferenceChange: function (prefId, prefValue) {
console.log("Preference changed", prefId, prefValue);
// your code here to handle the change
},
</pre>

=== Updating preference from code ===
The BGA framework lacks any method to update a user preference from the code (see [https://studio.boardgamearena.com/bug?id=36 proposal #36]), but you can create your own if you need to.

; In ggg.js
<pre>
updatePreference: function(prefId, newValue) {
// Select preference value in control:
dojo.query('#preference_control_' + prefId + ' > option[value="' + newValue
// Also select fontrol to fix a BGA framework bug:
+ '"], #preference_fontrol_' + prefId + ' > option[value="' + newValue
+ '"]').forEach((value) => dojo.attr(value, 'selected', true));
// Generate change event on control to trigger callbacks:
const newEvt = document.createEvent('HTMLEvents');
newEvt.initEvent('change', false, true);
$('preference_control_' + prefId).dispatchEvent(newEvt);
},
</pre>

=== Accessing User Preferences on the server ===
PHP has a variable called $this->player_preferences.
This contains a table of player preferences, ONLY accessible in setupNewGame().
You can use this to populate a table that you manage yourself.
You have to update the table when a player changes preference (and you have to hook up a listener and initiate an AJAX call out-of-turn).
Check the code of Agricola for details but this should work:

; In dbmodel.sql
<pre>
CREATE TABLE IF NOT EXISTS `user_preferences` (
`player_id` int(10) NOT NULL,
`pref_id` int(10) NOT NULL,
`pref_value` int(10) NOT NULL,
PRIMARY KEY (`player_id`, `pref_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

; In ggg.game.php
<pre>
protected function setupNewGame($players, $options = array())
{
// TODO: Save $this->player_preferences: key is player_id, value is array with pref_id as key and pref_value as value
}
</pre>

; In ggg.js

<pre>

// use code for initPreferencesObserver from above example

onPreferenceChange(prefId, prefValue) {
prefId = parseInt(prefId);
if (prefId === 101 /*TODO: You probably want to send only some preferences*/) {
// TODO: Code your own action in ggg.action.php and send it prefId and prefValue
// The on the server side you can save it all in the user_preferences
// table you created above.
}
},
</pre>

[[Category:Studio]]

Options and preferences: gameoptions.json, gamepreferences.json

2022-11-07T15:43:28Z

Draasill: /* option level */

{{Studio_Framework_Navigation}}

In this file, you can define your game options (i.e. game variants) and user preferences.

Note: If your game has no variants or preferences, you don't have to modify this file.

'''IMPORTANT:''' after you edited this file and syncronized to ftp folder you have to go to the control panel and press "Reload game options configuration" for your changes '''to take effect'''.

Make sure you understand difference between options and preferences:
* Game options - something usually in the rule book defined as "variant" (except for 2,3,X people - that is automatically handled - you can query it)
* User preferences - personal choices of each player only visible to that specific player - i.e. layout, either or not to prompt for action, either or not auto-opt in in some actions, etc

__TOC__

== Game Options ==

Game options are selected by the table creator and usually correspond to game variants, for example if the game includes expansions or certain special rules.

These variants are defined in gameoptions.inc.php as the $game_options variable:

$game_options = [ // exactly named that
// options start with 100
100 => [ /*option description array for option 100*/ ],
101 => [ /*option description array for option 101*/ ],
// etc
];

All options defined in this file should have a corresponding "game state label" with the same ID (see "initGameStateLabels" in yourgame.game.php)

self::initGameStateLabels ([
...
"my_game_variant" => 100,
]);

Numbers have to be exactly from 100 to 199 (there can be gaps).

That is how you access them during runtime:

public function isSecondVariant() {
return $this->getGameStateValue('my_game_variant') == 2;
}

Or this
$this->gamestate->table_globals[100]

The following are the parameters of option description array:
* '''name''' - '''mandatory'''. The name of the option visible for table creator. Value must be wrapped in totranslate function.
* '''values''' - '''mandatory'''. The array (map) of values with additional parameters per value.
** '''name''' - '''mandatory'''. String representation of the numeric value visible to table creator. Value must be wrapped in totranslate function.
** '''description''' - String description of this value to use when the name of the option is not self-explanatory. Displayed at the table under the option when this value is selected.
** '''tmdisplay''' - String representation of the option visible in the table description in the lobby. Usually if a variant values are On and Off (default), the tmdisplay would be same as description name when On, and nothing (empty string) when Off. ('''Warning''': due to some caching, a change in tmdisplay may not be effective immediately in the studio, even after forcing a reload of gameoptions.inc.php.) '''Pro Tip:''' You can use this as a pre-game communication by adding fake options that just do nothing in the game but make it easier to find other player wanted the same game configuration (see the crew deep sea for example).
** '''nobeginner''' - Set to true if not recommended for beginners
** '''firstgameonly''' - Set to true if this option is recommended only for the first game (discovery option)
** '''beta''' - Set to true to indicate that this option is in "beta" development stage (there will be a warning for players starting the game)
** '''alpha''' - Set to true to indicate that this option is in "alpha" development stage (there will be a warning, and starting the game will be allowed only in training mode except for the developer)
** '''premium''' - Option can be only used by premium members
* '''default''' - indicates the default value to use for this option (optional, if not present the first value listed is the default)
* '''displaycondition''' - checks the conditions before displaying the option for selection. All conditions must be true for the option to display. Supported condition types:
** ''minplayers'' condition ensures at least this many players (Note: if your game works with a disjoint interval of player counts, you can supply an array of valid counts instead of a single value)
** ''maxplayers'' conditions ensure at most this many players
** ''otheroption'' condition ensures another option is set to this given values.
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given values
* '''displayconditionoperand''' - can be 'and' (this is the default) or 'or'. Allows to change the behaviour to display the option if one of the conditions is true instead of all of them.
* '''startcondition''' - checks the conditions (on options VALUES) before starting the game. All conditions must be true for the game to start, otherwise players will get a red error message when attempting to begin the game. Supported condition types:
** ''minplayers'' condition ensures at least this many players (Note: if your game works with a disjoint interval of player counts, you can supply an array of valid counts instead of a single value)
** ''maxplayers'' conditions ensure at most this many players
** ''otheroption'' conditions ensure another option is set to this given values. That works the same as in '''displaycondition'''.
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given value. That works the same as in '''displaycondition'''.
*: For all these condition types, a ''gamestartonly'' boolean option can be added, if you have options that are exclusive. Setting this boolean to ''true'' will defer the evaluation of the startcondition to the game creation, instead of preventing the player to select options that are exclusive at all. See [[#gamestartonly|below]] for an example.
* '''notdisplayedmessage''' - if option is not suppose to be visible because of displaycondition but this is set, the text will be visible instead of combo drop down
* '''level''' - what kind of option it is: ''base'', ''major'', or ''additional''. See [[#option_level|below]] for more informations.

Common options for all tables (reserved range 200-299):
*201 (const GAMESTATE_RATING_MODE) - ELO OFF (aka Training mode),
*200 (const GAMESTATE_CLOCK_MODE) - game speed profile, array(0,1,2) - realtime (technically <10 realtime but you cannot define range in php), values >=10 - turn based (currently 10..21)

Example:
<pre>
$game_options = array(
100 => array(
'name' => totranslate('my game option'),
'values' => array(
// A simple value for this option:
1 => array(
'name' => totranslate('option 1')
),

// A simple value for this option.
// If this value is chosen, the value of "tmdisplay" is displayed in the game lobby
2 => array(
'name' => totranslate('option 2'),
'tmdisplay' => totranslate('option 2')
),

// Another value, with other options:
// beta=true => this option is in beta version right now.
// nobeginner=true => this option is not recommended for beginners
3 => array(
'name' => totranslate('option 3'),
'beta' => true,
'nobeginner' => true
),
),
'default' => 1
),

101 => array(
'name' => totranslate('Draft variant'),
'values' => array(
1 => array(
'name' => totranslate('No draft')
),
2 => array(
'name' => totranslate('Draft'),
'tmdisplay' => totranslate('Draft'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100, // Game specific option defined in the same array above
'value' => array(2, 3, 4)
),
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1 // 1 if OFF
)
),

'startcondition' => array(
1 => array(),
2 => array(
array(
'type' => 'maxplayers',
'value' => 3,
'message' => totranslate('Draft option is available for 3 players maximum.')
)
),
),
),

102 => array(
'name' => totranslate('Takeovers'),
'values' => array(
2 => array(
'name' => totranslate('No takeover')
),
1 => array(
'name' => totranslate('Allow takeovers'),
'tmdisplay' => totranslate('Takeovers'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array( // Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100,
'value' => array(3, 4)
)
),
'startcondition' => array(
2 => array(),
1 => array(
array(
'type' => 'maxplayers',
'value' => 2,
'message' => totranslate('Rebel vs Imperium Takeover Scenario is available for 2 players only.')
)
),
),
)
);
</pre>

Example of option that condition on ELO off

<pre>
$game_options = array(

100 => array(
'name' => totranslate('Learning Game (No Research)'),
'values' => array(

1 => array( 'name' => totranslate('Off'), 'tmdisplay' => totranslate('') ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Learning Game') ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1, // 1 if OFF

)
),
'notdisplayedmessage' => totranslate('Learning variant available only with ELO off')
),

);
</pre>

Example of condition that is only available for REALTIME game mode
<pre>
'displaycondition' => array(
// Note: do not display this option until these conditions are met - game speed is selected as realtime
array( 'type' => 'otheroption', 'id' => GAMESTATE_CLOCK_MODE, 'value' => array(0,1,2) )
),
</pre>

Example of using condition on your own option
<pre>
102 => array(
'name' => totranslate('Scenarios'),
'values' => array(
1 => array( 'name' => totranslate('Off'),
'nobeginner' => false ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Scenarios'),
'nobeginner' => true ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroptionisnot',
'id' => 100, // learning variant
'value' => 2, // 1 if OFF,2 is ON

)
),
'notdisplayedmessage' => totranslate('Scenarios variant is not available if Learning variant is chosen')
),
</pre>

Example of handling solo vs multiplayer options:

<pre>
$game_options = array(

100 => array(
'name' => totranslate('Board setup'),
'values' => array(
1 => array(
'name' => totranslate( 'Mirror setup' ),
'description' => totranslate( 'The starting player shuffles their 6 Farm Cards and randomly lays a card face up in each of the round spaces of their Fruit Island Board. The other players then lay their cards in exactly the same way, copying the order of the starting player.' ),
'tmdisplay' => totranslate( 'Mirror setup' ),
),
2 => array(
'name' => totranslate( 'Random setup' ),
'description' => totranslate( 'Instead of every player copying the same card configuration as the starting player, every player shuffles their Farm Cards and lays down the cards randomly on their Fruit Island Board.' ),
'tmdisplay' => totranslate( 'Random setup' ),
),
),
'displaycondition' => array(
// Note: only display for non-solo mode
array(
'type' => 'minplayers',
'value' => array (2, 3, 4),
),
),
),

102 => array(
'name' => totranslate('Solo difficulty'),
'values' => array(
0 => array(
'name' => totranslate( 'Banan-apprentice' ),
'description' => totranslate( 'Do not remove any seed before starting the game.' ),
'tmdisplay' => totranslate( 'Banan-apprentice' ),
),
1 => array(
'name' => totranslate( 'Pear to the Throne' ),
'description' => totranslate( 'Remove 1 seed before starting the game.' ),
'tmdisplay' => totranslate( 'Pear to the Throne' ),
)
),
'displaycondition' => array(
// Note: only display for solo mode
array(
'type' => 'maxplayers',
'value' => 1
),
),
),

);
</pre>

==== displaycondition vs startcondition ====

<code>displaycondition</code> should be used when an option should not be present in the list under certain conditions.

For example, displaying the option which is consistent with the player count.

* 2 player maps: A B C D
* 3 player maps: E F G H
* 4 player maps: I J K L

<code>startcondition</code> should be used when a specific combination of option values is invalid, but the option itself still makes sense to show.

For example:

* Player 1 faction: A, B, C, D, E, F, G
* Player 2 faction: A, B, C, D, E, F, G
* startcondition: both players can't be the same faction

These options should both be displayed at all times, but there are some invalid configurations.

==== gamestartonly ====

On the table configuration page, it won't let you select a combination which is invalid according to <code>startcondition</code>. Doing so will show a red warning, and will revert the option to the previous value. This means you could end up in a situation where you can't easily change between certain options (requiring you to set or unset options in a specific order).

The consequence of the <code>gamestartonly</code> flag is that the player _can_ select an invalid combination. However, when clicking "Start", an invalid combination will produce an error.

Probably the easiest way to see what the difference is is with an example.

With a _Clans of Caledonia_ table:
* set to training mode
* set player count to 1
* try setting "Clan Auction" to one of the "On" options
* try starting the game, there's an error! Ie. <code>"gamestartonly" => true</code>

Then, with a _Sushi Go Party!_ table:
* set number of players to 7
* try setting "Sushi Go! / Sushi Go Party!" to "Sushi Go!"
* you can't set the option! Ie. <code>"gamestartonly" => false</code>

In code:

<pre>
$game_options = array(
100 => array(
'name' => totranslate('Option name'),
'values' => array( ... ),
'startcondition' => array(
1 => array(
array(
'type' => 'maxplayers',
'value' => 2,
'message' => totranslate('This option is available for 2 players only.'),
'gamestartonly' => true, // true = check only on gamestart, false = don't allow player to even select this combination
)
),
),
),
);
</pre>

==== option level ====

<pre>
$game_options = array(
100 => array(
'name' => totranslate('Option name'),
'values' => array( ... ),
'level' => 'base'
)
);
</pre>

* ''base'' is the default value (you don't need to specify it).
* ''major'' denotes a major option, which will always be displayed on top, and with a specific UI.
* ''additional'' means this option will not be displayed by default, to unclutter the option panel.

About major options:
* a game can only have '''1 major option''', and of course, it must be a important game changer.
* the pictures will default to the standard Game Box, and can be set independently for each option, from the [[Game metadata manager]] (in the "Major Variants" section).

About additional options:
* please set each option that concerns small details in this category: advanced players will find this option anyway, and it will simplify the interface of the page of your game.

[[File:Option-levels.png|800px|Option levels]]

==== option display ====

An option can be displayed as a '''Checkbox''' instead of a selector.

This is the case for options which:
* have only '''2 values'''
* values are either (case insensitive):
** ''yes'' and ''no''
** ''on'' and ''off''
** ''enabled'' and ''disabled''

[[File:Option-display.png|800px|Example of checkbox display]]

== User Preferences ==

User preferences is something cosmetic about the game interface which however can create user wars, so you can satisfy all users
by giving them individual preferences. You should use this only if it significantly improves the interface for a large proportion of users.
These preferences appear in the three-line hamburger menu in the top corner of the bga menu. "Display game logs" and Display tooltips" are baked-in by default, but you can extend this list as below.

[[File:century_preferences_menu.PNG|400px|The user preferences menu for the game Century]]

<blockquote>
''These preferences are a good place to put accessibility options - as Century did for its Colorblind Support.''
</blockquote>

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Colorblind Support'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'None' ), 'cssPref' => 'colorblind_off' ),
2 => array( 'name' => totranslate( 'Numbers' ), 'cssPref' => 'colorblind_on' ),
3 => array( 'name' => totranslate( 'Shapes' ), 'cssPref' => 'colorblind_shapes' )
),
'default' => 1
),
);
</pre>

There is two ways to check/apply this. In java Script

if (this.prefs[100].value == 2) ...

This checks if preferences 100 has selected value 2.

Second, if cssPref specified it will be applied to the '''<html>''' tag. So you can use different css styling for the preference. Note: it seems needed to set needReload to true for that class change to be effective.

As user you have to select them from the Gear menu when game is started. On studio only user0 will have it actually working (bug?).

The following are the parameters of preferences description array:
* '''name''' - '''mandatory'''. The name of the preference. Value will be automatically wrapped in totranslate if you don't.
* '''needReload''' - If set to true, the game interface will auto-reload after a change of the preference.
* '''values''' - '''mandatory'''. The array (map) of values with additional parameters per value.
** '''name''' - '''mandatory'''. String representation of the numeric value. Value will be automatically wrapped in totranslate if you don't.
** '''cssPref''' - CSS class to add to the '''<html>''' tag. Currently it is added or removed only after a reload (see needReload).
* '''default''' - Indicates the default value to use for this preference (optional, if not present the first value listed is the default).

=== Listening for preference changes ===

The BGA framework lacks any callback to notify your game when a user preference is changed (see [https://studio.boardgamearena.com/bug?id=36 proposal #36]), but you can create your own if you need to run some UI code in response to a preference change.

; In ggg.js
<pre>
setup: function (gamedatas) {
// your setup code here ...

this.initPreferencesObserver();
},

initPreferencesObserver: function () {
// Call onPreferenceChange() when any value changes
dojo.query('.preference_control').on('change', (e) => {
const match = e.target.id.match(/^preference_[cf]ontrol_(\d+)$/);
if (!match) {
return;
}
const pref = match[1];
const newValue = e.target.value;
this.prefs[pref].value = newValue;
this.onPreferenceChange(pref, newValue);
});
},

onPreferenceChange: function (prefId, prefValue) {
console.log("Preference changed", prefId, prefValue);
// your code here to handle the change
},
</pre>

=== Updating preference from code ===
The BGA framework lacks any method to update a user preference from the code (see [https://studio.boardgamearena.com/bug?id=36 proposal #36]), but you can create your own if you need to.

; In ggg.js
<pre>
updatePreference: function(prefId, newValue) {
// Select preference value in control:
dojo.query('#preference_control_' + prefId + ' > option[value="' + newValue
// Also select fontrol to fix a BGA framework bug:
+ '"], #preference_fontrol_' + prefId + ' > option[value="' + newValue
+ '"]').forEach((value) => dojo.attr(value, 'selected', true));
// Generate change event on control to trigger callbacks:
const newEvt = document.createEvent('HTMLEvents');
newEvt.initEvent('change', false, true);
$('preference_control_' + prefId).dispatchEvent(newEvt);
},
</pre>

=== Accessing User Preferences on the server ===
PHP has a variable called $this->player_preferences.
This contains a table of player preferences, ONLY accessible in setupNewGame().
You can use this to populate a table that you manage yourself.
You have to update the table when a player changes preference (and you have to hook up a listener and initiate an AJAX call out-of-turn).
Check the code of Agricola for details but this should work:

; In dbmodel.sql
<pre>
CREATE TABLE IF NOT EXISTS `user_preferences` (
`player_id` int(10) NOT NULL,
`pref_id` int(10) NOT NULL,
`pref_value` int(10) NOT NULL,
PRIMARY KEY (`player_id`, `pref_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

; In ggg.game.php
<pre>
protected function setupNewGame($players, $options = array())
{
// TODO: Save $this->player_preferences: key is player_id, value is array with pref_id as key and pref_value as value
}
</pre>

; In ggg.js

<pre>

// use code for initPreferencesObserver from above example

onPreferenceChange(prefId, prefValue) {
prefId = parseInt(prefId);
if (prefId === 101 /*TODO: You probably want to send only some preferences*/) {
// TODO: Code your own action in ggg.action.php and send it prefId and prefValue
// The on the server side you can save it all in the user_preferences
// table you created above.
}
},
</pre>

[[Category:Studio]]

Options and preferences: gameoptions.json, gamepreferences.json

2022-11-07T15:34:38Z

Draasill: /* option level */

{{Studio_Framework_Navigation}}

In this file, you can define your game options (i.e. game variants) and user preferences.

Note: If your game has no variants or preferences, you don't have to modify this file.

'''IMPORTANT:''' after you edited this file and syncronized to ftp folder you have to go to the control panel and press "Reload game options configuration" for your changes '''to take effect'''.

Make sure you understand difference between options and preferences:
* Game options - something usually in the rule book defined as "variant" (except for 2,3,X people - that is automatically handled - you can query it)
* User preferences - personal choices of each player only visible to that specific player - i.e. layout, either or not to prompt for action, either or not auto-opt in in some actions, etc

__TOC__

== Game Options ==

Game options are selected by the table creator and usually correspond to game variants, for example if the game includes expansions or certain special rules.

These variants are defined in gameoptions.inc.php as the $game_options variable:

$game_options = [ // exactly named that
// options start with 100
100 => [ /*option description array for option 100*/ ],
101 => [ /*option description array for option 101*/ ],
// etc
];

All options defined in this file should have a corresponding "game state label" with the same ID (see "initGameStateLabels" in yourgame.game.php)

self::initGameStateLabels ([
...
"my_game_variant" => 100,
]);

Numbers have to be exactly from 100 to 199 (there can be gaps).

That is how you access them during runtime:

public function isSecondVariant() {
return $this->getGameStateValue('my_game_variant') == 2;
}

Or this
$this->gamestate->table_globals[100]

The following are the parameters of option description array:
* '''name''' - '''mandatory'''. The name of the option visible for table creator. Value must be wrapped in totranslate function.
* '''values''' - '''mandatory'''. The array (map) of values with additional parameters per value.
** '''name''' - '''mandatory'''. String representation of the numeric value visible to table creator. Value must be wrapped in totranslate function.
** '''description''' - String description of this value to use when the name of the option is not self-explanatory. Displayed at the table under the option when this value is selected.
** '''tmdisplay''' - String representation of the option visible in the table description in the lobby. Usually if a variant values are On and Off (default), the tmdisplay would be same as description name when On, and nothing (empty string) when Off. ('''Warning''': due to some caching, a change in tmdisplay may not be effective immediately in the studio, even after forcing a reload of gameoptions.inc.php.) '''Pro Tip:''' You can use this as a pre-game communication by adding fake options that just do nothing in the game but make it easier to find other player wanted the same game configuration (see the crew deep sea for example).
** '''nobeginner''' - Set to true if not recommended for beginners
** '''firstgameonly''' - Set to true if this option is recommended only for the first game (discovery option)
** '''beta''' - Set to true to indicate that this option is in "beta" development stage (there will be a warning for players starting the game)
** '''alpha''' - Set to true to indicate that this option is in "alpha" development stage (there will be a warning, and starting the game will be allowed only in training mode except for the developer)
** '''premium''' - Option can be only used by premium members
* '''default''' - indicates the default value to use for this option (optional, if not present the first value listed is the default)
* '''displaycondition''' - checks the conditions before displaying the option for selection. All conditions must be true for the option to display. Supported condition types:
** ''minplayers'' condition ensures at least this many players (Note: if your game works with a disjoint interval of player counts, you can supply an array of valid counts instead of a single value)
** ''maxplayers'' conditions ensure at most this many players
** ''otheroption'' condition ensures another option is set to this given values.
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given values
* '''displayconditionoperand''' - can be 'and' (this is the default) or 'or'. Allows to change the behaviour to display the option if one of the conditions is true instead of all of them.
* '''startcondition''' - checks the conditions (on options VALUES) before starting the game. All conditions must be true for the game to start, otherwise players will get a red error message when attempting to begin the game. Supported condition types:
** ''minplayers'' condition ensures at least this many players (Note: if your game works with a disjoint interval of player counts, you can supply an array of valid counts instead of a single value)
** ''maxplayers'' conditions ensure at most this many players
** ''otheroption'' conditions ensure another option is set to this given values. That works the same as in '''displaycondition'''.
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given value. That works the same as in '''displaycondition'''.
*: For all these condition types, a ''gamestartonly'' boolean option can be added, if you have options that are exclusive. Setting this boolean to ''true'' will defer the evaluation of the startcondition to the game creation, instead of preventing the player to select options that are exclusive at all. See [[#gamestartonly|below]] for an example.
* '''notdisplayedmessage''' - if option is not suppose to be visible because of displaycondition but this is set, the text will be visible instead of combo drop down
* '''level''' - what kind of option it is: ''base'', ''major'', or ''additional''. See [[#option_level|below]] for more informations.

Common options for all tables (reserved range 200-299):
*201 (const GAMESTATE_RATING_MODE) - ELO OFF (aka Training mode),
*200 (const GAMESTATE_CLOCK_MODE) - game speed profile, array(0,1,2) - realtime (technically <10 realtime but you cannot define range in php), values >=10 - turn based (currently 10..21)

Example:
<pre>
$game_options = array(
100 => array(
'name' => totranslate('my game option'),
'values' => array(
// A simple value for this option:
1 => array(
'name' => totranslate('option 1')
),

// A simple value for this option.
// If this value is chosen, the value of "tmdisplay" is displayed in the game lobby
2 => array(
'name' => totranslate('option 2'),
'tmdisplay' => totranslate('option 2')
),

// Another value, with other options:
// beta=true => this option is in beta version right now.
// nobeginner=true => this option is not recommended for beginners
3 => array(
'name' => totranslate('option 3'),
'beta' => true,
'nobeginner' => true
),
),
'default' => 1
),

101 => array(
'name' => totranslate('Draft variant'),
'values' => array(
1 => array(
'name' => totranslate('No draft')
),
2 => array(
'name' => totranslate('Draft'),
'tmdisplay' => totranslate('Draft'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100, // Game specific option defined in the same array above
'value' => array(2, 3, 4)
),
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1 // 1 if OFF
)
),

'startcondition' => array(
1 => array(),
2 => array(
array(
'type' => 'maxplayers',
'value' => 3,
'message' => totranslate('Draft option is available for 3 players maximum.')
)
),
),
),

102 => array(
'name' => totranslate('Takeovers'),
'values' => array(
2 => array(
'name' => totranslate('No takeover')
),
1 => array(
'name' => totranslate('Allow takeovers'),
'tmdisplay' => totranslate('Takeovers'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array( // Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100,
'value' => array(3, 4)
)
),
'startcondition' => array(
2 => array(),
1 => array(
array(
'type' => 'maxplayers',
'value' => 2,
'message' => totranslate('Rebel vs Imperium Takeover Scenario is available for 2 players only.')
)
),
),
)
);
</pre>

Example of option that condition on ELO off

<pre>
$game_options = array(

100 => array(
'name' => totranslate('Learning Game (No Research)'),
'values' => array(

1 => array( 'name' => totranslate('Off'), 'tmdisplay' => totranslate('') ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Learning Game') ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1, // 1 if OFF

)
),
'notdisplayedmessage' => totranslate('Learning variant available only with ELO off')
),

);
</pre>

Example of condition that is only available for REALTIME game mode
<pre>
'displaycondition' => array(
// Note: do not display this option until these conditions are met - game speed is selected as realtime
array( 'type' => 'otheroption', 'id' => GAMESTATE_CLOCK_MODE, 'value' => array(0,1,2) )
),
</pre>

Example of using condition on your own option
<pre>
102 => array(
'name' => totranslate('Scenarios'),
'values' => array(
1 => array( 'name' => totranslate('Off'),
'nobeginner' => false ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Scenarios'),
'nobeginner' => true ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroptionisnot',
'id' => 100, // learning variant
'value' => 2, // 1 if OFF,2 is ON

)
),
'notdisplayedmessage' => totranslate('Scenarios variant is not available if Learning variant is chosen')
),
</pre>

Example of handling solo vs multiplayer options:

<pre>
$game_options = array(

100 => array(
'name' => totranslate('Board setup'),
'values' => array(
1 => array(
'name' => totranslate( 'Mirror setup' ),
'description' => totranslate( 'The starting player shuffles their 6 Farm Cards and randomly lays a card face up in each of the round spaces of their Fruit Island Board. The other players then lay their cards in exactly the same way, copying the order of the starting player.' ),
'tmdisplay' => totranslate( 'Mirror setup' ),
),
2 => array(
'name' => totranslate( 'Random setup' ),
'description' => totranslate( 'Instead of every player copying the same card configuration as the starting player, every player shuffles their Farm Cards and lays down the cards randomly on their Fruit Island Board.' ),
'tmdisplay' => totranslate( 'Random setup' ),
),
),
'displaycondition' => array(
// Note: only display for non-solo mode
array(
'type' => 'minplayers',
'value' => array (2, 3, 4),
),
),
),

102 => array(
'name' => totranslate('Solo difficulty'),
'values' => array(
0 => array(
'name' => totranslate( 'Banan-apprentice' ),
'description' => totranslate( 'Do not remove any seed before starting the game.' ),
'tmdisplay' => totranslate( 'Banan-apprentice' ),
),
1 => array(
'name' => totranslate( 'Pear to the Throne' ),
'description' => totranslate( 'Remove 1 seed before starting the game.' ),
'tmdisplay' => totranslate( 'Pear to the Throne' ),
)
),
'displaycondition' => array(
// Note: only display for solo mode
array(
'type' => 'maxplayers',
'value' => 1
),
),
),

);
</pre>

==== displaycondition vs startcondition ====

<code>displaycondition</code> should be used when an option should not be present in the list under certain conditions.

For example, displaying the option which is consistent with the player count.

* 2 player maps: A B C D
* 3 player maps: E F G H
* 4 player maps: I J K L

<code>startcondition</code> should be used when a specific combination of option values is invalid, but the option itself still makes sense to show.

For example:

* Player 1 faction: A, B, C, D, E, F, G
* Player 2 faction: A, B, C, D, E, F, G
* startcondition: both players can't be the same faction

These options should both be displayed at all times, but there are some invalid configurations.

==== gamestartonly ====

On the table configuration page, it won't let you select a combination which is invalid according to <code>startcondition</code>. Doing so will show a red warning, and will revert the option to the previous value. This means you could end up in a situation where you can't easily change between certain options (requiring you to set or unset options in a specific order).

The consequence of the <code>gamestartonly</code> flag is that the player _can_ select an invalid combination. However, when clicking "Start", an invalid combination will produce an error.

Probably the easiest way to see what the difference is is with an example.

With a _Clans of Caledonia_ table:
* set to training mode
* set player count to 1
* try setting "Clan Auction" to one of the "On" options
* try starting the game, there's an error! Ie. <code>"gamestartonly" => true</code>

Then, with a _Sushi Go Party!_ table:
* set number of players to 7
* try setting "Sushi Go! / Sushi Go Party!" to "Sushi Go!"
* you can't set the option! Ie. <code>"gamestartonly" => false</code>

In code:

<pre>
$game_options = array(
100 => array(
'name' => totranslate('Option name'),
'values' => array( ... ),
'startcondition' => array(
1 => array(
array(
'type' => 'maxplayers',
'value' => 2,
'message' => totranslate('This option is available for 2 players only.'),
'gamestartonly' => true, // true = check only on gamestart, false = don't allow player to even select this combination
)
),
),
),
);
</pre>

==== option level ====

<pre>
$game_options = array(
100 => array(
'name' => totranslate('Option name'),
'values' => array( ... ),
'level' => 'base'
)
);
</pre>

* ''base'' is the default value (you don't need to specify it).
* ''major'' denotes a major option, which will always be displayed on top, and with a specific UI.
* ''additional'' means this option will not be displayed by default, to unclutter the option panel.

About major options:
* a game can only have '''1 major option''', and of course, it must be a important game changer.
* the pictures will default to the standard Game Box, and can be set independently for each option, from the [[Game metadata manager]] (in the "Major Variants" section).

[[File:Option-levels.png|800px|Option levels]]

==== option display ====

An option can be displayed as a '''Checkbox''' instead of a selector.

This is the case for options which:
* have only '''2 values'''
* values are either (case insensitive):
** ''yes'' and ''no''
** ''on'' and ''off''
** ''enabled'' and ''disabled''

[[File:Option-display.png|800px|Example of checkbox display]]

== User Preferences ==

User preferences is something cosmetic about the game interface which however can create user wars, so you can satisfy all users
by giving them individual preferences. You should use this only if it significantly improves the interface for a large proportion of users.
These preferences appear in the three-line hamburger menu in the top corner of the bga menu. "Display game logs" and Display tooltips" are baked-in by default, but you can extend this list as below.

[[File:century_preferences_menu.PNG|400px|The user preferences menu for the game Century]]

<blockquote>
''These preferences are a good place to put accessibility options - as Century did for its Colorblind Support.''
</blockquote>

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Colorblind Support'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'None' ), 'cssPref' => 'colorblind_off' ),
2 => array( 'name' => totranslate( 'Numbers' ), 'cssPref' => 'colorblind_on' ),
3 => array( 'name' => totranslate( 'Shapes' ), 'cssPref' => 'colorblind_shapes' )
),
'default' => 1
),
);
</pre>

There is two ways to check/apply this. In java Script

if (this.prefs[100].value == 2) ...

This checks if preferences 100 has selected value 2.

Second, if cssPref specified it will be applied to the '''<html>''' tag. So you can use different css styling for the preference. Note: it seems needed to set needReload to true for that class change to be effective.

As user you have to select them from the Gear menu when game is started. On studio only user0 will have it actually working (bug?).

The following are the parameters of preferences description array:
* '''name''' - '''mandatory'''. The name of the preference. Value will be automatically wrapped in totranslate if you don't.
* '''needReload''' - If set to true, the game interface will auto-reload after a change of the preference.
* '''values''' - '''mandatory'''. The array (map) of values with additional parameters per value.
** '''name''' - '''mandatory'''. String representation of the numeric value. Value will be automatically wrapped in totranslate if you don't.
** '''cssPref''' - CSS class to add to the '''<html>''' tag. Currently it is added or removed only after a reload (see needReload).
* '''default''' - Indicates the default value to use for this preference (optional, if not present the first value listed is the default).

=== Listening for preference changes ===

The BGA framework lacks any callback to notify your game when a user preference is changed (see [https://studio.boardgamearena.com/bug?id=36 proposal #36]), but you can create your own if you need to run some UI code in response to a preference change.

; In ggg.js
<pre>
setup: function (gamedatas) {
// your setup code here ...

this.initPreferencesObserver();
},

initPreferencesObserver: function () {
// Call onPreferenceChange() when any value changes
dojo.query('.preference_control').on('change', (e) => {
const match = e.target.id.match(/^preference_[cf]ontrol_(\d+)$/);
if (!match) {
return;
}
const pref = match[1];
const newValue = e.target.value;
this.prefs[pref].value = newValue;
this.onPreferenceChange(pref, newValue);
});
},

onPreferenceChange: function (prefId, prefValue) {
console.log("Preference changed", prefId, prefValue);
// your code here to handle the change
},
</pre>

=== Updating preference from code ===
The BGA framework lacks any method to update a user preference from the code (see [https://studio.boardgamearena.com/bug?id=36 proposal #36]), but you can create your own if you need to.

; In ggg.js
<pre>
updatePreference: function(prefId, newValue) {
// Select preference value in control:
dojo.query('#preference_control_' + prefId + ' > option[value="' + newValue
// Also select fontrol to fix a BGA framework bug:
+ '"], #preference_fontrol_' + prefId + ' > option[value="' + newValue
+ '"]').forEach((value) => dojo.attr(value, 'selected', true));
// Generate change event on control to trigger callbacks:
const newEvt = document.createEvent('HTMLEvents');
newEvt.initEvent('change', false, true);
$('preference_control_' + prefId).dispatchEvent(newEvt);
},
</pre>

=== Accessing User Preferences on the server ===
PHP has a variable called $this->player_preferences.
This contains a table of player preferences, ONLY accessible in setupNewGame().
You can use this to populate a table that you manage yourself.
You have to update the table when a player changes preference (and you have to hook up a listener and initiate an AJAX call out-of-turn).
Check the code of Agricola for details but this should work:

; In dbmodel.sql
<pre>
CREATE TABLE IF NOT EXISTS `user_preferences` (
`player_id` int(10) NOT NULL,
`pref_id` int(10) NOT NULL,
`pref_value` int(10) NOT NULL,
PRIMARY KEY (`player_id`, `pref_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

; In ggg.game.php
<pre>
protected function setupNewGame($players, $options = array())
{
// TODO: Save $this->player_preferences: key is player_id, value is array with pref_id as key and pref_value as value
}
</pre>

; In ggg.js

<pre>

// use code for initPreferencesObserver from above example

onPreferenceChange(prefId, prefValue) {
prefId = parseInt(prefId);
if (prefId === 101 /*TODO: You probably want to send only some preferences*/) {
// TODO: Code your own action in ggg.action.php and send it prefId and prefValue
// The on the server side you can save it all in the user_preferences
// table you created above.
}
},
</pre>

[[Category:Studio]]

File:Option-levels.png

2022-11-07T15:33:40Z

Draasill:

Options and preferences: gameoptions.json, gamepreferences.json

2022-11-07T15:33:23Z

Draasill: /* option display */

{{Studio_Framework_Navigation}}

In this file, you can define your game options (i.e. game variants) and user preferences.

Note: If your game has no variants or preferences, you don't have to modify this file.

'''IMPORTANT:''' after you edited this file and syncronized to ftp folder you have to go to the control panel and press "Reload game options configuration" for your changes '''to take effect'''.

Make sure you understand difference between options and preferences:
* Game options - something usually in the rule book defined as "variant" (except for 2,3,X people - that is automatically handled - you can query it)
* User preferences - personal choices of each player only visible to that specific player - i.e. layout, either or not to prompt for action, either or not auto-opt in in some actions, etc

__TOC__

== Game Options ==

Game options are selected by the table creator and usually correspond to game variants, for example if the game includes expansions or certain special rules.

These variants are defined in gameoptions.inc.php as the $game_options variable:

$game_options = [ // exactly named that
// options start with 100
100 => [ /*option description array for option 100*/ ],
101 => [ /*option description array for option 101*/ ],
// etc
];

All options defined in this file should have a corresponding "game state label" with the same ID (see "initGameStateLabels" in yourgame.game.php)

self::initGameStateLabels ([
...
"my_game_variant" => 100,
]);

Numbers have to be exactly from 100 to 199 (there can be gaps).

That is how you access them during runtime:

public function isSecondVariant() {
return $this->getGameStateValue('my_game_variant') == 2;
}

Or this
$this->gamestate->table_globals[100]

The following are the parameters of option description array:
* '''name''' - '''mandatory'''. The name of the option visible for table creator. Value must be wrapped in totranslate function.
* '''values''' - '''mandatory'''. The array (map) of values with additional parameters per value.
** '''name''' - '''mandatory'''. String representation of the numeric value visible to table creator. Value must be wrapped in totranslate function.
** '''description''' - String description of this value to use when the name of the option is not self-explanatory. Displayed at the table under the option when this value is selected.
** '''tmdisplay''' - String representation of the option visible in the table description in the lobby. Usually if a variant values are On and Off (default), the tmdisplay would be same as description name when On, and nothing (empty string) when Off. ('''Warning''': due to some caching, a change in tmdisplay may not be effective immediately in the studio, even after forcing a reload of gameoptions.inc.php.) '''Pro Tip:''' You can use this as a pre-game communication by adding fake options that just do nothing in the game but make it easier to find other player wanted the same game configuration (see the crew deep sea for example).
** '''nobeginner''' - Set to true if not recommended for beginners
** '''firstgameonly''' - Set to true if this option is recommended only for the first game (discovery option)
** '''beta''' - Set to true to indicate that this option is in "beta" development stage (there will be a warning for players starting the game)
** '''alpha''' - Set to true to indicate that this option is in "alpha" development stage (there will be a warning, and starting the game will be allowed only in training mode except for the developer)
** '''premium''' - Option can be only used by premium members
* '''default''' - indicates the default value to use for this option (optional, if not present the first value listed is the default)
* '''displaycondition''' - checks the conditions before displaying the option for selection. All conditions must be true for the option to display. Supported condition types:
** ''minplayers'' condition ensures at least this many players (Note: if your game works with a disjoint interval of player counts, you can supply an array of valid counts instead of a single value)
** ''maxplayers'' conditions ensure at most this many players
** ''otheroption'' condition ensures another option is set to this given values.
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given values
* '''displayconditionoperand''' - can be 'and' (this is the default) or 'or'. Allows to change the behaviour to display the option if one of the conditions is true instead of all of them.
* '''startcondition''' - checks the conditions (on options VALUES) before starting the game. All conditions must be true for the game to start, otherwise players will get a red error message when attempting to begin the game. Supported condition types:
** ''minplayers'' condition ensures at least this many players (Note: if your game works with a disjoint interval of player counts, you can supply an array of valid counts instead of a single value)
** ''maxplayers'' conditions ensure at most this many players
** ''otheroption'' conditions ensure another option is set to this given values. That works the same as in '''displaycondition'''.
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given value. That works the same as in '''displaycondition'''.
*: For all these condition types, a ''gamestartonly'' boolean option can be added, if you have options that are exclusive. Setting this boolean to ''true'' will defer the evaluation of the startcondition to the game creation, instead of preventing the player to select options that are exclusive at all. See [[#gamestartonly|below]] for an example.
* '''notdisplayedmessage''' - if option is not suppose to be visible because of displaycondition but this is set, the text will be visible instead of combo drop down
* '''level''' - what kind of option it is: ''base'', ''major'', or ''additional''. See [[#option_level|below]] for more informations.

Common options for all tables (reserved range 200-299):
*201 (const GAMESTATE_RATING_MODE) - ELO OFF (aka Training mode),
*200 (const GAMESTATE_CLOCK_MODE) - game speed profile, array(0,1,2) - realtime (technically <10 realtime but you cannot define range in php), values >=10 - turn based (currently 10..21)

Example:
<pre>
$game_options = array(
100 => array(
'name' => totranslate('my game option'),
'values' => array(
// A simple value for this option:
1 => array(
'name' => totranslate('option 1')
),

// A simple value for this option.
// If this value is chosen, the value of "tmdisplay" is displayed in the game lobby
2 => array(
'name' => totranslate('option 2'),
'tmdisplay' => totranslate('option 2')
),

// Another value, with other options:
// beta=true => this option is in beta version right now.
// nobeginner=true => this option is not recommended for beginners
3 => array(
'name' => totranslate('option 3'),
'beta' => true,
'nobeginner' => true
),
),
'default' => 1
),

101 => array(
'name' => totranslate('Draft variant'),
'values' => array(
1 => array(
'name' => totranslate('No draft')
),
2 => array(
'name' => totranslate('Draft'),
'tmdisplay' => totranslate('Draft'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100, // Game specific option defined in the same array above
'value' => array(2, 3, 4)
),
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1 // 1 if OFF
)
),

'startcondition' => array(
1 => array(),
2 => array(
array(
'type' => 'maxplayers',
'value' => 3,
'message' => totranslate('Draft option is available for 3 players maximum.')
)
),
),
),

102 => array(
'name' => totranslate('Takeovers'),
'values' => array(
2 => array(
'name' => totranslate('No takeover')
),
1 => array(
'name' => totranslate('Allow takeovers'),
'tmdisplay' => totranslate('Takeovers'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array( // Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100,
'value' => array(3, 4)
)
),
'startcondition' => array(
2 => array(),
1 => array(
array(
'type' => 'maxplayers',
'value' => 2,
'message' => totranslate('Rebel vs Imperium Takeover Scenario is available for 2 players only.')
)
),
),
)
);
</pre>

Example of option that condition on ELO off

<pre>
$game_options = array(

100 => array(
'name' => totranslate('Learning Game (No Research)'),
'values' => array(

1 => array( 'name' => totranslate('Off'), 'tmdisplay' => totranslate('') ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Learning Game') ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1, // 1 if OFF

)
),
'notdisplayedmessage' => totranslate('Learning variant available only with ELO off')
),

);
</pre>

Example of condition that is only available for REALTIME game mode
<pre>
'displaycondition' => array(
// Note: do not display this option until these conditions are met - game speed is selected as realtime
array( 'type' => 'otheroption', 'id' => GAMESTATE_CLOCK_MODE, 'value' => array(0,1,2) )
),
</pre>

Example of using condition on your own option
<pre>
102 => array(
'name' => totranslate('Scenarios'),
'values' => array(
1 => array( 'name' => totranslate('Off'),
'nobeginner' => false ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Scenarios'),
'nobeginner' => true ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroptionisnot',
'id' => 100, // learning variant
'value' => 2, // 1 if OFF,2 is ON

)
),
'notdisplayedmessage' => totranslate('Scenarios variant is not available if Learning variant is chosen')
),
</pre>

Example of handling solo vs multiplayer options:

<pre>
$game_options = array(

100 => array(
'name' => totranslate('Board setup'),
'values' => array(
1 => array(
'name' => totranslate( 'Mirror setup' ),
'description' => totranslate( 'The starting player shuffles their 6 Farm Cards and randomly lays a card face up in each of the round spaces of their Fruit Island Board. The other players then lay their cards in exactly the same way, copying the order of the starting player.' ),
'tmdisplay' => totranslate( 'Mirror setup' ),
),
2 => array(
'name' => totranslate( 'Random setup' ),
'description' => totranslate( 'Instead of every player copying the same card configuration as the starting player, every player shuffles their Farm Cards and lays down the cards randomly on their Fruit Island Board.' ),
'tmdisplay' => totranslate( 'Random setup' ),
),
),
'displaycondition' => array(
// Note: only display for non-solo mode
array(
'type' => 'minplayers',
'value' => array (2, 3, 4),
),
),
),

102 => array(
'name' => totranslate('Solo difficulty'),
'values' => array(
0 => array(
'name' => totranslate( 'Banan-apprentice' ),
'description' => totranslate( 'Do not remove any seed before starting the game.' ),
'tmdisplay' => totranslate( 'Banan-apprentice' ),
),
1 => array(
'name' => totranslate( 'Pear to the Throne' ),
'description' => totranslate( 'Remove 1 seed before starting the game.' ),
'tmdisplay' => totranslate( 'Pear to the Throne' ),
)
),
'displaycondition' => array(
// Note: only display for solo mode
array(
'type' => 'maxplayers',
'value' => 1
),
),
),

);
</pre>

==== displaycondition vs startcondition ====

<code>displaycondition</code> should be used when an option should not be present in the list under certain conditions.

For example, displaying the option which is consistent with the player count.

* 2 player maps: A B C D
* 3 player maps: E F G H
* 4 player maps: I J K L

<code>startcondition</code> should be used when a specific combination of option values is invalid, but the option itself still makes sense to show.

For example:

* Player 1 faction: A, B, C, D, E, F, G
* Player 2 faction: A, B, C, D, E, F, G
* startcondition: both players can't be the same faction

These options should both be displayed at all times, but there are some invalid configurations.

==== gamestartonly ====

On the table configuration page, it won't let you select a combination which is invalid according to <code>startcondition</code>. Doing so will show a red warning, and will revert the option to the previous value. This means you could end up in a situation where you can't easily change between certain options (requiring you to set or unset options in a specific order).

The consequence of the <code>gamestartonly</code> flag is that the player _can_ select an invalid combination. However, when clicking "Start", an invalid combination will produce an error.

Probably the easiest way to see what the difference is is with an example.

With a _Clans of Caledonia_ table:
* set to training mode
* set player count to 1
* try setting "Clan Auction" to one of the "On" options
* try starting the game, there's an error! Ie. <code>"gamestartonly" => true</code>

Then, with a _Sushi Go Party!_ table:
* set number of players to 7
* try setting "Sushi Go! / Sushi Go Party!" to "Sushi Go!"
* you can't set the option! Ie. <code>"gamestartonly" => false</code>

In code:

<pre>
$game_options = array(
100 => array(
'name' => totranslate('Option name'),
'values' => array( ... ),
'startcondition' => array(
1 => array(
array(
'type' => 'maxplayers',
'value' => 2,
'message' => totranslate('This option is available for 2 players only.'),
'gamestartonly' => true, // true = check only on gamestart, false = don't allow player to even select this combination
)
),
),
),
);
</pre>

==== option level ====

<pre>
$game_options = array(
100 => array(
'name' => totranslate('Option name'),
'values' => array( ... ),
'level' => 'base'
)
);
</pre>

* ''base'' is the default value (you don't need to specify it).
* ''major'' denotes a major option, which will always be displayed on top, and with a specific UI.
* ''additional'' means this option will not be displayed by default, to unclutter the option panel.

About major options:
* a game can only have '''1 major option''', and of course, it must be a important game changer.
* the pictures will default to the standard Game Box, and can be set independently for each option, from the [[Game metadata manager]] (in the "Major Variants" section).

==== option display ====

An option can be displayed as a '''Checkbox''' instead of a selector.

This is the case for options which:
* have only '''2 values'''
* values are either (case insensitive):
** ''yes'' and ''no''
** ''on'' and ''off''
** ''enabled'' and ''disabled''

[[File:Option-display.png|800px|Example of checkbox display]]

== User Preferences ==

User preferences is something cosmetic about the game interface which however can create user wars, so you can satisfy all users
by giving them individual preferences. You should use this only if it significantly improves the interface for a large proportion of users.
These preferences appear in the three-line hamburger menu in the top corner of the bga menu. "Display game logs" and Display tooltips" are baked-in by default, but you can extend this list as below.

[[File:century_preferences_menu.PNG|400px|The user preferences menu for the game Century]]

<blockquote>
''These preferences are a good place to put accessibility options - as Century did for its Colorblind Support.''
</blockquote>

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Colorblind Support'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'None' ), 'cssPref' => 'colorblind_off' ),
2 => array( 'name' => totranslate( 'Numbers' ), 'cssPref' => 'colorblind_on' ),
3 => array( 'name' => totranslate( 'Shapes' ), 'cssPref' => 'colorblind_shapes' )
),
'default' => 1
),
);
</pre>

There is two ways to check/apply this. In java Script

if (this.prefs[100].value == 2) ...

This checks if preferences 100 has selected value 2.

Second, if cssPref specified it will be applied to the '''<html>''' tag. So you can use different css styling for the preference. Note: it seems needed to set needReload to true for that class change to be effective.

As user you have to select them from the Gear menu when game is started. On studio only user0 will have it actually working (bug?).

The following are the parameters of preferences description array:
* '''name''' - '''mandatory'''. The name of the preference. Value will be automatically wrapped in totranslate if you don't.
* '''needReload''' - If set to true, the game interface will auto-reload after a change of the preference.
* '''values''' - '''mandatory'''. The array (map) of values with additional parameters per value.
** '''name''' - '''mandatory'''. String representation of the numeric value. Value will be automatically wrapped in totranslate if you don't.
** '''cssPref''' - CSS class to add to the '''<html>''' tag. Currently it is added or removed only after a reload (see needReload).
* '''default''' - Indicates the default value to use for this preference (optional, if not present the first value listed is the default).

=== Listening for preference changes ===

The BGA framework lacks any callback to notify your game when a user preference is changed (see [https://studio.boardgamearena.com/bug?id=36 proposal #36]), but you can create your own if you need to run some UI code in response to a preference change.

; In ggg.js
<pre>
setup: function (gamedatas) {
// your setup code here ...

this.initPreferencesObserver();
},

initPreferencesObserver: function () {
// Call onPreferenceChange() when any value changes
dojo.query('.preference_control').on('change', (e) => {
const match = e.target.id.match(/^preference_[cf]ontrol_(\d+)$/);
if (!match) {
return;
}
const pref = match[1];
const newValue = e.target.value;
this.prefs[pref].value = newValue;
this.onPreferenceChange(pref, newValue);
});
},

onPreferenceChange: function (prefId, prefValue) {
console.log("Preference changed", prefId, prefValue);
// your code here to handle the change
},
</pre>

=== Updating preference from code ===
The BGA framework lacks any method to update a user preference from the code (see [https://studio.boardgamearena.com/bug?id=36 proposal #36]), but you can create your own if you need to.

; In ggg.js
<pre>
updatePreference: function(prefId, newValue) {
// Select preference value in control:
dojo.query('#preference_control_' + prefId + ' > option[value="' + newValue
// Also select fontrol to fix a BGA framework bug:
+ '"], #preference_fontrol_' + prefId + ' > option[value="' + newValue
+ '"]').forEach((value) => dojo.attr(value, 'selected', true));
// Generate change event on control to trigger callbacks:
const newEvt = document.createEvent('HTMLEvents');
newEvt.initEvent('change', false, true);
$('preference_control_' + prefId).dispatchEvent(newEvt);
},
</pre>

=== Accessing User Preferences on the server ===
PHP has a variable called $this->player_preferences.
This contains a table of player preferences, ONLY accessible in setupNewGame().
You can use this to populate a table that you manage yourself.
You have to update the table when a player changes preference (and you have to hook up a listener and initiate an AJAX call out-of-turn).
Check the code of Agricola for details but this should work:

; In dbmodel.sql
<pre>
CREATE TABLE IF NOT EXISTS `user_preferences` (
`player_id` int(10) NOT NULL,
`pref_id` int(10) NOT NULL,
`pref_value` int(10) NOT NULL,
PRIMARY KEY (`player_id`, `pref_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

; In ggg.game.php
<pre>
protected function setupNewGame($players, $options = array())
{
// TODO: Save $this->player_preferences: key is player_id, value is array with pref_id as key and pref_value as value
}
</pre>

; In ggg.js

<pre>

// use code for initPreferencesObserver from above example

onPreferenceChange(prefId, prefValue) {
prefId = parseInt(prefId);
if (prefId === 101 /*TODO: You probably want to send only some preferences*/) {
// TODO: Code your own action in ggg.action.php and send it prefId and prefValue
// The on the server side you can save it all in the user_preferences
// table you created above.
}
},
</pre>

[[Category:Studio]]

File:Option-display.png

2022-11-07T15:31:44Z

Draasill:

Options and preferences: gameoptions.json, gamepreferences.json

2022-11-07T15:29:53Z

Draasill:

{{Studio_Framework_Navigation}}

In this file, you can define your game options (i.e. game variants) and user preferences.

Note: If your game has no variants or preferences, you don't have to modify this file.

'''IMPORTANT:''' after you edited this file and syncronized to ftp folder you have to go to the control panel and press "Reload game options configuration" for your changes '''to take effect'''.

Make sure you understand difference between options and preferences:
* Game options - something usually in the rule book defined as "variant" (except for 2,3,X people - that is automatically handled - you can query it)
* User preferences - personal choices of each player only visible to that specific player - i.e. layout, either or not to prompt for action, either or not auto-opt in in some actions, etc

__TOC__

== Game Options ==

Game options are selected by the table creator and usually correspond to game variants, for example if the game includes expansions or certain special rules.

These variants are defined in gameoptions.inc.php as the $game_options variable:

$game_options = [ // exactly named that
// options start with 100
100 => [ /*option description array for option 100*/ ],
101 => [ /*option description array for option 101*/ ],
// etc
];

All options defined in this file should have a corresponding "game state label" with the same ID (see "initGameStateLabels" in yourgame.game.php)

self::initGameStateLabels ([
...
"my_game_variant" => 100,
]);

Numbers have to be exactly from 100 to 199 (there can be gaps).

That is how you access them during runtime:

public function isSecondVariant() {
return $this->getGameStateValue('my_game_variant') == 2;
}

Or this
$this->gamestate->table_globals[100]

The following are the parameters of option description array:
* '''name''' - '''mandatory'''. The name of the option visible for table creator. Value must be wrapped in totranslate function.
* '''values''' - '''mandatory'''. The array (map) of values with additional parameters per value.
** '''name''' - '''mandatory'''. String representation of the numeric value visible to table creator. Value must be wrapped in totranslate function.
** '''description''' - String description of this value to use when the name of the option is not self-explanatory. Displayed at the table under the option when this value is selected.
** '''tmdisplay''' - String representation of the option visible in the table description in the lobby. Usually if a variant values are On and Off (default), the tmdisplay would be same as description name when On, and nothing (empty string) when Off. ('''Warning''': due to some caching, a change in tmdisplay may not be effective immediately in the studio, even after forcing a reload of gameoptions.inc.php.) '''Pro Tip:''' You can use this as a pre-game communication by adding fake options that just do nothing in the game but make it easier to find other player wanted the same game configuration (see the crew deep sea for example).
** '''nobeginner''' - Set to true if not recommended for beginners
** '''firstgameonly''' - Set to true if this option is recommended only for the first game (discovery option)
** '''beta''' - Set to true to indicate that this option is in "beta" development stage (there will be a warning for players starting the game)
** '''alpha''' - Set to true to indicate that this option is in "alpha" development stage (there will be a warning, and starting the game will be allowed only in training mode except for the developer)
** '''premium''' - Option can be only used by premium members
* '''default''' - indicates the default value to use for this option (optional, if not present the first value listed is the default)
* '''displaycondition''' - checks the conditions before displaying the option for selection. All conditions must be true for the option to display. Supported condition types:
** ''minplayers'' condition ensures at least this many players (Note: if your game works with a disjoint interval of player counts, you can supply an array of valid counts instead of a single value)
** ''maxplayers'' conditions ensure at most this many players
** ''otheroption'' condition ensures another option is set to this given values.
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given values
* '''displayconditionoperand''' - can be 'and' (this is the default) or 'or'. Allows to change the behaviour to display the option if one of the conditions is true instead of all of them.
* '''startcondition''' - checks the conditions (on options VALUES) before starting the game. All conditions must be true for the game to start, otherwise players will get a red error message when attempting to begin the game. Supported condition types:
** ''minplayers'' condition ensures at least this many players (Note: if your game works with a disjoint interval of player counts, you can supply an array of valid counts instead of a single value)
** ''maxplayers'' conditions ensure at most this many players
** ''otheroption'' conditions ensure another option is set to this given values. That works the same as in '''displaycondition'''.
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given value. That works the same as in '''displaycondition'''.
*: For all these condition types, a ''gamestartonly'' boolean option can be added, if you have options that are exclusive. Setting this boolean to ''true'' will defer the evaluation of the startcondition to the game creation, instead of preventing the player to select options that are exclusive at all. See [[#gamestartonly|below]] for an example.
* '''notdisplayedmessage''' - if option is not suppose to be visible because of displaycondition but this is set, the text will be visible instead of combo drop down
* '''level''' - what kind of option it is: ''base'', ''major'', or ''additional''. See [[#option_level|below]] for more informations.

Common options for all tables (reserved range 200-299):
*201 (const GAMESTATE_RATING_MODE) - ELO OFF (aka Training mode),
*200 (const GAMESTATE_CLOCK_MODE) - game speed profile, array(0,1,2) - realtime (technically <10 realtime but you cannot define range in php), values >=10 - turn based (currently 10..21)

Example:
<pre>
$game_options = array(
100 => array(
'name' => totranslate('my game option'),
'values' => array(
// A simple value for this option:
1 => array(
'name' => totranslate('option 1')
),

// A simple value for this option.
// If this value is chosen, the value of "tmdisplay" is displayed in the game lobby
2 => array(
'name' => totranslate('option 2'),
'tmdisplay' => totranslate('option 2')
),

// Another value, with other options:
// beta=true => this option is in beta version right now.
// nobeginner=true => this option is not recommended for beginners
3 => array(
'name' => totranslate('option 3'),
'beta' => true,
'nobeginner' => true
),
),
'default' => 1
),

101 => array(
'name' => totranslate('Draft variant'),
'values' => array(
1 => array(
'name' => totranslate('No draft')
),
2 => array(
'name' => totranslate('Draft'),
'tmdisplay' => totranslate('Draft'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100, // Game specific option defined in the same array above
'value' => array(2, 3, 4)
),
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1 // 1 if OFF
)
),

'startcondition' => array(
1 => array(),
2 => array(
array(
'type' => 'maxplayers',
'value' => 3,
'message' => totranslate('Draft option is available for 3 players maximum.')
)
),
),
),

102 => array(
'name' => totranslate('Takeovers'),
'values' => array(
2 => array(
'name' => totranslate('No takeover')
),
1 => array(
'name' => totranslate('Allow takeovers'),
'tmdisplay' => totranslate('Takeovers'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array( // Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100,
'value' => array(3, 4)
)
),
'startcondition' => array(
2 => array(),
1 => array(
array(
'type' => 'maxplayers',
'value' => 2,
'message' => totranslate('Rebel vs Imperium Takeover Scenario is available for 2 players only.')
)
),
),
)
);
</pre>

Example of option that condition on ELO off

<pre>
$game_options = array(

100 => array(
'name' => totranslate('Learning Game (No Research)'),
'values' => array(

1 => array( 'name' => totranslate('Off'), 'tmdisplay' => totranslate('') ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Learning Game') ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1, // 1 if OFF

)
),
'notdisplayedmessage' => totranslate('Learning variant available only with ELO off')
),

);
</pre>

Example of condition that is only available for REALTIME game mode
<pre>
'displaycondition' => array(
// Note: do not display this option until these conditions are met - game speed is selected as realtime
array( 'type' => 'otheroption', 'id' => GAMESTATE_CLOCK_MODE, 'value' => array(0,1,2) )
),
</pre>

Example of using condition on your own option
<pre>
102 => array(
'name' => totranslate('Scenarios'),
'values' => array(
1 => array( 'name' => totranslate('Off'),
'nobeginner' => false ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Scenarios'),
'nobeginner' => true ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroptionisnot',
'id' => 100, // learning variant
'value' => 2, // 1 if OFF,2 is ON

)
),
'notdisplayedmessage' => totranslate('Scenarios variant is not available if Learning variant is chosen')
),
</pre>

Example of handling solo vs multiplayer options:

<pre>
$game_options = array(

100 => array(
'name' => totranslate('Board setup'),
'values' => array(
1 => array(
'name' => totranslate( 'Mirror setup' ),
'description' => totranslate( 'The starting player shuffles their 6 Farm Cards and randomly lays a card face up in each of the round spaces of their Fruit Island Board. The other players then lay their cards in exactly the same way, copying the order of the starting player.' ),
'tmdisplay' => totranslate( 'Mirror setup' ),
),
2 => array(
'name' => totranslate( 'Random setup' ),
'description' => totranslate( 'Instead of every player copying the same card configuration as the starting player, every player shuffles their Farm Cards and lays down the cards randomly on their Fruit Island Board.' ),
'tmdisplay' => totranslate( 'Random setup' ),
),
),
'displaycondition' => array(
// Note: only display for non-solo mode
array(
'type' => 'minplayers',
'value' => array (2, 3, 4),
),
),
),

102 => array(
'name' => totranslate('Solo difficulty'),
'values' => array(
0 => array(
'name' => totranslate( 'Banan-apprentice' ),
'description' => totranslate( 'Do not remove any seed before starting the game.' ),
'tmdisplay' => totranslate( 'Banan-apprentice' ),
),
1 => array(
'name' => totranslate( 'Pear to the Throne' ),
'description' => totranslate( 'Remove 1 seed before starting the game.' ),
'tmdisplay' => totranslate( 'Pear to the Throne' ),
)
),
'displaycondition' => array(
// Note: only display for solo mode
array(
'type' => 'maxplayers',
'value' => 1
),
),
),

);
</pre>

==== displaycondition vs startcondition ====

<code>displaycondition</code> should be used when an option should not be present in the list under certain conditions.

For example, displaying the option which is consistent with the player count.

* 2 player maps: A B C D
* 3 player maps: E F G H
* 4 player maps: I J K L

<code>startcondition</code> should be used when a specific combination of option values is invalid, but the option itself still makes sense to show.

For example:

* Player 1 faction: A, B, C, D, E, F, G
* Player 2 faction: A, B, C, D, E, F, G
* startcondition: both players can't be the same faction

These options should both be displayed at all times, but there are some invalid configurations.

==== gamestartonly ====

On the table configuration page, it won't let you select a combination which is invalid according to <code>startcondition</code>. Doing so will show a red warning, and will revert the option to the previous value. This means you could end up in a situation where you can't easily change between certain options (requiring you to set or unset options in a specific order).

The consequence of the <code>gamestartonly</code> flag is that the player _can_ select an invalid combination. However, when clicking "Start", an invalid combination will produce an error.

Probably the easiest way to see what the difference is is with an example.

With a _Clans of Caledonia_ table:
* set to training mode
* set player count to 1
* try setting "Clan Auction" to one of the "On" options
* try starting the game, there's an error! Ie. <code>"gamestartonly" => true</code>

Then, with a _Sushi Go Party!_ table:
* set number of players to 7
* try setting "Sushi Go! / Sushi Go Party!" to "Sushi Go!"
* you can't set the option! Ie. <code>"gamestartonly" => false</code>

In code:

<pre>
$game_options = array(
100 => array(
'name' => totranslate('Option name'),
'values' => array( ... ),
'startcondition' => array(
1 => array(
array(
'type' => 'maxplayers',
'value' => 2,
'message' => totranslate('This option is available for 2 players only.'),
'gamestartonly' => true, // true = check only on gamestart, false = don't allow player to even select this combination
)
),
),
),
);
</pre>

==== option level ====

<pre>
$game_options = array(
100 => array(
'name' => totranslate('Option name'),
'values' => array( ... ),
'level' => 'base'
)
);
</pre>

* ''base'' is the default value (you don't need to specify it).
* ''major'' denotes a major option, which will always be displayed on top, and with a specific UI.
* ''additional'' means this option will not be displayed by default, to unclutter the option panel.

About major options:
* a game can only have '''1 major option''', and of course, it must be a important game changer.
* the pictures will default to the standard Game Box, and can be set independently for each option, from the [[Game metadata manager]] (in the "Major Variants" section).

==== option display ====

An option can be displayed as a '''Checkbox''' instead of a selector.

This is the case for options which:
* have only '''2 values'''
* values are either (case insensitive):
** ''yes'' and ''no''
** ''on'' and ''off''
** ''enabled'' and ''disabled''

== User Preferences ==

User preferences is something cosmetic about the game interface which however can create user wars, so you can satisfy all users
by giving them individual preferences. You should use this only if it significantly improves the interface for a large proportion of users.
These preferences appear in the three-line hamburger menu in the top corner of the bga menu. "Display game logs" and Display tooltips" are baked-in by default, but you can extend this list as below.

[[File:century_preferences_menu.PNG|400px|The user preferences menu for the game Century]]

<blockquote>
''These preferences are a good place to put accessibility options - as Century did for its Colorblind Support.''
</blockquote>

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Colorblind Support'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'None' ), 'cssPref' => 'colorblind_off' ),
2 => array( 'name' => totranslate( 'Numbers' ), 'cssPref' => 'colorblind_on' ),
3 => array( 'name' => totranslate( 'Shapes' ), 'cssPref' => 'colorblind_shapes' )
),
'default' => 1
),
);
</pre>

There is two ways to check/apply this. In java Script

if (this.prefs[100].value == 2) ...

This checks if preferences 100 has selected value 2.

Second, if cssPref specified it will be applied to the '''<html>''' tag. So you can use different css styling for the preference. Note: it seems needed to set needReload to true for that class change to be effective.

As user you have to select them from the Gear menu when game is started. On studio only user0 will have it actually working (bug?).

The following are the parameters of preferences description array:
* '''name''' - '''mandatory'''. The name of the preference. Value will be automatically wrapped in totranslate if you don't.
* '''needReload''' - If set to true, the game interface will auto-reload after a change of the preference.
* '''values''' - '''mandatory'''. The array (map) of values with additional parameters per value.
** '''name''' - '''mandatory'''. String representation of the numeric value. Value will be automatically wrapped in totranslate if you don't.
** '''cssPref''' - CSS class to add to the '''<html>''' tag. Currently it is added or removed only after a reload (see needReload).
* '''default''' - Indicates the default value to use for this preference (optional, if not present the first value listed is the default).

=== Listening for preference changes ===

The BGA framework lacks any callback to notify your game when a user preference is changed (see [https://studio.boardgamearena.com/bug?id=36 proposal #36]), but you can create your own if you need to run some UI code in response to a preference change.

; In ggg.js
<pre>
setup: function (gamedatas) {
// your setup code here ...

this.initPreferencesObserver();
},

initPreferencesObserver: function () {
// Call onPreferenceChange() when any value changes
dojo.query('.preference_control').on('change', (e) => {
const match = e.target.id.match(/^preference_[cf]ontrol_(\d+)$/);
if (!match) {
return;
}
const pref = match[1];
const newValue = e.target.value;
this.prefs[pref].value = newValue;
this.onPreferenceChange(pref, newValue);
});
},

onPreferenceChange: function (prefId, prefValue) {
console.log("Preference changed", prefId, prefValue);
// your code here to handle the change
},
</pre>

=== Updating preference from code ===
The BGA framework lacks any method to update a user preference from the code (see [https://studio.boardgamearena.com/bug?id=36 proposal #36]), but you can create your own if you need to.

; In ggg.js
<pre>
updatePreference: function(prefId, newValue) {
// Select preference value in control:
dojo.query('#preference_control_' + prefId + ' > option[value="' + newValue
// Also select fontrol to fix a BGA framework bug:
+ '"], #preference_fontrol_' + prefId + ' > option[value="' + newValue
+ '"]').forEach((value) => dojo.attr(value, 'selected', true));
// Generate change event on control to trigger callbacks:
const newEvt = document.createEvent('HTMLEvents');
newEvt.initEvent('change', false, true);
$('preference_control_' + prefId).dispatchEvent(newEvt);
},
</pre>

=== Accessing User Preferences on the server ===
PHP has a variable called $this->player_preferences.
This contains a table of player preferences, ONLY accessible in setupNewGame().
You can use this to populate a table that you manage yourself.
You have to update the table when a player changes preference (and you have to hook up a listener and initiate an AJAX call out-of-turn).
Check the code of Agricola for details but this should work:

; In dbmodel.sql
<pre>
CREATE TABLE IF NOT EXISTS `user_preferences` (
`player_id` int(10) NOT NULL,
`pref_id` int(10) NOT NULL,
`pref_value` int(10) NOT NULL,
PRIMARY KEY (`player_id`, `pref_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

; In ggg.game.php
<pre>
protected function setupNewGame($players, $options = array())
{
// TODO: Save $this->player_preferences: key is player_id, value is array with pref_id as key and pref_value as value
}
</pre>

; In ggg.js

<pre>

// use code for initPreferencesObserver from above example

onPreferenceChange(prefId, prefValue) {
prefId = parseInt(prefId);
if (prefId === 101 /*TODO: You probably want to send only some preferences*/) {
// TODO: Code your own action in ggg.action.php and send it prefId and prefValue
// The on the server side you can save it all in the user_preferences
// table you created above.
}
},
</pre>

[[Category:Studio]]

Game interface stylesheet: yourgamename.css

2022-08-11T09:49:41Z

Draasill: remove useless browser prefixes & workaround

{{Studio_Framework_Navigation}}

__TOC__

This is the CSS stylesheet of your game User Interface.

Styles defined on this file will be applied to the HTML elements you define in your HTML template (yourgame_yourgame.tpl), and to HTML elements you create dynamically with Javascript.

Usually, you are using CSS to:

1°) define the overall layout of your game
(ex: place the board on the top left, place player's hand beside, place the deck on the right, ...).

2°) create your CSS-sprites:
All images of your games should be gathered into a small number of image files. Then, using background-image and background-position CSS properties, you create HTML blocks that can display these images correctly.

Example:
<pre>
Example of CSS sprites (a black token and a white token, 20x20px each, embedded in the same "tokens.png" 40x20px image):

.white_token {
background-image: url('img/tokens.png');
background-position: 0px 0px;
}
.black_token {
background-image: url('img/tokens.png');
background-position: -20px 0px;
}
.token {
width: 20px;
height: 20px;
background-repeat: none;
}
</pre>

3°) ... anything else:

It is really easy to add and remove CSS classes dynamically from your Javascript with dojo.addClass and dojo.removeClass. It is also easy to check if an element has a class (dojo.hasClass) or to get all elements with a specific class (dojo.query).

This is why, very often, using CSS classes for the logic of your user interface allow you to do complex thing easily.

Note: on the production platform, this file will be compressed and comments will be removed. Consequently, don't hesitate to put as many comments as necessary.

Important: ALL the CSS directives for your game must be included in this CSS file. You can't create additional CSS files and import them.

== Warning: using percentage in background-position ==

In the example above, you will see "background-position: -20px 0px;" is used for the black token. You could also write this as "background-position: -100% 0%;" which displays the image at the same offset, because it is relative to the size of the .token bounding box, and this means the size of your image file doesn't need to precisely match the size of objects on the screen (this can be easier to write, and you can also substitute different image files without having to rewrite all the css.) However, it is strongly recommended that if you do this, you also specify <code>background-size</code> as a percentage as well.

This is because, if the size of the div on screen after any further scaling - which is done for you by the framework to fit games into small windows - is not a whole integer number of pixels, then rounding must occur at some points in the calculation; if the background-size and background-position are calculated in different ways, the difference in rounding can result int the final image offsets being incorrect. This is most significant on Safari (on MacOS, iPhone and iPad) where the discrepancy can be substantial enough to make a game ''illegible''; but other browsers can be off by a few pixels as well. [https://jsfiddle.net/shadowphiar/yLq36mzt/ (external demo)]. To avoid this issue, either:

* choose one unit (pixels, em, percentages etc) and specify '''all''' the background-size and background-position offsets of a div in the same unit.
* adjust the size of your div so that, after any global scaling (this.gameinterface_zoomFactor), it will occupy an integer number of pixels on the screen.

== Warning: using Z-index ==

You may use z-index CSS property in your game interface, but you should pay attention to the following: BGA dialogs are displayed with a z-index of 950. If you want to use z-index safely, you should use value '''lower than 900'''.

About z-index: don't forget that if you are using a z-index, your element will be displayed above all elements that do not have a z-index. So it's no use to have big z-index values: 1 is enough most of the time :)

== Tip: how to make your cards looks beautiful :) ==

This piece of CSS (to adapt to your needs) is adding rounded corners + a shadow to your card.

<pre>
border-radius: 10px;
border: 1px black solid;
box-shadow: 5px 5px 5px 0px rgba(0,0,0,0.4);
</pre>

== spectatorMode ==

When a spectator (= a player that is not part of the game) is viewing a game, the BGA framework add the CSS class "spectatorMode" to the wrapping HTML tag of your game.

This way, if you want to apply a special style to some elements of your game for spectators, you can do this in your CSS:

<pre>
.spectatorMode #your_element_id {
/* your special style */
}
</pre>

The most common usage of this is to hide some elements to spectators. For example, to hide "my hand" elements:

<pre>
.spectatorMode #my_hand {
display: none;
}
</pre>

[[Category:Studio]]

Game meta-information: gameinfos.jsonc

2022-04-07T13:40:55Z

Draasill: /* Tags */

{{Studio_Framework_Navigation}}

== Overview ==

From this file, you can edit the various meta-information of your game.

Once you modified the file, don't forget to click on "Reload game informations" from the Control Panel in order in can be taken into account.

Most information provided in this file are self-explainable.

See sections below for specific cases.

== Publisher/Designer fields ==

These fields should match the publisher/designer for the game. In the case of a public domain name, they should be left empty (empty string '')

== Beta ==

You are not allowed to set the "'''is_beta'''" to 0 before the game has been released on BGA and stabilized.

== Time Profiles ==
'''fast/medium/slow_additional_time''': please set high values here: after the game has been released, we will lower these value to match the real game duration.

== Number of players ==

'''players'''
'players' => array( 3, 4, 6 ),

* during the first step of development of a game, it is recommended to have "1 player" configuration: much easy to start/stop a game this way, don't need to switch players.
* if you change the minimum number of players from for example 1 to 2, make sure the new tables you create are not restricted from 1 to 1 player otherwise when you create a new table and this account setting is used, there will be a conflict with the new minimum number of players allowed and you will be blocked from creating the game.
But you can also unblock yourself by changing player number again, launching a game with a larger number, and then getting back to the numbers you want.

'''suggest_player_number''' / '''not_recommend_player_number'''
don't specify anything here if there is no configuration that is REALLY better/worst than another one. You can check player's poll on BoardGameGeek game page if you have any doubt. '''Important exception:''' in the automatic lobby, if 'suggest_player_number' is not specified, the system will try first the lowest. So if the lowest player number is not compatible with the default options for your game (especially if there is a Solo mode that can only be played in training mode) you have to specify a suggest_player_number of your choice, so that players launching a game in the automatic lobby without checking the option don't get an error with the default configuration.

== Colors ==

'''player_colors'''
'player_colors' => array( "ff0000", "008000", "0000ff", "ffa500", "ffffff" ),

This array defines the default player colors, theoretically this can be bigger then maximum number of players but you have to support all of the in your game.
Your setupNewGame in php is responsible for attributing these values to players. See section "Player color preferences" in [[Main_game_logic:_yourgamename.game.php]] for details.

== Losers not ranked between themselves ==

By default, all player are ranked, but in some games, the rules say that there is only one winner and that all the other players are losers and not ranked between themselves. You can set this option to true so that for your game, there is only one winner and losers, without a full ranking of all players.

The score in this case should be 1 for the winner and 0 for the losers.

// 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' => false,

== Disable player rotation in case of rematch ==

By default, in case of a rematch players are rotated so that the first player changes. If for your game it's better to always have a random player order you can change this option.

// When doing a rematch, the player order is swapped using a "rotation" so the starting player is not the same
// If you want to disable this, set this to true (even if the comment in your game file say the opposite).
'disable_player_order_swap_on_rematch' => false,

== Custom "buy this game" button ==

By default, the "buy this game" button is a link to an Amazon search with the name of the game.

You can replace it by a different URL / game button label with :

'custom_buy_button' => array(
'url' => 'http://yoururl.com',
'label' => 'Name of the website'
),

Note : button label will be "Buy on <Name of the website>"

== Tags ==

A maximum of '''ten''' tags can be attributed to your game (not counting complexity and duration tags).

Tags are useful to place your game in the correct game list section and to give a good quick overview of what the game is about to players.

'''⚠ Note''': The ''order'' of the tags is very important too, you'll have to put the most relevant first.

'''⚠ Note''': tags are <b style="color:darkred">only read during the first deploy</b> from the file <code>gameinfos.inc.php</code> ; afterwards, BGA is responsible for setting tags for a game.

Game complexity (you '''must''' specify one tag '''and only one''' from this category):
* <code>2</code>: Casual games
* <code>3</code>: For regular players
* <code>4</code>: For core gamers

Duration tags (only indicative - the correct tag will be automatically set by BGA after a while):
* <code>10</code>: Short game (<10 minutes)
* <code>11</code>: Medium length game (10 minutes to 30 minutes)
* <code>12</code>: Long game (>30mn)

Other tags:
* <code>20</code>: Awarded game (Win a prestigious award) (the game must have been at the '''first''' place of one the [http://boardgamegeek.com/wiki/page/Gaming_Industry_Awards# following major awards list]).
* <code>22</code>: Prototype (This game has not been published yet)
* <code>23</code>: Classic (This game is a classic from Public Domain)
* <code>25</code>: Party game
* <code>26</code>: Family
* <code>27</code>: Miniatures (figurines)
* <code>28</code>: Recommended in Realtime
* <code>29</code>: Recommended in Turnbased
* <code>30</code>: Best for 2 (best with 2 players) (automatically added to games for 2p only)

Theme tags:
* <code>100</code>: Fantasy
* <code>101</code>: Science-Fiction
* <code>102</code>: Historical
* <code>103</code>: Adventure
* <code>104</code>: Exploration
* <code>105</code>: Conquest
* <code>106</code>: Building
* <code>107</code>: Western
* <code>108</code>: Espionage
* <code>109</code>: Trains
* <code>110</code>: Sport
* <code>111</code>: Economy
* <code>112</code>: Aviation
* <code>113</code>: Surreal/Silly/Absurd
* <code>114</code>: Animals
* <code>115</code>: Wargame
* <code>1</code>: Abstract game

Mechanism tags:
* <code>200</code>: Cards (cards plays a central role in this game)
* <code>201</code>: Dice
* <code>202</code>: Solo
* <code>203</code>: Worker placement
* <code>204</code>: Hand management
* <code>205</code>: Bluffing
* <code>206</code>: Tile placement
* <code>207</code>: Combos
* <code>208</code>: Area Majority
* <code>209</code>: Race
* <code>210</code>: Collection
* <code>211</code>: Cooperative
* <code>212</code>: Random
* <code>213</code>: Speed
* <code>214</code>: Asymmetrical
* <code>215</code>: Communication
* <code>216</code>: Conquest
* <code>217</code>: Team
* <code>218</code>: Bidding
* <code>219</code>: Objectives
* <code>220</code>: Trick-taking
* <code>221</code>: Resource management
* <code>222</code>: Roles
* <code>223</code>: Roll & Write
* <code>224</code>: Push your luck
* <code>225</code>: Voting
* <code>226</code>: Word games
* <code>227</code>: Deck Building
* <code>228</code>: Engine building
* <code>229</code>: Drafting
* <code>230</code>: Player elimination

== Game Presentation ==

Short game presentation text that will appear on the game description page, structured as an array of paragraphs.

Each paragraph must be wrapped with totranslate() for translation and should not contain html (plain text without formatting). A good length for this text is between 100 and 150 words (about 6 to 9 lines on a standard display)

Example:
'presentation' => array(
totranslate("This wonderful game is about geometric shapes!"),
totranslate("It was awarded best triangle game of the year in 2005 and nominated for the Spiel des Jahres."),
...
),

== Tie breaker description ==
Describe tie breaker score calculation (player_score_aux in player table).

Important: This is used in the javascript too, which is automatically generated. Using newlines in here will cause errors in the javascript, which will cause the game to not load.

Example:
'tie_breaker_description' => totranslate("Number of remaining cards in hand"),

== Multiple tie breaker management ==

If your game has multiple tie breakers, here is what you should do.

Let's take this example: "In case of a tie, the winner is the game with the most remaining money, then number of buildings built, then number of cards in your hand".

In this example, your "score_aux" field is probably calculated like this:

10000 * (remaining_money ) + 100 * (buildings_built) + (number_of_cards)

In this case, you should add the following in gameinfos.inc.php:

'tie_breaker_split' => array( 10000, 100 , 1 ),

It means that the first tie breaker has been multiplied by 10000, the second by 100, and the third by 1.

Using this, the result screen will be adapted to show exactly what is needed. For example:
* When 2 players are tied, it will show their remaining money.
* If their remaining money are equal, it will show the number of building built in addition to the remaining money.
* If these two tie breaker are still the same, it will show the 3 tie breaking values.

== Language dependency ==

If you have a game that is language dependent, you can use the option described here: [[Main_game_logic:_yourgamename.game.php#Language_dependent_games_API]]

== Coop Elo Mode ==

For cooperative games, by default players will earn as many Elo points as the score.

For games where there is no variable difficulty (such as for example Bandido) we keep that setting, but for all coop games where we have options to change the difficulty level and/or where the score reached indicates a higher level of skill and/or where the number of players has a significant impact on the difficulty, we have to set up a reference scale for Elo points (between 1300 and 2500). Players regularly winning with a specific difficulty setting will have their Elo nearing this value asymptotically over time.

For this, you have to set up the coop_elo_mode parameter.

'''Warning: While this can reflect player skills more precisely compared to flat ELO gain, players may abandon losing games or avoid new players to prevent ELO loss.'''

Related discussion - https://forum.boardgamearena.com/viewtopic.php?f=3&t=24363

Here is an example using options and win/loss (score 1/0):

'coop_elo_mode' => [
'type' => 'points_references',
'references' => [
// Difficulty 1
['players_nbr' => 2, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],
['players_nbr' => 2, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],
['players_nbr' => 3, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1350]],
['players_nbr' => 3, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1400]],
['players_nbr' => 4, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],
['players_nbr' => 4, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],
// Difficulty 2
['players_nbr' => 2, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],
['players_nbr' => 2, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],
['players_nbr' => 3, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1450]],
['players_nbr' => 3, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1540]],
['players_nbr' => 4, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],
['players_nbr' => 4, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],
// Difficulty 3
['players_nbr' => 2, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],
['players_nbr' => 2, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],
['players_nbr' => 3, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],
['players_nbr' => 3, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],
['players_nbr' => 4, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],
['players_nbr' => 4, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],
// Difficulty 4
['players_nbr' => 2, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],
['players_nbr' => 2, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],
['players_nbr' => 3, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1640]],
['players_nbr' => 3, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 1830]],
['players_nbr' => 4, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],
['players_nbr' => 4, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],
// Difficulty 5
['players_nbr' => 2, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],
['players_nbr' => 2, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],
['players_nbr' => 3, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1740]],
['players_nbr' => 3, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 1980]],
['players_nbr' => 4, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],
['players_nbr' => 4, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],
],
],

Here is an example using different scoring values to indicate the level of difficulty mastered by the players winning the game:

'coop_elo_mode' => array(
'type' => 'points_references',
'references' => array(
array(
'players_nbr' => 2,
//'options' => array( ),
'elo' => array(
0 => 1000,
1 => 1350,
2 => 1425,
3 => 1500,
4 => 1576,
5 => 1651,
6 => 1727,
7 => 1802,
8 => 1878,
9 => 1953,
10 => 2029,
11 => 2104,
12 => 2180
)
),
array(
'players_nbr' => 3,
//'options' => array( ),
'elo' => array(
0 => 1000,
1 => 1400,
2 => 1470,
3 => 1541,
4 => 1612,
5 => 1683,
6 => 1754,
7 => 1825,
8 => 1895,
9 => 1966,
10 => 2018,
11 => 2095,
12 => 2250
)
),
array(
'players_nbr' => 4,
//'options' => array( ),
'elo' => array(
0 => 1000,
1 => 1430,
2 => 1505,
3 => 1580,
4 => 1655,
5 => 1730,
6 => 1805,
7 => 1880,
8 => 1955,
9 => 2030,
10 => 2105,
11 => 2180,
12 => 2330
)
),
array(
'players_nbr' => 5,
// 'options' => array( ),
'elo' => array(
0 => 1000,
1 => 1480,
2 => 1558,
3 => 1636,
4 => 1714,
5 => 1792,
6 => 1870,
7 => 1949,
8 => 2027,
9 => 2105,
10 => 2183,
11 => 2261,
12 => 2340
)
)
)
),

Game meta-information: gameinfos.jsonc

2022-03-16T20:12:19Z

Draasill: /* Tags */

{{Studio_Framework_Navigation}}

== Overview ==

From this file, you can edit the various meta-information of your game.

Once you modified the file, don't forget to click on "Reload game informations" from the Control Panel in order in can be taken into account.

Most information provided in this file are self-explainable.

See sections below for specific cases.

== Publisher/Designer fields ==

These fields should match the publisher/designer for the game. In the case of a public domain name, they should be left empty (empty string '')

== Beta ==

You are not allowed to set the "'''is_beta'''" to 0 before the game has been released on BGA and stabilized.

== Time Profiles ==
'''fast/medium/slow_additional_time''': please set high values here: after the game has been released, we will lower these value to match the real game duration.

== Number of players ==

'''players'''
'players' => array( 3, 4, 6 ),

* during the first step of development of a game, it is recommended to have "1 player" configuration: much easy to start/stop a game this way, don't need to switch players.
* if you change the minimum number of players from for example 1 to 2, make sure the new tables you create are not restricted from 1 to 1 player otherwise when you create a new table and this account setting is used, there will be a conflict with the new minimum number of players allowed and you will be blocked from creating the game.
But you can also unblock yourself by changing player number again, launching a game with a larger number, and then getting back to the numbers you want.

'''suggest_player_number''' / '''not_recommend_player_number'''
don't specify anything here if there is no configuration that is REALLY better/worst than another one. You can check player's poll on BoardGameGeek game page if you have any doubt. '''Important exception:''' in the automatic lobby, if 'suggest_player_number' is not specified, the system will try first the lowest. So if the lowest player number is not compatible with the default options for your game (especially if there is a Solo mode that can only be played in training mode) you have to specify a suggest_player_number of your choice, so that players launching a game in the automatic lobby without checking the option don't get an error with the default configuration.

== Colors ==

'''player_colors'''
'player_colors' => array( "ff0000", "008000", "0000ff", "ffa500", "ffffff" ),

This array defines the default player colors, theoretically this can be bigger then maximum number of players but you have to support all of the in your game.
Your setupNewGame in php is responsible for attributing these values to players. See section "Player color preferences" in [[Main_game_logic:_yourgamename.game.php]] for details.

== Losers not ranked between themselves ==

By default, all player are ranked, but in some games, the rules say that there is only one winner and that all the other players are losers and not ranked between themselves. You can set this option to true so that for your game, there is only one winner and losers, without a full ranking of all players.

The score in this case should be 1 for the winner and 0 for the losers.

// 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' => false,

== Disable player rotation in case of rematch ==

By default, in case of a rematch players are rotated so that the first player changes. If for your game it's better to always have a random player order you can change this option.

// When doing a rematch, the player order is swapped using a "rotation" so the starting player is not the same
// If you want to disable this, set this to true (even if the comment in your game file say the opposite).
'disable_player_order_swap_on_rematch' => false,

== Custom "buy this game" button ==

By default, the "buy this game" button is a link to an Amazon search with the name of the game.

You can replace it by a different URL / game button label with :

'custom_buy_button' => array(
'url' => 'http://yoururl.com',
'label' => 'Name of the website'
),

Note : button label will be "Buy on <Name of the website>"

== Tags ==

A maximum of '''ten''' tags can be attributed to your game (not counting complexity and duration tags).

Tags are useful to place your game in the correct game list section and to give a good quick overview of what the game is about to players.

'''⚠ Note''': The ''order'' of the tags is very important too, you'll have to put the most relevant first.

'''⚠ Note''': tags are <b style="color:darkred">only read during the first deploy</b> from the file <code>gameinfos.inc.php</code> ; afterwards, BGA is responsible for setting tags for a game.

Game complexity (you '''must''' specify one tag '''and only one''' from this category):
* <code>2</code>: Casual games
* <code>3</code>: For regular players
* <code>4</code>: For core gamers

Duration tags (only indicative - the correct tag will be automatically set by BGA after a while):
* <code>10</code>: Short game (<10 minutes)
* <code>11</code>: Medium length game (10 minutes to 30 minutes)
* <code>12</code>: Long game (>30mn)

Other tags:
* <code>20</code>: Awarded game (Win a prestigious award) (the game must have been at the '''first''' place of one the [http://boardgamegeek.com/wiki/page/Gaming_Industry_Awards# following major awards list]).
* <code>22</code>: Prototype (This game has not been published yet)
* <code>23</code>: Classic (This game is a classic from Public Domain)
* <code>25</code>: Party game
* <code>26</code>: Family
* <code>27</code>: Miniatures (figurines)
* <code>28</code>: Recommended in Realtime
* <code>29</code>: Recommended in Turnbased
* <code>30</code>: 2 players (2p game / best with 2 players)

Theme tags:
* <code>100</code>: Fantasy
* <code>101</code>: Science-Fiction
* <code>102</code>: Historical
* <code>103</code>: Adventure
* <code>104</code>: Exploration
* <code>105</code>: Conquest
* <code>106</code>: Building
* <code>107</code>: Western
* <code>108</code>: Espionage
* <code>109</code>: Trains
* <code>110</code>: Sport
* <code>111</code>: Financial
* <code>112</code>: Aviation
* <code>113</code>: Surreal/Silly/Absurd
* <code>114</code>: Animals
* <code>115</code>: Wargame
* <code>1</code>: Abstract game

Mechanism tags:
* <code>200</code>: Cards (cards plays a central role in this game)
* <code>201</code>: Dice
* <code>202</code>: Solo
* <code>203</code>: Worker placement
* <code>204</code>: Hand management
* <code>205</code>: Bluffing
* <code>206</code>: Tile placement
* <code>207</code>: Combos
* <code>208</code>: Area Majority
* <code>209</code>: Race
* <code>210</code>: Collection
* <code>211</code>: Cooperative
* <code>212</code>: Random
* <code>213</code>: Speed
* <code>214</code>: Asymmetrical
* <code>215</code>: Communication
* <code>216</code>: Conquest
* <code>217</code>: Team
* <code>218</code>: Bidding
* <code>219</code>: Objectives
* <code>220</code>: Trick-taking
* <code>221</code>: Resource management
* <code>222</code>: Roles
* <code>223</code>: Roll & Write
* <code>224</code>: Push your luck
* <code>225</code>: Voting
* <code>226</code>: Word games
* <code>227</code>: Deck Building
* <code>228</code>: Engine building
* <code>229</code>: Drafting
* <code>230</code>: Player elimination

== Game Presentation ==

Short game presentation text that will appear on the game description page, structured as an array of paragraphs.

Each paragraph must be wrapped with totranslate() for translation and should not contain html (plain text without formatting). A good length for this text is between 100 and 150 words (about 6 to 9 lines on a standard display)

Example:
'presentation' => array(
totranslate("This wonderful game is about geometric shapes!"),
totranslate("It was awarded best triangle game of the year in 2005 and nominated for the Spiel des Jahres."),
...
),

== Tie breaker description ==
Describe tie breaker score calculation (player_score_aux in player table).

Important: This is used in the javascript too, which is automatically generated. Using newlines in here will cause errors in the javascript, which will cause the game to not load.

Example:
'tie_breaker_description' => totranslate("Number of remaining cards in hand"),

== Multiple tie breaker management ==

If your game has multiple tie breakers, here is what you should do.

Let's take this example: "In case of a tie, the winner is the game with the most remaining money, then number of buildings built, then number of cards in your hand".

In this example, your "score_aux" field is probably calculated like this:

10000 * (remaining_money ) + 100 * (buildings_built) + (number_of_cards)

In this case, you should add the following in gameinfos.inc.php:

'tie_breaker_split' => array( 10000, 100 , 1 ),

It means that the first tie breaker has been multiplied by 10000, the second by 100, and the third by 1.

Using this, the result screen will be adapted to show exactly what is needed. For example:
* When 2 players are tied, it will show their remaining money.
* If their remaining money are equal, it will show the number of building built in addition to the remaining money.
* If these two tie breaker are still the same, it will show the 3 tie breaking values.

== Language dependency ==

If you have a game that is language dependent, you can use the option described here: [[Main_game_logic:_yourgamename.game.php#Language_dependent_games_API]]

== Coop Elo Mode ==

For cooperative games, by default players will earn as many Elo points as the score.

For games where there is no variable difficulty (such as for example Bandido) we keep that setting, but for all coop games where we have options to change the difficulty level and/or where the score reached indicates a higher level of skill and/or where the number of players has a significant impact on the difficulty, we have to set up a reference scale for Elo points (between 1300 and 2500). Players regularly winning with a specific difficulty setting will have their Elo nearing this value asymptotically over time.

For this, you have to set up the coop_elo_mode parameter.

'''Warning: While this can reflect player skills more precisely compared to flat ELO gain, players may abandon losing games or avoid new players to prevent ELO loss.'''

Related discussion - https://forum.boardgamearena.com/viewtopic.php?f=3&t=24363

Here is an example using options and win/loss (score 1/0):

'coop_elo_mode' => [
'type' => 'points_references',
'references' => [
// Difficulty 1
['players_nbr' => 2, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],
['players_nbr' => 2, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],
['players_nbr' => 3, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1350]],
['players_nbr' => 3, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1400]],
['players_nbr' => 4, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],
['players_nbr' => 4, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],
// Difficulty 2
['players_nbr' => 2, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],
['players_nbr' => 2, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],
['players_nbr' => 3, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1450]],
['players_nbr' => 3, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1540]],
['players_nbr' => 4, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],
['players_nbr' => 4, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],
// Difficulty 3
['players_nbr' => 2, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],
['players_nbr' => 2, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],
['players_nbr' => 3, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],
['players_nbr' => 3, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],
['players_nbr' => 4, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],
['players_nbr' => 4, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],
// Difficulty 4
['players_nbr' => 2, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],
['players_nbr' => 2, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],
['players_nbr' => 3, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1640]],
['players_nbr' => 3, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 1830]],
['players_nbr' => 4, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],
['players_nbr' => 4, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],
// Difficulty 5
['players_nbr' => 2, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],
['players_nbr' => 2, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],
['players_nbr' => 3, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1740]],
['players_nbr' => 3, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 1980]],
['players_nbr' => 4, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],
['players_nbr' => 4, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],
],
],

Here is an example using different scoring values to indicate the level of difficulty mastered by the players winning the game:

'coop_elo_mode' => array(
'type' => 'points_references',
'references' => array(
array(
'players_nbr' => 2,
//'options' => array( ),
'elo' => array(
0 => 1000,
1 => 1350,
2 => 1425,
3 => 1500,
4 => 1576,
5 => 1651,
6 => 1727,
7 => 1802,
8 => 1878,
9 => 1953,
10 => 2029,
11 => 2104,
12 => 2180
)
),
array(
'players_nbr' => 3,
//'options' => array( ),
'elo' => array(
0 => 1000,
1 => 1400,
2 => 1470,
3 => 1541,
4 => 1612,
5 => 1683,
6 => 1754,
7 => 1825,
8 => 1895,
9 => 1966,
10 => 2018,
11 => 2095,
12 => 2250
)
),
array(
'players_nbr' => 4,
//'options' => array( ),
'elo' => array(
0 => 1000,
1 => 1430,
2 => 1505,
3 => 1580,
4 => 1655,
5 => 1730,
6 => 1805,
7 => 1880,
8 => 1955,
9 => 2030,
10 => 2105,
11 => 2180,
12 => 2330
)
),
array(
'players_nbr' => 5,
// 'options' => array( ),
'elo' => array(
0 => 1000,
1 => 1480,
2 => 1558,
3 => 1636,
4 => 1714,
5 => 1792,
6 => 1870,
7 => 1949,
8 => 2027,
9 => 2105,
10 => 2183,
11 => 2261,
12 => 2340
)
)
)
),

Template:Studio Framework Navigation

2021-06-22T16:38:18Z

Draasill: add "studio-framework-navigation" class to hide from main page

<div class="studio-framework-navigation" style="float: right; width: 300px; border: solid #000 1px; padding: 1em; margin-left: 1em; background: #fff;">
__NOTOC__
<h3><center>'''Game File Reference'''</center></h3>

<h3><center>'''[[Studio file reference|Overview]]'''</center></h3>

* [[Game database model: dbmodel.sql|<b>dbmodel.sql</b>]] - database model
* [[Game meta-information: gameinfos.inc.php|<b>gameinfos.inc.php</b>]] - meta-information
* [[Game options and preferences: gameoptions.inc.php|<b>gameoptions.inc.php</b>]] - game options & user preferences
* [[Game art: img directory|<b>img/</b>]] - game art
* [[Game material description: material.inc.php|<b>material.inc.php</b>]] - static data
* <b>misc/</b> - studio-only storage
* <b>modules/</b> - additional game code
* [[Your game state machine: states.inc.php|<b>states.inc.php</b>]] - state machine
* [[Game statistics: stats.inc.php|<b>stats.inc.php</b>]] - statistics
* [[Players actions: yourgamename.action.php|X.<b>action.php</b>]] - player actions
* [[Game interface stylesheet: yourgamename.css|X<b>.css</b>]] - interface stylesheet
* [[Main game logic: yourgamename.game.php|X.<b>game.php</b>]] - main logic
* [[Game interface logic: yourgamename.js|X.<b>js</b>]] - interface logic
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X.<b>view.php</b>]] - dynamic game layout
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X_X.<b>tpl</b>]] - static game layout
<br>
-----
<h3><center>'''Useful Components'''</center></h3>

'''Official'''

* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
* [[Draggable]]: a JS component to manage drag'n'drop actions.
* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.
* [[Zone]]: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).

Undocumented component (if somebody knows please help with docs)
* [[Wrapper]]: a JS component to wrap a <div> element around its child, even if these elements are absolute positioned.

'''Unofficial'''

* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks
* [[Some usual board game elements image ressources]]

<br>
-----
<h3><center>'''Game Development Process'''</center></h3>

* [[First steps with BGA Studio]]
* [[Create a game in BGA Studio: Complete Walkthrough]]
* [[Tutorial reversi]]
* [[Tutorial gomoku]]
* [[Tutorial hearts]]
* [[BGA Studio Guidelines]]
* [[BGA game Lifecycle]]
* [[Pre-release checklist]]
* [[Post-release phase]]
* [[Help|Player Resources]] - add player help/rules to your game page

<br>
-----
<h3><center>'''Guides for Common Topics'''</center></h3>

* [[Translations]] - make your game translatable
* [[Game replay|Game Replay]]
* [[Your game mobile version|Mobile Users]]
* [[3D]]

<br>
-----
<h3><center>'''Miscellaneous Resources'''</center></h3>

* [[Studio FAQ]]
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment
* [[Studio logs]] - Instructions for log access
* [[Practical debugging]] - Tips focused on debugging
* [[Troubleshooting]] - Most common "I am really stuck" situations
* [https://studio.boardgamearena.com/bugs Studio Bugs] - Reports against Studio itself (not BGA!)
</div>

Stock

2021-02-05T09:55:11Z

Draasill: minor

{{Studio_Framework_Navigation}}

== Overview ==

'''Stock''' is a javascript component that you can use in your game interface to display a set of elements of the same size that need to be arranged in single or multiple lines.

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

Examples of stock use cases:

* Display a set of cards, typically hands (examples: ''Hearts'', ''Seasons'', ''The Boss'', ''Race for the Galaxy'').
* Display items in player panels (examples: ''Takenoko'', ''Amyitis'', ...)
* ... Many other situations. For example, black dice and cubes on cards in ''Troyes'' are displayed with stock components.

Using stock:

* Your items are arranged nicely and sorted by type.
* When adding or removing items to a set, all items slide smoothly to their new position in the set.
* Selecting and unselecting items are built-in functions.
* You don't have to worry about inserting/removing HTML code; the entire life cycle of the stock is managed by the component.

== Using stock: a simple example ==

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

First, don't forget to add "ebg/stock" as a dependency in your js file:

<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE
],
</pre>

The stock is initialized in the Javascript "setup" method like this:

<pre>
// Player hand
this.playerHand = new ebg.stock();
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

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

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

Here's how we tell stock what items to display:

<pre>
// Specify that there are 13 images per row in the CSS sprite image
this.playerHand.image_items_per_row = 13;

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

Explanation:

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

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

From now on, if we need to add a card - for example, the 5 of Hearts - to a player's hand, we can do this:

<pre>
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ) );
</pre>

In reality, cards have some IDs, which are useful to manipulate them. This is the reason we are using "addToStockWithId" instead:

<pre>
this.playerHand.addToStockWithId( this.getCardUniqueId( 2 /* 2=hearts */, 5 ), my_card_id );
</pre>

If afterwards we want to remove this card from the stock:

<pre>
this.playerHand.removeFromStockById( my_card_id );
</pre>

== Complete stock component reference ==

=== Creation ===

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

With create, you create a new stock component.

Parameters:
* page: the container page. Usually: "this".
* container_div: the container "div" element (an empty div element in your template, with an id).
* width and height (in pixels) for the stock component.

(See ''Hearts'' example above).

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

Define a new type of item and add it to the stock.

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

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

Be careful: you must specify the image url as this:

<pre>
g_gamethemeurl+'img/yourimage.png'
</pre>

* image_position: if "image" specify the URL of a CSS sprite, you must specify the position of the item image in this CSS sprite. For example, if you have a CSS sprite with 3 cubes with a size of 20x20 pixels each (so your CSS image has for example a size of 20x60 or 60x20), you specify "0" for the first cube image, 1 for the second, 2 for the third.

''Important'': if there is more than one line of items in your CSS sprite, you must specify how many items per line you have in your CSS sprite, see image_items_per_row below:

'''image_items_per_row'''
Class member to set number of columns in css sprite (or how many items per row). I.e. if you sprite is 4 cards horizonatall and 6 vertically, you have to set it to 4.
<pre>
// Specify that there are 10 image items per row in images used in "myStockObject" control.
this.myStockObject.image_items_per_row = 4;
</pre>

=== Add/Remove items ===

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

Add an item to the stock, with the specified type, but without a unique ID.

To make your life easier, in most cases we suggest you use '''addToStockWithId''' in order to give an ID to the item added. '''addToStock''' is suitable when you are using a stock to control items that are generic game materials that don't need to be tracked individually (example: a bunch of money tokens).

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

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

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

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

This is the same method as '''addToStock''', except that it also associates an ID with the newly created item.

This is especially useful:

* When you need to know which item(s) have been selected by the user (see '''getSelectedItems''').
* When you need to remove a specific item from the stock with '''removeFromStockById'''.

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

Remove an item of the specific type from the stock.

'to' is an optional parameter. If "to" contains the ID of an HTML element, the item removed from the Stock slides to this HTML element before it disappears.

'noupdate' is an optional parameter. If set to "true" it will prevent the Stock display from changing. This is useful when multiple (but not all) items are removed at the same time, to avoid ghost items appearing briefly. If you pass noupdate you have to call updateDisplay() after all items are removed.

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

Remove an item with a specific ID from the stock.

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

'noupdate' is an optional parameter. If set to "true" it will prevent the Stock display from changing. This is useful when multiple (but not all) items are removed at the same time, to avoid ghost items appearing briefly. If you pass noupdate you have to call updateDisplay() after all items are removed.

'''removeAll()'''

Remove all items from the stock.

'''removeAllTo( to )'''

Remove all items from the stock. If "to" contains the ID of an HTML element, the item removed from the stock slides to this HTML element before it disappears.

=== Getters ===

'''getPresentTypeList()'''

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

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

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

'''count():'''

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

'''getAllItems()'''

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

'''getItemDivId(id)'''

Get the div id using the stock item id (to manipulate element properties directly).

'''getItemById(id)'''

Get the Stock item with the id in parameter
ex : return the object { type:1, id: 1001 }

=== Selection ===

'''setSelectionMode( mode )'''

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

'''setSelectionAppearance( type )'''

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

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

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

'''isSelected( id )'''

Return a boolean indicating whether the specified item id has been selected.

'''selectItem( id )'''

Select the specified item.

'''unselectItem( id )'''

Unselect the specified item.

'''unselectAll()'''

Unselect all items of the stock.

'''onChangeSelection'''

This callback method is called when the player selects/unselects an item of the stock.

You can connect this to one of your methods like this:

<pre>
dojo.connect( this.myStockControl, 'onChangeSelection', this, 'onMyMethodToCall' );

(...)

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

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

Nota bene:
- The "control_name" argument is the ID (the "DOM" id) of the "div" container of your stock control. Using "control_name", you can use the same callback method for different Stock control and see which one trigger the method.
- The "item_id" argument is the stock ID (index) of the stock item that has just been selected/unselected.

'''getSelectedItems()'''

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

'''getUnselectedItems()'''

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

=== Layout ===

'''resetItemsPosition()'''

If you moved an item from the stock control manually (ex: after a drag'n'drop) and want to reset their positions to their original ones, you can call this method.
Note: it is the same as updateDisplay() without arugment, not sure why there are two methods.

'''updateDisplay(from)'''
Update the display completely (if 'from' is defined: moves new items from this location).

Example code if you change the underlying stock item, or otherwise want to make the stock item refresh:
<pre>
this.myStockControl.updateDisplay();
</pre>

'''item_margin'''

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

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

'''changeItemsWeight( newWeights )'''

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

Items are immediately re-sorted with the new weight.

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

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

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

Example2:
<pre>
// Be careful with object initialisers with variables, use the bracket notation.
// Item type 1 gets a new weight of 10
var card_type = 1;
this.myStockControl.changeItemsWeight( { [card_type]: 10 } );
</pre>

'''centerItems'''

Center the stock items in the middle of the stock container.
e.g. this.myStock.centerItems = true;

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

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

By default, horizontal_overlap and vertical_overlap are 0.

When horizontal_overlap=20, it means that a stock item will overlap to only show 20% of the width of all the previous items. horizontal_overlap can't be greater than 100.

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

See the games "Jaipur" or "Koryŏ" to see examples of use of this function.

'''autowidth'''

Stock does not play well if you attempt to inline-block it with other blocks, to fix that you have to set this flag which will calculate width properly
mystock.autowidth = true;

=== Customize apperance ===

'''extraClasses'''

Can be set to a list of class names (separated by space) on stock object, so when div is created these are added, i.e.

this.playerHand.extraClasses='mycard';

Note that it is the same list for all items.

'''onItemCreate'''

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

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

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

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

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

</pre>

'''onItemDelete'''

Function handler called when div is removed

this.myStock.onItemDelete = (card_div, card_type_id, card_id) => { console.log("card deleted from myStock: "+card_id); };

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

Most cases will be one of the following situations:

'''Situation A''':

When you add a card to a stock item, and this card is '''not''' coming from another stock:

* Use '''addToStockWithId''' with a "from" argument set to the element of your interface where the card should come from (i.e. div id). For example if you want to "reveal" card from player hand and it is not an interface element you can set from to be 'player_board_'+activePlayerId (where activePlayerId is player who played that card).

'''Situation B''':

When you add a card to a stock item, and this card is coming from another stock:

* On the destination Stock, use '''addToStockWithId''' with a "from" argument which is the HTML id of the corresponding item in the source Stock. For example, if the source stock id is "myHand", then the HTML id of card 48 is "myHand_item_48".
* Then, remove the source item with '''removeFromStockById'''.

(Note that it's important to do things in this order, because the source item must still exist when you use it as the origin of the slide.)

'''Situation C''':

When you move a card from a stock item to something that is not a stock item:

* Insert the card as a classic HTML template (dojo.place / this.format_block).
* Place it on the Stock item with '''this.placeOnObject''', using the Stock item HTML id (see above).
* Slide it to its new position with '''this.slideToObject'''.
* Remove the card from the Stock item with '''removeFromStockById'''.

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

You can customize this (showing the default value):
<pre>

this.mystock.jstpl_stock_item= "<div id=\"${id}\" class=\"stockitem\" style=\"top:${top}px;left:${left}px;width:${width}px;height:${height}px;z-index:${position};background-image:url('${image}');\"></div>";
</pre>
To produce a different type of stock item

Gamehelpindianchief

2020-09-12T13:18:57Z

Draasill:

== How to Play: ==

The game lasts just 7 rounds. Over the course of the game each player will make 7 different melds. Each meld requires a different number of cards and has different rules for scoring points.

The 7 melds take their names from a Mother Goose rhyme:

* 5 cards - Rich Man
* 3 cards - Poor Man
* 2 cards - Beggar Man
* 1 card - Thief
* 6 cards - Doctor
* 4 cards - Lawyer
* 7 cards - Indian Chief

During the 7 rounds, a player makes each meld once and once only, but they can be made in any order. After each round the hands refill to 8 cards. The game is over at the end of the seventh round, i.e., once everyone has made all 7 melds.

== The 7 Melds ==

Here are the 7 different melds in order of number of cards required:

1. Thief. Meld any single card and score the face value for that card. (For all "face values" in the game, aces count 1 and face cards count 10.)

The Thief's special power is that, after everyone's scores for the hand have been recorded, the player who played the Thief may elect, instead of being dealt a new card from the deck, to "steal" a card someone else has melded on that hand.

Once a Thief decides to steal a card, the player takes it into hand and replaces it in the other player's meld with the card melded as Thief. Thus it is available to be stolen by another Thief, if any.

If more than one Thief is in play, the honor of the first steal goes to the lower or lowest number. If there is a tie and they cannot agree to take different cards, neither Thief gets to steal.

2. Beggar Man. Meld 2 cards and hope for sympathy. This symbolizes two outstretched supplicating hands.

For each card someone else melds on the same round that matches the rank of one of your two cards, score 2 points.

3. Poor Man. Melding 3 cards, here is your chance to profit by the sweat of your brow. The spade is the symbol of your toil. Meld any 3 cards, but score the face values only of the spades you play.

4. Lawyer. The Law is exact. Meld 4 cards, and if their face values add up to exactly 25, score 25 points. Otherwise score nothing.

5. Rich Man. Even a Rich Man has to pay taxes! Meld any 5 cards, add their face values together and score the total as a negative number.

6. Doctor. The 6 cards melded as the Doctor must meet very stringent requirements, or they will score nothing. All 3 of these conditions must be met:

(a) No two cards can be of the same rank. (Because a Doctor needs wide and varied knowledge.)

(b) At least one of the 6 cards must be a heart. (Because a Doctor needs to have a heart!)

(c) One of the 6 cards must be an ace. (Because a Doctor should be an ace!)

If these three conditions are met, then the player picks one suit and scores 10 points for each card in that suit among his 6 cards. (Because a Doctor needs to be good at his specialty.)

7. Indian Chief. The Indian Chief is a compound meld, being comprised of two discrete parts: A five-card poker hand and a two-card chemin-de-fer hand.

(a) To score the chemin-de-fer hand, add the face value of the two cards together and count just the last digit of the total. (For example, a 7 and an 8 added together make 15, so are worth 5.)

(b) To score the remaining 5 cards in the meld, find the best poker hand that can be made and score as follows:

* 50 for five of a kind (if two decks are in play)
* 45 for a straight flush
* 40 for four of a kind
* 35 for a full house
* 30 for a flush
* 25 for a straight
* 20 for three of a kind
* 15 for two pairs
* 10 for one pair
* 5 for no pair

Remember: The 7 melds can be played in any order. After the 7 rounds are played and scored, the winner is the player with the most points.

== Refilling to 8 cards: ==

The players leave their melds face-up until the cards for the new round have been dealt from the remainder of the deck. Then the remainder of the deck is shuffled together with the face-up cards to form the supply for the next hand.

Gamehelpindianchief

2020-09-11T20:52:13Z

Draasill: /* How to Play: */

== How to Play: ==

The game lasts just 7 rounds. Over the course of the game each player will make 7 different melds. Each meld requires a different number of cards and has different rules for scoring points.

The 7 melds take their names from a Mother Goose rhyme:

* 5 cards - Rich Man
* 3 cards - Poor Man
* 2 cards - Beggar Man
* 1 card - Thief
* 6 cards - Doctor
* 4 cards - Lawyer
* 7 cards - Indian Chief

During the 7 rounds, a player makes each meld once and once only, but they can be made in any order. After each round the hands refill to 8 cards. The game is over at the end of the seventh round, i.e., once everyone has made all 7 melds.

== The 7 Melds ==

Here are the 7 different melds in order of number of cards required:

1. Thief. Meld any single card and score the face value for that card. (For all "face values" in the game, aces count 1 and face cards count 10.)

The Thief's special power is that, after everyone's scores for the hand have been recorded, the player who played the Thief may elect, instead of being dealt a new card from the deck, to "steal" a card someone else has melded on that hand.

Once a Thief decides to steal a card, the player takes it into hand and replaces it in the other player's meld with the card melded as Thief. Thus it is available to be stolen by another Thief, if any.

If more than one Thief is in play, the honor of the first steal goes to the lower or lowest number. If there is a tie and they cannot agree to take different cards, neither Thief gets to steal.

2. Beggar Man. Meld 2 cards and hope for sympathy. This symbolizes two outstretched supplicating hands.

For each card someone else melds on the same round that matches the rank of one of your two cards, score 2 points.

3. Poor Man. Melding 3 cards, here is your chance to profit by the sweat of your brow. The spade is the symbol of your toil. Meld any 3 cards, but score the face values only of the spades you play.

4. Lawyer. The Law is exact. Meld 4 cards, and if their face values add up to exactly 25, score 25 points. Otherwise score nothing.

5. Rich Man. Even a Rich Man has to pay taxes! Meld any 5 cards, add their face values together and score the total as a negative number.

6. Doctor. The 6 cards melded as the Doctor must meet very stringent requirements, or they will score nothing. All 3 of these conditions must be met:

(a) No two cards can be of the same rank. (Because a Doctor needs wide and varied knowledge.)

(b) At least one of the 6 cards must be a heart. (Because a Doctor needs to have a heart!)

(c) One of the 6 cards must be an ace. (Because a Doctor should be an ace!)

If these three conditions are met, then the player picks one suit and scores 10 points for each card in that suit among his 6 cards. (Because a Doctor needs to be good at his specialty.)

7. Indian Chief. The Indian Chief is a compound meld, being comprised of two discrete parts: A five-card poker hand and a two-card chemin-de-fer hand.

(a) To score the chemin-de-fer hand, add the face value of the two cards together and count just the last digit of the total. (For example, a 7 and an 8 added together make 15, so are worth 5.)

(b) To score the remaining 5 cards in the meld, find the best poker hand that can be made and score as follows:

50 for five of a kind (if two decks are in play)
45 for a straight flush
40 for four of a kind
35 for a full house
30 for a flush
25 for a straight
20 for three of a kind
15 for two pairs
10 for one pair
5 for no pair

Remember: The 7 melds can be played in any order. After the 7 rounds are played and scored, the winner is the player with the most points.

== Refilling to 8 cards: ==

The players leave their melds face-up until the cards for the new round have been dealt from the remainder of the deck. Then the remainder of the deck is shuffled together with the face-up cards to form the supply for the next hand.

BGA Code Sharing

2020-05-25T14:21:49Z

Draasill: /* Projects hosted not in studio */

{{Studio_Framework_Navigation}}

This page is for listing of externally hosted bga projects, tools and resources, as well as internal project
intended for sharing

== Projects hosted not in studio ==

See the table a link and nickname of the developer on bga (same as used for dev forum), and short description

'''Important notice about artwork on BGA Open Source projects: original hi-resolution images from publishers must not be published on the repositories. In addition, it is better to specify that the images derivated from publishers artwork are copyrighted and cannot be licensed under a free license like Creative Commons.
'''

{| class="wikitable"
|-
! NON-GAME PROJECTS
! CODE LINK
! DEVELOPER
|-
| Shared Code (not a game)
| https://github.com/elaskavaia/bga-sharedcode
| Victoria_La
|-
| BoardGameArena Workbench (not a game)
| https://github.com/danielholmes/bga-workbench
| Daniel Holmes (dhau)
|-
! GAME
! CODE LINK
! DEVELOPER
|-
| Assyria
| https://github.com/sebastien-prudhomme/bga-assyria
| daikinee
|-
| The Battle for Hill 218
| https://github.com/danielholmes/battle-for-hill-218
| Daniel Holmes (dhau)
|-
| Bonbons
| https://github.com/AntonioSoler/bga-bonbons
| Morgalad
|-
| Coinche
| https://github.com/drasill/bga-coinche
| Draasill
|-
| Coup: City State
| https://github.com/quietmint/bga-coupcitystate
| quietmint
|-
| Egyptian Ratscrew
| https://github.com/0BuRner/bga-egyptianratscrew
| 0BuRner
|-
| Eruption
| https://github.com/AndyKerrison/bga-eruption
| Andy_K
|-
| Florenza: The Card Game
| https://github.com/alberto-bottarini/bga-florenza
| tarini
|-
| Hearts '''(Tutorial)'''
| https://github.com/elaskavaia/bga-heartsla
| Victoria_La
|-
| Incan Gold
| https://github.com/AntonioSoler/bga-incangold
| Morgalad
|-
| Marco Polo
| https://github.com/rcitaliano/MarcoPolo
| rcitaliano
|-
| Nile
| https://github.com/AndyKerrison/bga-nile
| Andy_K
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
| Penny Press
| https://github.com/AdamNovotny/bga-blooms
| A-dam
|-
| P.I.
| https://gitlab.com/fa81/bga-pi, https://github.com/hellp/bga-pi (mirror)
| Fabian Neumann (fa81)
|-
| Tablut
| https://github.com/Lucas-C/tablut
| Lucas-C & ntaffore
|-
| Takara Island
| https://github.com/AntonioSoler/bga-takaraisland
| Morgalad
|-
| Teotihuacan: City of Gods
| https://github.com/Trompetenhut/bga-teotihuacan
| Trompetenhut
|-
| The King's Guild
| https://github.com/AdamNovotny/BGG-KingsGuild
| A-dam
|}

== Projects on studio ==

Links to studio project which owner wish share as read only.
Project owner please add you project here, dev nickname and short description if you would like to share it.
For the projects below any developer can add themselves to a project as read-only from http://en.studio.boardgamearena.com/#!projects page.

{| class="wikitable"
|-
! NAME
! CODE LINK
! DEVELOPER
|-
| Shared Code
| http://en.studio.boardgamearena.com/#!studiogame?game=sharedcode
| Victoria_La
|-
| Original BGA template
| http://en.studio.boardgamearena.com/#!studiogame?game=template
| Victoria_La
|-
|}

== Other useful resources ==

* Archive of tutorial projects https://www.dropbox.com/s/rsd5r4v49xudpp0/Studio.zip?dl=0
** Note: Hearts project is corrupted there, use Hearts tutorial project above
* Website with bunch of textures and sounds http://www.grsites.com/archive/textures/
* Shrink images without loss of quality https://tinypng.com/ or http://www.iloveimg.com/ (recommended by Gregory Isabelli)
* CSS shapes https://css-tricks.com/examples/ShapesOfCSS/
* PDF Scraper - extract images - http://www.extractpdf.com/
* BoardGameArena Workbench - set of tools to help test and deploy BGA projects - https://github.com/danielholmes/bga-workbench

BGA Code Sharing

2020-05-25T14:19:16Z

Draasill: /* Projects hosted not in studio */

{{Studio_Framework_Navigation}}

This page is for listing of externally hosted bga projects, tools and resources, as well as internal project
intended for sharing

== Projects hosted not in studio ==

See the table a link and nickname of the developer on bga (same as used for dev forum), and short description

'''Important notice about artwork on BGA Open Source projects: original hi-resolution images from publishers must not be published on the repositories. In addition, it is better to specify that the images derivated from publishers artwork are copyrighted and cannot be licensed under a free license like Creative Commons.
'''

{| class="wikitable"
|-
! NON-GAME PROJECTS
! CODE LINK
! DEVELOPER
|-
| Shared Code (not a game)
| https://github.com/elaskavaia/bga-sharedcode
| Victoria_La
|-
| BoardGameArena Workbench (not a game)
| https://github.com/danielholmes/bga-workbench
| Daniel Holmes (dhau)
|-
! GAME
! CODE LINK
! DEVELOPER
|-
| Assyria
| https://github.com/sebastien-prudhomme/bga-assyria
| daikinee
|-
| The Battle for Hill 218
| https://github.com/danielholmes/battle-for-hill-218
| Daniel Holmes (dhau)
|-
| Bonbons
| https://github.com/AntonioSoler/bga-bonbons
| Morgalad
|-
| Coup: City State
| https://github.com/quietmint/bga-coupcitystate
| quietmint
|-
| Coinche
| https://github.com/drasill/bga-coinche
| Draasill
|-
| Egyptian Ratscrew
| https://github.com/0BuRner/bga-egyptianratscrew
| 0BuRner
|-
| Eruption
| https://github.com/AndyKerrison/bga-eruption
| Andy_K
|-
| Florenza: The Card Game
| https://github.com/alberto-bottarini/bga-florenza
| tarini
|-
| Hearts '''(Tutorial)'''
| https://github.com/elaskavaia/bga-heartsla
| Victoria_La
|-
| Incan Gold
| https://github.com/AntonioSoler/bga-incangold
| Morgalad
|-
| Marco Polo
| https://github.com/rcitaliano/MarcoPolo
| rcitaliano
|-
| Nile
| https://github.com/AndyKerrison/bga-nile
| Andy_K
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
| Penny Press
| https://github.com/AdamNovotny/bga-blooms
| A-dam
|-
| P.I.
| https://gitlab.com/fa81/bga-pi, https://github.com/hellp/bga-pi (mirror)
| Fabian Neumann (fa81)
|-
| Tablut
| https://github.com/Lucas-C/tablut
| Lucas-C & ntaffore
|-
| Takara Island
| https://github.com/AntonioSoler/bga-takaraisland
| Morgalad
|-
| Teotihuacan: City of Gods
| https://github.com/Trompetenhut/bga-teotihuacan
| Trompetenhut
|-
| The King's Guild
| https://github.com/AdamNovotny/BGG-KingsGuild
| A-dam
|}

== Projects on studio ==

Links to studio project which owner wish share as read only.
Project owner please add you project here, dev nickname and short description if you would like to share it.
For the projects below any developer can add themselves to a project as read-only from http://en.studio.boardgamearena.com/#!projects page.

{| class="wikitable"
|-
! NAME
! CODE LINK
! DEVELOPER
|-
| Shared Code
| http://en.studio.boardgamearena.com/#!studiogame?game=sharedcode
| Victoria_La
|-
| Original BGA template
| http://en.studio.boardgamearena.com/#!studiogame?game=template
| Victoria_La
|-
|}

== Other useful resources ==

* Archive of tutorial projects https://www.dropbox.com/s/rsd5r4v49xudpp0/Studio.zip?dl=0
** Note: Hearts project is corrupted there, use Hearts tutorial project above
* Website with bunch of textures and sounds http://www.grsites.com/archive/textures/
* Shrink images without loss of quality https://tinypng.com/ or http://www.iloveimg.com/ (recommended by Gregory Isabelli)
* CSS shapes https://css-tricks.com/examples/ShapesOfCSS/
* PDF Scraper - extract images - http://www.extractpdf.com/
* BoardGameArena Workbench - set of tools to help test and deploy BGA projects - https://github.com/danielholmes/bga-workbench