Board Game Arena - User contributions [en]

Gamehelpstoneage

2026-06-28T17:19:28Z

Inaofr: /* Mammoth Herd */ Indicate the cancelling of 2p/3p limitation at the mammoth position

==Overview==

You are the leader of a tribe during the Stone Age and must decide where to allocate your members to gather resources, build huts, and grow your civilization. While you advance, don't forget to keep your tribe fed or you will lose points.

==Gameplay==

Each player starts with 5 people and 12 food.

Each round has 3 phases.

==== Phase 1: Place Workers ====

In turn order, each player assigns one or more workers to a place. Each place (except for the Hunting Grounds) has a set capacity. Only one tribe can occupy a place at a time. And if your tribe occupies the space, you cannot add more people from your tribe later.

'''<u>Variations Based on Number of Players</u>'''

'''''Two Players'''''

Only 2 out of 3 places in the village (''Tool Maker (tools)'', ''Hut (gain worker)'', and ''Field (increase food production)'') may be occupied per turn.

Only 1 player may place people in any of the resource areas (''Forest'' (wood), ''Clay Pit'' (brick), ''Quarry'' (stone), and ''River'' (gold)).

'''''Three Players'''''

Only 2 out of 3 places in the village (''Tool Maker (tools)'', ''Hut (gain worker)'', and ''Field (increase food production)'') may be occupied per turn (like a two-player game).

Only 2 player may place people in any of the resource areas (''Forest'' (wood), ''Clay Pit'' (brick), ''Quarry'' (stone), and ''River'' (gold)).

==== Phase 2: Remove People and Gain Resources====

In turn order, each player removes their people from each place and gains/pays for the benefits of that place.

The following formula determines the number of resources received: For each worker placed, a die is rolled. The total of all dice is divided by the resource's "value" (the rarer the resource, the higher the number). The resulting whole number (remainder ignored) is the total resources received.

'''<u>Places</u>'''

{| class="wikitable" style="width:auto;" border="2"
!| Name || Resource || Capacity || Description
|-
| '''Hunting Grounds''' || Food || -- || Roll dice equal to # of workers placed. Dice total ÷ '''2''' = # of food received
|-
| '''Forest''' || Wood || 7 || Roll dice equal to # of workers placed. Dice total ÷ '''3''' = # of wood received
|-
| '''Clay Pit''' || Brick || 7|| Roll dice equal to # of workers placed. Dice total ÷ '''4''' = # of bricks received
|-
| '''Quarry''' || Stone || 7 || Roll dice equal to # of workers placed. Dice total ÷ '''5''' = # of stones received
|-
| '''River''' || Gold || 7 || Roll dice equal to # of workers placed. Dice total ÷ '''6''' = # of gold bars received
|-
| '''Tool maker''' ||Tool || 1 || Gain a tool. Each player can only have 3 tools, but each can be upgraded (up to 3 times) by placing a worker here.
|-
| '''Hut''' ||+1 Worker || 2 || Gain 1 worker. ''Exactly'' 2 people must be placed here. Max of 10 workers.
|-
| '''Field''' ||+1 food production || 1 || Increase your food production by 1.
|-
| '''Buildings''' ||Buy buildings || 7 || Buy buildings with resources. Buildings are worth VP.
|-
| '''Civilization''' || Civilization card || 1 || Pay the # of resources based on its slot to gain its immediate effect and scoring benefits.
|}

'''<u>Tools</u>'''

Tools are used to increase the number of resources gained. By using the tool, its value (1-4) is added to the dice total. Each tool can only be used once per turn. The whole value of the tool must be used (i.e. you cannot add less than 4 to a total when using a level 4 tool). Some Civilization cards grant "single-use" tools. These are lost after use and don't count for scoring.

'''<u>Buildings</u>'''

Pay the cost to gain the Building and receive the points listed in the top-left corner. If this number is a ?, points are equal to the total value of the resources used to acquire this building.

{| class="wikitable" style="width:auto;" border="2"
!| Resource || Value
|-
| '''Wood''' || 3
|-
| '''Brick''' || 4
|-
| '''Stone''' || 5
|-
| '''Gold''' || 6
|}

'''<u>Civilization Cards</u>'''

Each card has an ''immediate effect'' (usually granting a resource) and a ''scoring multiplier''. See '''End Game''' for how Civilization Cards are scored.

==== Phase 3: Feed People====

To feed your people, you must be able to discard enough food equal to # of workers minus food production number. If you have less food than this, you may substitute any resource. If you still don't have enough for your workers, you lose all food and are given a -10 point penalty.

====Ending the Round====

All Civilization Cards are moved to the right and new cards are put in the empty spaces. The next player becomes the starting player and a new round begins.

==Game End==

The game ends when either:

<ul class="bulletlist" style="margin:1em 0;padding-inline-start:40px;">
<li>One stack of buildings is empty when a round ends. (The number of building stacks is equal to the number of players).</li>
<li>There are insufficient Civilization Cards to fill each slot when a round begins.</li>
</ul>

====Scoring====

Civilization Cards with a '''green''' lower background are culture cards. They have 1 of 8 different symbols. At the end of the game, score is determined by grouping cards into sets with all different symbols, squaring the number of cards in each set, and adding them together. For example, a player has 1 card with a tablet, 1 card with pottery, 2 cards with a sundial, and 3 cards with a loom. This forms one set of four symbols (tablet, pottery, sundial, loom), one set of two symbols (sundial, loom) and one set of one symbol (the third loom). The player scores 16 (4²) for the first set, 4 (2²) for the second set and 1 for the third set, for a total of 21 points.

Civilization Cards with a '''sand''' background are specialized workers: farmers, tool makers, hut builders, and shamans. These are scored as follows:

<ul class="bulletlist" style="margin:1em 0;padding-inline-start:40px;">
<li># of cards with ''farmers'' x food production number</li>
<li># of cards with ''tool makers'' x total value of tools</li>
<li># of cards with ''hut builders'' x # of buildings</li>
<li># of cards with ''shamans'' x workers</li>
</ul>

The total from Civilization Cards is added to the VP printed on your buildings, plus 1 point for each remaining resource.

== Variants ==
====Harsh Winter====

<ul class="bulletlist" style="margin:1em 0;padding-inline-start:40px;">
<li>Certain buildings allow you to spend an extra stone to score 5 points.</li>
<li>You can spend an extra gold when purchasing a Civilization Card to score 6 points.</li>
</ul>

====Wild Animals====

<ul class="bulletlist" style="margin:1em 0;padding-inline-start:40px;">
<li>Four "wild animal" cards are shuffled into the Civilization Cards.
<ul class="bulletlist" style="padding-inline-start:40px;">
<li>When revealed, wild animals subtract 1, 2, or 3 from all dice rolls.</li>
<li>Players must collectively place X people on the card to drive it off, where X = number of players.</li>
<li>After driving off a wild animal, each player rolls 1 die per person placed on it and receives the rewards.</li>
</ul></li>
</ul>

====Igloos====

<ul class="bulletlist" style="margin:1em 0;padding-inline-start:40px;">
<li>Spend 3 resources of the same type to buy an igloo, which awards points like a building but does not count for the end-game building bonus.
</ul>

====The New Huts====

<ul class="bulletlist" style="margin:1em 0;padding-inline-start:40px;">
<li>Adds new buildings that grant fewer points when built but grant a bonus, such as gaining a resource each round or +1 worker/tool/food production). These do count for the end-game building bonus.
</ul>

====Mammoth Herd====

<ul class="bulletlist" style="margin:1em 0;padding-inline-start:40px;">
<li>At the beginning of each round, a mammoth appears on the place shown by the top-most bonus tile.
<li>Players who place people there can spend 1 food or resource per person to try to tame the mammoth.
<li>Each player who places people to tame the mammoth rolls 1 die per person.
<li>The player with the highest single die is the "mammoth tamer". The mammoth tamer can choose to take the "1" or "all" bonus, as shown on the back of the bonus tile.
<li>The other players who rolled are "challengers". Challengers take the "all" bonus.
<li>At the end of the game, the player with the most mammoth tiles scores 10 points.<li>2 or 3 players game: all players might place workers at the mammoth location (the 2p/3p game limitation is cancelled at the mammoth location).
</ul>

====The Expansion====

<ul class="bulletlist" style="margin:1em 0;padding-inline-start:40px;">
<li>'''New Good:''' Jewelry
<ul class="bulletlist" style="padding-inline-start:40px;">
<li>1 tooth = 1 jewelry, 1 ring = 3 jewelry</li>
<li>Jewelry does not count as a resource or food</li>
<li>A player can trade resources '''or''' jewelry for buildings and Civilization Cards
<li>Jewelry is acquired at the Hunting Grounds and has the same value as food. You ''can'' gain a combination of food and jewelry
</ul>
<li>'''New Place:''' Merchant
<ul class="bulletlist" style="padding-inline-start:40px;">
<li>Like the hut, this place requires exactly 2 people and is worth no points at the end of the game.</li>
<li>When this place is used, you gain 2 jewelry and your merchant level increases by 2. This represents the player's ability to trade.</li>
<li>The merchant exists in the village. In a 4-player game, only 3 of the 4 places can be visited. Rules for the 2-3 player game remain the same (only 2 village spaces can be visited per round).
</ul>
<li>'''New Mechanic:''' Trading
<ul class="bulletlist" style="padding-inline-start:40px;">
<li>A player can trade resources/jewelry once per round, regardless of whether they put any workers on the merchant
<li>A player can only trade in order to buy a Civilization Card or a building (except for an igloo)
<li>If also playing with the ''Harsh Winter'' variant, the extra stone/gold cannot be obtained with a trade
<li>The ratio of goods traded depends on your merchant level.
<li>A player cannot trade if their merchant level is 0. (Meaning the merchant must be visited at least once before any trading can occur.)
</ul>
<li>'''New Civilization Card slot'''
<ul class="bulletlist" style="padding-inline-start:40px;">
<li>There is now a fifth slot for Civilization Cards. Cards here cost 3 jewelry.
<li>A player can spend 3 more jewelry to buy the topmost face-down Civilization Card without applying its immediate effect.</li>
</ul>

BGA Code Sharing

2026-04-21T17:05:28Z

Inaofr: /* Projects on studio */ Add d case (Stone Age case, een asked me to not make it public for this reason)

{{Studio_Framework_Navigation}}

This page is for listing of externally hosted bga projects, tools and resources, as well as internal project
intended for sharing

== Community shared components, pens, etc ==

{| class="wikitable"
|-
! NAME
! CODE LINK
! DESCRIPTION
|-
! colspan="3" | Dice models and animation
|-
| Die: 4 sided
| https://codepen.io/mrkiffie/pen/doVZgW ; https://codepen.io/VictoriaLa/pen/JjZNezr
| code pen
|-
| Die: 6 sided
| https://github.com/elaskavaia/bga-sharedcode ; https://codepen.io/VictoriaLa/pen/QWBBbwz
|
|-
| Die: 8 sided
| https://codepen.io/VictoriaLa/pen/YzMPeGq
| code pen
|-
| Die: 12 sided (dodecahedron)
| https://codepen.io/VictoriaLa/pen/xxLLxOP <nowiki/> https://codepen.io/hoursgoby/pen/GRwQzxo
| Code pen
|-
| Die: 20 sided
| https://codepen.io/vicentemundim/details/cenIh
| Code pen
|-
! colspan="3" | Moving object using CSS animation (mostly)
|-
| Phantom object move on oversurface
| https://codepen.io/VictoriaLa/pen/gORvdJo
| This technique creates clone of the object it moves it on another surface. It works well when parents that css transform applies such as scale and rotate
|-
| Move object directly using positioning
| https://codepen.io/VictoriaLa/pen/dyzgKVX
| This technique is modification of BGA framework method to allow mobile object not to have absolute position before or after the move (and uses css animation not dojo). Methods slideToObjectRelative, attachToNewObjectNoDestroy
|-
! colspan="3" | Responsive layout, zoom and navigation for game boards
|-
|Flex Layout
|https://codepen.io/VictoriaLa/pen/XWjJJgG
|Example on how to create flexible layout just by using css
|-
|Zoom
|[https://github.com/thoun/bga-zoom/ Repo]<nowiki> | </nowiki>[https://thoun.github.io/bga-zoom/demo/index.html Demo] (visible on Knarr, Azul, Abyss, ...)
|Allow the user to zoom on the game board. Include the controls to zoom, and handle the scale applied to the HTML element.
|-
|Jump to
|[https://github.com/thoun/bga-jump-to/ Repo]<nowiki> | </nowiki>[https://thoun.github.io/bga-jump-to/demo/index.html Demo] (visible on Knarr, Elawa)
|Add floating controls to quickly jump to a player's table
|-
! colspan="3" | Algorithms
|-
|Hex grid
|tapestry,Tumbleweed,gaia project,Gold West
|
|-
|Shortest path on hex grid
|memoir 44
| Dijkstra
|-
|Largest area on hex grid
|tapestry, ...
|
|-
|Largest area on square grid
|king domino, ...
|
|-
|Tetris pieces
|patchwork, ...
|Matrix manupations to rotate, flip and fit tetris pieces
|-
|Line of sights on hex grid
|memoir 44
|Find intersecting hexes on a line between two cells
|-
! colspan="3" | Alternative implementations of BGA modules
|-
|Scrollmap with zoom
|https://github.com/yansnow78/bga_scrollmap
|you can find it in cacao, ginkgopilis, sagani, bigmonster,dominoes, Carcassonne hunters and gatherers and many others. <nowiki>#</nowiki> improvements compare to scrollmap:
- add zoom capabilities

- add possibility to adjust pan delta to tile size when clicking on arrows

- allow zoom with scroll wheel. only allow zoom with wheel if alt or ctrl or shift are pressed by default. add possibility to select which key need to be pressed when zooming with wheel

- allow pan/scroll and pinch zoom on smartphone. only allow 2 fingers to start scrolling by default, one finger is for page scrolling

- make clickable area of buttons a bit bigger on smartphone

- improve animation between game board and player bards thanks to an animation_div

- add support to long click on buttons (continuous scroll or zoom or enlarge/reduce until button released)
|-
|Scrollmap Plus
|patchwork
|Implementation with some bugs fixed, improved drag support and ability to use only one direction (i.e. only horizontal like carousel). Found in modules/extscrollmap.js
|-
! colspan="3" | Assorted stuff
|-
|Help
|[https://github.com/thoun/bga-help/ Repo]<nowiki> | </nowiki>[https://thoun.github.io/bga-help/demo/index.html Demo] (visible on Knarr)
|Add floating help buttons at the bottom left corner of the screen

|}

== Projects ==

Add the game name, a link to repository and nickname of the developer on bga (same as used for dev forum), and short description. See [[Tools_and_tips_of_BGA_Studio#Version_Control]] for some suggestions on how and where to publish your code externally. Also see the [https://github.com/topics/boardgamearena boardgamearena] topic on github.

'''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
! COMMENT
|-
| Shared Code (not a game)
| https://github.com/elaskavaia/bga-sharedcode
| Victoria_La
| Examples of various game components and PHP stubs of framework code to make IDE happy
|-
| Vanilla Typescipt template (not a game)
| https://github.com/elaskavaia/bga-dojoless
| Victoria_La
| Project template for typescript and using minimal dojo, good for vscode - type checking, auto-complete, navigation
|-
| BoardGameArena Workbench (not a game)
| https://github.com/danielholmes/bga-workbench
| Daniel Holmes (dhau)
|-
|BGA-boilerplate
|https://github.com/bga-devs/tisaac-boilerplate/
|Tisaac (and Vincentt ?)
|Main boilerplate with extended "basic" function and code structure
|-
|BGA Type Safe Template
|https://github.com/NevinAF/bga-ts-template
|NevinAF
|Full typing of all BGA Framework components.
|-
|Undo functionality
|https://github.com/Ginso/UndoFunctions
|Ginso
|Code for adding undo functionality that also allows undoing single actions and not just the whole turn.
Also contains a class that wraps DB functions and adds a parsing functionality for numbers, bools and json
|-
! GAME
! CODE LINK
! DEVELOPER
! COMMENT
|-
| 99 (Trick-taking Card Game)
| https://github.com/ekelly/bga-ninetynine
| QuasarDukeDev
|-
| Abandon All Artichokes
| https://github.com/0-wiz-0/bga-abandonallartichokes
| __wiz__, rojomojo
|-
| Assyria
| https://github.com/sebastien-prudhomme/bga-assyria
| daikinee
|-
| Aura
| https://github.com/micahstairs/bga-aura
| Micah Stairs (micahstairs)
|-
| Bandido
| https://github.com/opheliehb/BandidoBGA
| ophelopede & Harkle
|-
| The Battle for Hill 218
| https://github.com/danielholmes/battle-for-hill-218
| Daniel Holmes (dhau)
|-
| Bonbons
| https://github.com/AntonioSoler/bga-bonbons
| Morgalad
|-
|Big Monster
|https://github.com/nmatton/bigmonster
|nicotacotac
|-
| Bonsai
| https://github.com/PhilipDavis/BGA-Bonsai
| Philip Davis (pdw3)
| Action stack for client-side undo system; generator functions to model complex turn workflows; infinite hex grid with auto resizing; all data in a single JSON blob; animated scorepad
|-
| Canosa
| https://codeberg.org/halibut/Canosa
| junibegood
|-
|Cóatl
|https://github.com/AbelTiborToth/bga-coatl
|Doctor Neo Cortex
|-
| Coinche
| https://github.com/drasill/bga-coinche
| Draasill
|-
|Copenhagen
|https://github.com/JoeProgram/bga-copenhagen
|JoeProgram
|-
| Coup: City State
| https://github.com/quietmint/bga-coupcitystate
| quietmint
|-
|Deep Regrets
|https://github.com/JamesGames7/bga-deepRegrets
|JamesGames7
|-
|Dice Hospital : Emergency Roll
|https://github.com/firgon/dicehospitaler
|firgon
|-
| Dice Summoners
| https://github.com/eoincos/bga-dicesummoners
| eoincos
|-
| Dungeon Roll
| https://github.com/MartinGoulet/bga-dungeonroll
| MGoulet
|-
| Egyptian Ratscrew
| https://github.com/0BuRner/bga-egyptianratscrew
| 0BuRner
|-
| Eruption
| https://github.com/AndyKerrison/bga-eruption
| Andy_K
|-
| A Fistful Of Gold
| https://bitbucket.org/Joel_L/fistfulofgold
| Brainchild
|-
| Fled
| https://github.com/PhilipDavis/BGA-Fled
| Philip Davis (pdw3)
| All data in a single JSON blob
|-
|Flip Freighters
|https://github.com/joesimpson/bga-flipfreighters
|joesimpson
|-
| Florenza: The Card Game
| https://github.com/alberto-bottarini/bga-florenza
| tarini
|-
| For-Ex
| https://github.com/Fnordistan/forex
| AmadanNaBriona
|-
| Get the MacGuffin
| https://github.com/mizutismask/bga-get-the-MacGuffin
| mizutismask
|-
| Hardback
| https://github.com/quietmint/bga-hardback
| quietmint
|-
| Hearts '''(Tutorial)'''
| https://github.com/elaskavaia/bga-heartsla
| Victoria_La
|
|-
| Homesteaders
| https://github.com/npatron/bga-homesteaders
| TheBoot
|-
| Incan Gold
| https://github.com/AntonioSoler/bga-incangold
| Morgalad
|-
| In the Year of the Dragon (10th Anniversary Edition)
| https://github.com/Fnordistan/ityotd
| AmadanNaBriona
|-
| Just Desserts
| https://github.com/mizutismask/bga-just-desserts
| mizutismask
|
|-
| The King's Guild
| https://github.com/AdamNovotny/BGG-KingsGuild
| A-dam
|-
| The Lady and the Tiger (Doors)
| https://github.com/Fnordistan/ladyandthetiger
| AmadanNaBriona
|-
|Linkage
|https://github.com/ShaPhi7/linkage
|ShaPhi7
|
|-
|Love Letter
|https://github.com/ShaPhi7/loveletter
|ShaPhi7
|
|-
| Mapmaker: The Gerrymandering Game
| https://github.com/gzhang01/bga-mapmaker
| gkz
|-
| Marco Polo
| https://github.com/rcitaliano/MarcoPolo
| rcitaliano
|
|-
| Monster Lands
| https://github.com/JamesGames7/bga-monsterlands
| James_Games
|
|-
| Nile
| https://github.com/AndyKerrison/bga-nile
| Andy_K
|-
|Ninjan
|https://github.com/dorukkicikoglu/bga-ninjan
|fenadoruk
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
|Now Boarding
|https://github.com/quietmint/bga-nowboarding
|quietmint
|-
|Odin
|https://github.com/dorukkicikoglu/bga-odin
|fenadoruk
|-
| Penny Press
| https://github.com/AdamNovotny/bga-blooms
| A-dam
|-
| Perikles
| https://github.com/Fnordistan/perikles
| AmadanNaBriona
|
|-
| P.I.
| https://gitlab.com/fa81/bga-pi, https://github.com/hellp/bga-pi (mirror)
| Fabian Neumann (fa81)
|-
| President
| https://github.com/quaresma95/president
| quaresma95
|-
| Santorini
| https://github.com/AntonioSoler/bga-santorini
| Morgalad, quietmint, Tisaac
|-
| Tablut
| https://github.com/Lucas-C/tablut
| Lucas-C & ntaffore
|-
| Takara Island
| https://github.com/AntonioSoler/bga-takaraisland
| Morgalad
|-
| Taluva
| https://github.com/quietmint/bga-taluva
| Morgalad & quietmint
|-
| Teotihuacan: City of Gods
| https://github.com/Trompetenhut/bga-teotihuacan
| Trompetenhut
|-
| Texas 42 (domino game, still under development)
| https://github.com/ishermandom/bga-42
| Stardust Spikes, Jason Turner-Maier, Ilya Sherman
|-
| Tic Tac Match
| https://github.com/leocaseiro/bga-tictacmatch
| Leo Caseiro
|-
| Trick of the Rails
| https://github.com/Fnordistan/trickoftherails
| AmadanNaBriona
|-
| Uptown
| https://github.com/elliotkendall/bga-uptown
| SpottedShroom
|-
| Via Magica
| https://github.com/christopherburke/bga_viamagica
| CuriousTerran
|-
|}

== Projects on studio ==

Any developer can add themselves to a project as read-only from https://studio.boardgamearena.com/#!projects page (almost any project).

If it is not visible: a) it has no bgg id b) it is already published (use radio button to switch) c) it is an old game not developed on studio d) it is an old game which code should not be copied.

== Other useful resources ==

Moved to [[Tools_and_tips_of_BGA_Studio]]

[[Category:Studio]]

Bugsclarification stoneage

2026-04-04T15:45:32Z

Inaofr:

Please do not report if your bug match one of the followings.

A frequent "won’t fix": sometimes you are not notified of a game update because of a lost message over the Internet. It can results in wrong situation display and in not being notified that it is your turn to play. These is linked to BGA framework and will not be fixed at the Stone Age code level. Please upvote this BGA website [https://boardgamearena.com/bug?id=201639 report].

Here is a list of frequent "not a bug" reports: the user was just not knowing the actual rule.
* Can not put a worker at x place: check the placement limitation rules for two or three players game (and even four players if you are using the trade expansion).
* Did not get the two (might be one with the trade expansion) wild resources of the civilization card: you got it on your player board, you have to click on the wild resource icon to choose them.
* Did not get the card bonus in game: when buying a card face down, you receive only the end game bonus, not the in game bonus.
* Did not get the free wood/clay/stone of the bought hut (new huts expansion): the free resource is not granted at buy but at start of each following turns.
* Could not insulate bought hut (harsh winter variant): only huts of the standard game and costing three defined resources (not wild resources) can be insulated.
* Can not trade to buy an igloo: trade is allowed to buy a hut or a card, igloos are not huts nor cards.
* Can not trade to buy hut or card, different normal causes here:
** you can trade only one time per game turn (a game turn ends when all workers have been removed from playing area),
** the 2:1, 1:1 or 1:2 trade indicator (depending on your trade level) is not a trade rate, but a trade possibility: for instance for the 1:1, you can trade one resource and only one against another one, you can not trade two or more against the same number,
** you can not trade one resource against itself, even at trade level 9 or 10 (1:2 trade possibility: you can not trade one wood against one wood and one stone for instance).
* Did not get the second resource in my 1:2 trade: all resources gain in a trade are used in the linked buy, even if not needed for it, and it does not add points and can not be used to insulate or pay an extra gold in harsh winter variant.

BGA Studio Migration Guide

2026-02-24T22:30:25Z

Inaofr: /* Deprecated translation functions */ clienttranslate is not working in view.php file, all formatting have to be done through notify or UserException formatting or be removed from PHP and rewrote in JavaScript.

This page is only for people who started long time ago and now need to re-write older projects into more modern versions.
Also if you trying to fix older game you may have to look here.

==Overview==
See announcement here https://studio.boardgamearena.com/forum/viewtopic.php?f=12&t=45248

📌 This symbol: direct information about migration
== Structural changes==

'''''gameoptions.inc.php''''' => gameoptions.json, gamepreferences.json

Previously, options and preferences were specified in a single gameoptions.inc.php file.

Now options and preferences are 2 json files, follow Migration steps on this page https://en.doc.boardgamearena.com/Options_and_preferences:_gameoptions.json,_gamepreferences.json#Migration

See [[#User preferences]] and [[#Game options]] for API changes.

When building the game with this file you will see deprecation warning: The file gameoptions.inc.php is deprecated. click "Reload game options configuration" to generate the JSON content you can then put on a gameoptions.json and gamepreferences.json file. Then you can safely delete the gameoptions.inc.php file.

'''''<gamename>.game.php''''' => modules/php/Game.php

Move and refactor, see section [[BGA Studio Migration Guide#Namespaced game class|Namespaced game class]]

'''<gamename>.action.php => remove'''

See section [[BGA Studio Migration Guide#Autowire game actions|Autowire game actions]]

'''''<gamename>.view.php, <gamename>_<gamename>.tpl''''' => remove

See section [[BGA Studio Migration Guide#Removal of view and template|Removal of view and template]]

'''gameinfos.inc.php'''

File still there. Deprecated keys '''designer''', '''artist''', '''year''', '''presentation''', '''tags''', '''complexity''', '''strategy''', '''luck''', '''diplomacy''', '''is_beta''' are no longer in use. Please remove these keys and use the Game Metadata Manager instead.

'''''material.inc.php''''' => optional

See section [[#Material]]

'''''states.inc.php''''' => modules/php/States

See section [[#States]]

'''stats.inc.php''' => stats.json

Deprecation warning: The file stats.inc.php is deprecated. click "Reload statistics configuration" to generate the JSON content you can then put on a stats.json file. Then you can safely delete the stats.inc.php file.

'''<gamename>.js'''

Equivalent file is in modules/js/Game.js, it is ES6 js class (yay) and no dojo mess.
There are also massive API changes, see bottom sections

==IDE Support==
A new _ide_helper.php file is now provided in every project dir, allowing IDE to provide syntax error highlighting for the framework functions. This file is regularly updated to match the latest framework updates.

Same with bga-framework.d.ts for those using TypeScript.

📌 Sync the files from the FTP dir to your local copy to benefit from it. Most of the IDE like Visual Studio Code should handle _ide_helper.php if you already followed https://en.doc.boardgamearena.com/Setting_up_BGA_Development_environment_using_VSCode

==Game configuration ==

===User preferences===

Access to user preferences and listener: https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#User_preferences

📌
*If you had a custom function called <code>setupPreferences()</code> reading the <select> values, you can now use <code>onGameUserPreferenceChanged</code> instead.
*If you had a copy of the user preferences on a DB table, it's not needed anymore. Remove all support of writing to this table. Replace access to this table with
$pref = $this->userPreferences->get($playerId, $prefCode) ?? $defaultValue;
*If you used $this->player_preferences - replace the use with use of proper API

====Instant cssPref on user preferences====
A reload is not needed anymore to apply cssPref on a user preference change.

📌 Remove forceReload: true if it was only set to update the cssPref. The player will appreciate to not reload the whole page!

===Game options===

New functions to access the table options (game options) without hassle

https://en.doc.boardgamearena.com/Options_and_preferences:_gameoptions.json,_gamepreferences.json#Game_Options

📌
*Remove declaration of game options from "<code>initGameStateLabels</code>"
* Instead of using <code>$this->getGameStateValue</code> or <code>$this->gamestate->table_globals</code> use
$this->tableOptions->get(int $optionId)

This new object can also return the Real-time/Turn-based setting: https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Reflexion_time

==Server parts (php, sql, etc)==

===PHP migration===

Oct 2025: The migration was made from PHP7.4 to PHP8.4 new syntax and functions.

New projects are generated using the strict mode

📌

*Replace all <code>self::</code> to <code>$this-></code> - The new project template has been updated to remove this bad practice (that may be unsupported in a future PHP version)

*Add <code>declare(strict_types=1);</code> to all .php files and fix compiler warnings (if you use IDE it will detect it before upload).

===Namespaced game class===
Game class from '''''<gamename>.game.php''''' are now namespaced (and moved to modules/php/Game.php) and can autoload other classes of the same namespace

[[Main game logic: Game.php#Creating other classes]]

📌 The class file should be moved to modules/php/Game.php and adopted

(In examples below YourGameName is NOT verbatim its your game name)

* Move YourGameName.game.php to modules/php (create this dir if does not exists)
* Rename to Game.php
* Find the place below the copyright and add

declare(strict_types=1);
namespace Bga\Games\YourGameName;

* Remove
require_once APP_GAMEMODULE_PATH . "module/table/table.game.php";

* Find you class declaration change YouGameName to Game (verbatim) and change extends

class Game extends \Bga\GameFramework\Table

* All references to non-namespaced classes in this file should be defined on top of the file with "use", for example "use \BgaUserException;" as it is this non-namespaced exception is used in the zombieTurn function.

* All includes with relative path will need to be updated too.

* The material.inc.php to have be moved and included directly (see below)

Multiple functions of "Table" base class are now deprecated, see how to migrate in corresponding section

* notifyAllPlayers
* notifyPlayer
* mysql_fetch_assoc
** Deprecation warning: mysql_fetch_assoc function detected. It is deprecated, and may be removed someday. Please replace it by standard framework DB functions!
* Table (class access without namespace)
* isMutiactiveState (misspelled version)
* State management functions (getState, state, getPrivateState)
* Player information functions (getActivePlayerName, getCurrentPlayerName, getCurrentPlayerColor)
* Game mode functions (isAsync, isRealtime)
* Exception classes (feException, BgaUserException, etc.)
* ...

===Material===
Material file '''material.inc.php''' is now optional. You can define all your material directly in php class. If you still like to keep it, and using namespaced Game.php you have to move it to subfolder and include directly [[Game material description: material.inc.php#Move it to modules/php]]

=== Autowire game actions===
Simplify the action calls by removing '''<gamename>.action.php''' file

https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Actions_%28autowired%29

📌 Autowired actions needs to start with "act", so it's risky to change them (if you change all actions names in the states.php, game, action and JS file, Real-time players will call the old name until they refresh. So, it needs to be done in two steps with duplicates on back side, or to be deployed when there is no Realt-time table running.

When migration is done, the action.php file can be deleted.

Deprecation warning: Actions detected on .action.php file. You can now use [[Main game logic: Game.php#Actions (autowired)|Auto-wired actions]] to avoid pass-through functions in .action.php file. If you transform your project to use only auto-wired actions, you can then delete the .action.php file.

=== Notifications===
Functions notifyAllPlayers and notifyPlayer from main game.php are deprecated

📌 Replace <code>$this->notifyAllPlayers</code> with <code>$this->bga->notify->all</code>
and Replace <code>$this->notifyPlayer</code> with <code>$this->bga->notify->player</code>

====Notification Decorators====
New notify function that handles decorators, reducing the duplicate code on notification args.

https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Notification_decorators

====Notification args consistency====
Previously, when you sent an arg that was transformed by format_string_recursive or bgaFormatText, the args object was mutated and you got the transformed value in the notif_ handler.

The solution was to send the values in 2 different names like this:

[
'roundNumber' => $roundNumber, // number, to update the round counter
'round_number' => $roundNumber, // number that will be transformed to string by bgaFormatText, when shown in bold in the logs
]
📌 Do not duplicate the value, as the notif_ handler will now get unmutated args

===Deprecated getGameName===
The getGameName() function is now useless in the Game PHP file and can be deleted

📌 Delete the getGameName function in the Game PHP file.

Deprecation warning: getGameName function detected. It is deprecated. You can delete it, it is not used anymore

===State Management Functions===
Several state-related functions have been deprecated in favor of more explicit methods:

📌
* Replace <code>$this->gamestate->state()</code> with <code>$this->getCurrentMainState()</code> or <code>$this->getCurrentState(int $playerId)</code>
* Replace <code>$this->getState()</code> with <code>$this->getCurrentMainStateId()</code> or <code>$this->getCurrentStateId(int $playerId)</code>
* Replace <code>$this->getPrivateState($playerId)</code> with <code>$this->getCurrentState($playerId)</code>
* Replace <code>$this->gamestate->states</code> access with <code>$this->getCurrentMainState()</code> or <code>$this->getCurrentState(int $playerId)</code>
* Replace <code>$this->isMutiactiveState()</code> (misspelled) with <code>$this->isMultiactiveState()</code>

===Player Information Functions===
Several functions for getting player information are deprecated in favor of more flexible methods:

📌
* Replace <code>$this->getActivePlayerName()</code> with <code>$this->getPlayerNameById($activePlayerId)</code> using $activePlayerId magic parameter
* Replace <code>$this->getCurrentPlayerName()</code> with <code>$this->getPlayerNameById($currentPlayerId)</code> using $currentPlayerId magic parameter
* Replace <code>$this->getCurrentPlayerColor()</code> with <code>$this->getPlayerColorById($currentPlayerId)</code> using $currentPlayerId magic parameter

===Game Mode Functions===
Functions to check game mode (turn-based vs real-time) have been moved to tableOptions:

📌
* Replace <code>$this->isAsync()</code> with <code>$this->tableOptions->isTurnBased()</code>
* Replace <code>$this->isRealtime()</code> with <code>$this->tableOptions->isRealTime()</code>

===Exception Classes===
Old exception classes are deprecated in favor of namespaced versions:

📌
* Replace <code>feException</code> with <code>\Bga\GameFramework\UserException</code>, <code>\Bga\GameFramework\SystemException</code>, or <code>\Bga\GameFramework\VisibleSystemException</code> depending on your need
* Replace <code>BgaUserException</code> with <code>\Bga\GameFramework\UserException</code>
* Replace <code>BgaSystemException</code> with <code>\Bga\GameFramework\SystemException</code>
* Replace <code>BgaVisibleSystemException</code> with <code>\Bga\GameFramework\VisibleSystemException</code>
* Remove usage of <code>FEX_NOCODE</code> constant - new exception classes don't need error codes

===Namespace for Base Classes===
Old class references without namespaces are deprecated:

📌
* Replace <code>extends Table</code> with <code>extends \Bga\GameFramework\Table</code>
* Replace <code>Deck</code> with <code>\Bga\GameFramework\Components\Deck</code>

=== Deprecated APP_* Classes ===
Deprecation warning:

Reference to old APP_* class detected.

We recommend you to use composition instead of extend:

Pass `private Game $game` in the constructor of your object that need to access Table functions

If it's too complicated, at least replace APP_Object/APP_GameClass by APP_DbObject as APP_Object/APP_GameClass may be removed soon and don't contain anything more than APP_DbObject.

Don't hesitate to ask for help in the Dev Discord or in the Dev forum if you don't know how to do it!
class Tokens extends APP_GameClass {
becomes:
class Tokens extends \APP_DbObject {

=== Deprecated translation functions ===

On php side translation story is simplified

* totranslate function is not longer needed and can be replaced with clienttranslate
* $this->_() (or self::_()) can also be replaced with clienttranslate when use for non parameterized strings (but not in deprecated <game>.view.php file):

throw new UserException(clienttranslate('You must choose 3 cards'));

UserException is also handling parameterized strings like the notify functions.

All parameterized strings on PHP side have to use either the notify or the UserException formatting. If some parameterized strings are none of these, you have to remove them from PHP and rewrote them in JavaScript using dojo.string.substitute.

See [[Translations]]

=== Deprecated getNew ===
Function getNew that was only used to create new deck object is now deprecated, use $this->deckFactory->createDeck('') instead

=== Stats ===

The stats function such as initStat, setStat and getStat are also deprecated in favor of access via the objects <code>$this->tableStats and $this->playerStats</code>
See https://en.doc.boardgamearena.com/index.php?title=Main_game_logic:_Game.php#Game_statistics

===Legacy===
New object to access the legacy functions, removing the need to manually decode the JSON result when getting the values.

[[Main game logic: Game.php#Legacy games API|https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Legacy_games_API]]

📌 Use $this->legacy->actionname instead of $this->actionnameLegacy and remove JSON decoding on getters

===Any Globals===
New database table and API to handle any type variables instead of numerical values only

https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Use_globals

📌 If you had custom tables just for that you can drop them and use standard table

=== Server Counters ===
2 new counter classes have been added to easily handle the various counters your game might have. You also have 2 prebuilt counters: playerScore and playerScoreAux, to handle the scoring values, so you don't need to update manually the DB when setting the scores.

https://en.doc.boardgamearena.com/PlayerCounter_and_TableCounter

📌 Replace setting player_score/player_score_aux using db queries with use of $this->playerScore and $this->playerScoreAux. Remove the notifications, or part of notifications, updating the player panel score counter (if you had some custom notification you may still need them).
===Updated Zombie Mode documentation and recommendations===
We now recommend making the zombie player playing randomly, instead of passing as a default. A new "Zombie Mode level" field has been added to the Game Metadata Manager, to indicated the Zombie Mode you implemented in your game.

https://en.doc.boardgamearena.com/Zombie_Mode

===View and template files: deprecated===
'''''<gamename>.view.php, <gamename>_<gamename>.tpl''''' are now optional and are not generated anymore on a new project. The new project templates demonstrate how to work without them.

📌 The DOM should be built on the JS side to remove the view/template files, so it can be complicated for old projects using them intensively. It would look like this:
this.getGameAreaElement().insertAdjacentHTML('beforeend', `
<nowiki><span>${_('My translated text')}</span></nowiki><nowiki><div id="player-tables"></div></nowiki>
`);

See more in [[#Access template elements]]

====Forbid access to global BGA variables and direct DB access on action/view files====
If you did not remove action and view files, you cannot longer use some stuff in them, such $g_user global and db access functions.

A new getCurrentPlayerId() function has been added to those action/view classes for easier migration

📌 Replace $g_user->get_id() by $this-> getCurrentPlayerId()

Replace DB calls by $this->game->DbQuery() (and such...)

===States===
There is now a way to describe each game state in a State class, that will handle all logic and description of the state. It helps splitting the code into multiple files, instead of one big Game.php file.

https://en.doc.boardgamearena.com/State_classes:_State_directory

📌 Create a State class for each state of the game (except 1 and 99 if they are still described in states.inc.php), move the state definition in it, and adapt the "st", "arg", "actXXX" and "zombie" functions in the class. When all classes are migrated, you can remove the states.inc.php file in the FTP folder.

==== If still using states.php====
The new class GameStateBuilder helps you build the state machine, allowing auto-completion, and avoid typo errors on state types. Complete example: 📌 https://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php

States 1 and 99, that must not be changed, are now optional.

📌 Replace the array definition by GameStateBuilder use. You can remove the declaration of states 1 and 99.

Note: it's only useful if you don't migrate to State classes described above

==Client parts (js, html, css) ==
===Main class===
File is moved from yourgamename.js to modules/js/Game.js and has a different structure
https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js
It won't be easy to convert this, maybe best just to use old one which still works, but move when you write a new game.

===Deprecated ajaxcall ===
Introduced function bgaPerformAction to replace ajaxcall and checkAction combination, with a simpler syntax:

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Actions

Deprecation warning: The <code>ajaxcall</code> function is deprecated, check [[/en.doc.boardgamearena.com/Game interface logic: yourgamename.js#Actions|the]] <code>bgaPerformAction</code> [[/en.doc.boardgamearena.com/Game interface logic: yourgamename.js#Actions|function]].

📌 Replace combination of checkAction/ajaxcall by bgaPerformAction. Beware of the options (3rd param) if it was an ajaxcall without checkAction.

===New this.bga.* API Structure===
Many client-side functions have been reorganized into namespaced objects under <code>this.bga</code> for better organization and discoverability:

====Player Functions (this.bga.players)====
📌
* Replace <code>this.isSpectator</code> with <code>this.bga.players.isCurrentPlayerSpectator()</code>
* Replace <code>this.isCurrentPlayerActive()</code> with <code>this.bga.players.isCurrentPlayerActive()</code>
* Replace <code>this.isPlayerActive(player_id)</code> with <code>this.bga.players.isPlayerActive(player_id)</code>
* Replace <code>this.getActivePlayers()</code> with <code>this.bga.players.getActivePlayerIds()</code>
* Replace <code>this.getActivePlayerId()</code> with <code>this.bga.players.getActivePlayerId()</code>
* Replace <code>this.getFormattedPlayerName(...)</code> with <code>this.bga.players.getFormattedPlayerName(...)</code>
* Replace <code>this.addAutomataPlayerPanel(...)</code> with <code>this.bga.players.addAutomataPlayerPanel(...)</code>

====State Functions (this.bga.states)====
📌
* Replace <code>this.on_client_state</code> with <code>this.bga.states.isOnClientState()</code>
* Replace <code>this.setClientState(stateName, args)</code> with <code>this.bga.states.setClientState(stateName, args)</code>
* Replace <code>this.restoreServerGameState()</code> with <code>this.bga.states.restoreServerGameState()</code>

====Status Bar Functions (this.bga.statusBar)====
📌
* Replace <code>this.updatePageTitle()</code> with <code>this.bga.statusBar.setTitle(title, args)</code>
* Replace <code>this.removeActionButtons()</code> with <code>this.bga.statusBar.removeActionButtons()</code>

====Action Functions (this.bga.actions)====
📌
* Replace <code>this.checkAction(action, nomessage)</code> with <code>this.bga.actions.checkAction(action, nomessage)</code>
* Replace <code>this.checkPossibleActions(action)</code> with <code>this.bga.actions.checkPossibleActions(action)</code>
* Replace <code>this.bgaPerformAction(...)</code> with <code>this.bga.actions.performAction(...)</code> - Note: catch result is now <code>{ message, args }</code> instead of just <code>message</code>

====Dialog Functions (this.bga.dialogs)====
📌
* Replace <code>this.showMoveUnauthorized()</code> with <code>this.bga.dialogs.showMoveUnauthorized()</code>
* Replace <code>this.showMessage(msg, type)</code> with <code>this.bga.dialogs.showMessage(msg, type)</code>
* Replace <code>this.confirmationDialog(text, callback, callback_cancel)</code> with <code>this.bga.dialogs.confirmation(text)</code> - Note: now returns a Promise instead of using callbacks
* Replace <code>this.multipleChoiceDialog(text, choices, callback)</code> with <code>this.bga.dialogs.multipleChoice(text, choices)</code> - Note: now returns a Promise instead of using callbacks

====Image Functions (this.bga.images)====
📌
* Replace <code>this.dontPreloadImage(image)</code> with <code>this.bga.images.dontPreloadImage(image)</code> or <code>this.bga.images.dontPreloadImages([...])</code>
* Replace <code>this.ensureSpecificGameImageLoading(imagelist)</code> with <code>this.bga.images.preloadImage(image)</code> or <code>this.bga.images.preloadImages([...])</code>

====Game Area Functions (this.bga.gameArea)====
📌
* Replace <code>this.getGameAreaElement()</code> with <code>this.bga.gameArea.getElement()</code>
* Replace <code>this.addLastTurnBanner(message, args)</code> with <code>this.bga.gameArea.addLastTurnBanner(message, args)</code>
* Replace <code>this.removeLastTurnBanner()</code> with <code>this.bga.gameArea.removeLastTurnBanner()</code>
* Replace <code>this.addWinConditionBanner(message, args)</code> with <code>this.bga.gameArea.addWinConditionBanner(message, args)</code>

====Player Panel Functions (this.bga.playerPanels)====
📌
* Replace <code>this.getPlayerPanelElement(playerId)</code> with <code>this.bga.playerPanels.getElement(playerId)</code>
* Replace <code>this.scoreCtrl[player_id]</code> with <code>this.bga.playerPanels.getScoreCounter(player_id)</code>

====User Preferences (this.bga.userPreferences)====
📌
* Replace <code>this.getGameUserPreference(pref_id)</code> with <code>this.bga.userPreferences.get(pref_id)</code>
* Replace <code>this.setGameUserPreference(pref_id, value)</code> with <code>this.bga.userPreferences.set(pref_id, value)</code>

====Notification Functions (this.bga.notifications)====
📌
* Replace <code>this.bgaSetupPromiseNotifications(...)</code> with <code>this.bga.notifications.setupPromiseNotifications(...)</code>

====Animation Functions (this.bga.gameui)====
📌
* Replace <code>this.instantaneousMode</code> with <code>this.bga.gameui.bgaAnimationsActive()</code> - Note: logic is reversed (instantaneousMode was true when animations should be skipped, bgaAnimationsActive() returns true when animations should play)

===Access to DOM elements ===
New functions getPlayerPanelElement(player_id) and this.getGameAreaElement()

Note: These functions are now deprecated in favor of <code>this.bga.playerPanels.getElement(playerId)</code> and <code>this.bga.gameArea.getElement()</code>. See [[#New this.bga.* API Structure]] above.

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Adding_stuff_to_player%27s_panel

📌 Code like dojo.place(html, player_board_${player.id}); would be replaced by this.bga.gameArea.getElement().insertAdjacentHTML('beforeend', html);
===Notification setup===
Notifications can now be automatically scanned and called without needing to register them one by one. They'll handle Promises, so they end synchronously when the Promise resolves.

Note: <code>bgaSetupPromiseNotifications</code> is now deprecated in favor of <code>this.bga.notifications.setupPromiseNotifications</code>. See [[#New this.bga.* API Structure]] above.

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Notifications

A wait function has been added to return a Promise when a delay is passed (compatible with fast-replay mode)

A new utility function has been added to support Promises for old Dojo animations

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Animation_Callbacks

📌 Dojo.subscribe calls in setupNotifications must be removed if using promise-based notification setup. Notif_ function should be async and return a Promise, make sure they wait for the expected amount of time if the sync setup was using a numerical duration

If you used Dojo animation, make them Promise compatible with "await this.bgaPlayDojoAnimation(dojoAnim);"

===Status bar manipulation===
Function to change the title from the JS

Note: <code>this.statusBar.*</code> methods are now available via <code>this.bga.statusBar.*</code> for consistency. See [[#New this.bga.* API Structure]] above.

https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Title_bar

📌 Replace direct title div manipulation with this.bga.statusBar.setTitle(title: string, args?: object), and benefit from replacement of ${actplayer}/${you}/... (see example in the link above).

This also includes a new function to create action buttons, that are more screen-reader compatible than the previous version. The new button parameters also allow you to set a confirm popin or an autoclick for confirmation buttons

📌 Replace this.addActionButton by this.bga.statusBar.addActionButton. Notice the parameters have changed, so they need to be adapted too! Remove manual setActionTimer or manual confirm with the new parameters.

===Dojo usage===
Dojo usage has been reduced to minimum in the new project template and the doc, as native JS is now able to do almost the same things, with better performance and more knowledge for newcomers of the native (vanilla) JS.

📌 Replace dojo by vanilla JS where possible
{| class="wikitable"
! Dojo API
! Category
! Description
! Vanilla JS Replacement
|-
| <code>dojo.byId("id")</code>
| DOM Selection
| Selects a single DOM element by its ID.
| <code>document.getElementById("id")</code>
|-
| <code>dojo.query("selector")</code>
| DOM Selection
| Selects a collection of DOM elements using CSS selectors.
| <code>document.querySelectorAll("selector")</code> or <code>document.querySelector("selector")</code>
|-
| <code>dojo.connect(node, "onclick", fn)</code>
| Event Handling
| Connects an event handler to a DOM element.
| <code>node.addEventListener("click", fn)</code>
|-
| <code>dojo.disconnect(handle)</code>
| Event Handling
| Removes an event handler created with <code>dojo.connect</code>.
| <code>handle.remove()</code> for event listeners, or <code>node.removeEventListener("click", fn)</code>
|-
| <code>dojo.stopEvent(evt)</code>
| Event Handling
| Prevents propagation and default action for an event.
| <code>evt.preventDefault(); evt.stopPropagation();</code>
|-
| <code>dojo.place(node, parent, "last")</code>
| DOM Manipulation
| Places a DOM node inside a parent node at a specific position.
| <code>parent.appendChild(node)</code>, when using raw html <code>parent.insertAdjacentHTML('beforeend', html)</code>
|-
| <code>dojo.create("tag", props, parent)</code>
| DOM Manipulation
| Creates a new DOM element with optional properties.
| <code>document.createElement("tag")</code>, then set properties and use <code>parent.appendChild()</code>
|-
| <code>dojo.style(node, "color", "red")</code>
| Styling
| Sets an inline CSS property on a DOM node. <b>CAUTION:</b> <code>dojo.style(node, "left")</code> (and "right", "width", etc) return lengths in pixels as numbers, not the set CSS style.
| <code>node.style.color = "red"</code>
|-
| <code>dojo.hasClass(node, "className")</code>
| Styling
| Checks if a DOM node has a specific CSS class.
| <code>node.classList.contains("className")</code>
|-
| <code>dojo.addClass(node, "className")</code>
| Styling
| Adds a CSS class to a DOM node.
| <code>node.classList.add("className")</code>
|-
| <code>dojo.removeClass(node, "className")</code>
| Styling
| Removes a CSS class from a DOM node.
| <code>node.classList.remove("className")</code>
|-
| <code>dojo.forEach(array, fn)</code>
| Array Utilities
| Iterates over an array.
| <code>array.forEach(fn)</code>
|-
| <code>dojo.map(array, fn)</code>
| Array Utilities
| Transforms an array by applying a function to each element.
| <code>array.map(fn)</code>
|-
| <code>dojo.fadeOut, dojo.fadeIn</code>
| Animations
| Various animations
| Use https://en.doc.boardgamearena.com/BgaAnimations or CSS animations
|-
| <code>dojo.hitch(this, "functionName")</code>
| Variable scoping
| Binds <code>this</code> (or other variable) in a callback
| <code>functionName.bind(this)</code>
|-
|<code>dojo.destroy(node)</code>
|DOM Manipulation
|Destroys a DOM element
|<code>node.remove()</code>
|-
|<code>dojo.indexof(array,value)</code>
|Array Utilities
|index of the item in the array,
|<code>array.indexof(value) or array.indexof(test)</code>
|-
|<code>dojo.string.substitute</code>
|String Utilities
|template substitution
|<code>Use JS template strings, i.e. `<div id=${id}></div>`. Note: not suitable for translations if variables are used inside</code>

|}

===Sound loading===
New functions load/play have been added for the sounds:

https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Sounds

📌 Replace template loading of sounds and global function playSound

===Formatting of log message using bgaFormatText===
This function, if defined, will allow you to insert HTML in the logs without overriding format_string_recursive. Example: 📌https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Define_this.bgaFormatText%28%29_method

📌 Replace the override of format_string_recursive by bgaFormatText (the last line will change)

===Automata player panel===
A new framework function to add a player panel for your game automas https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Adding_a_player_panel_for_an_automata

📌 Replace manually created automata player panel with this new function

===New JS libraries===
New JS libraries are created to help you design your games, especially for components that you will find on numerous games. See [[Studio#BGA Studio game components reference]]

📌 Replace manually created animation, stocks, etc with components (check the link above, don't want to duplicate it here)

===CSS imports===
Default BGA imports are auto-included, if you find this code and comment in .css you can delete it
@import url(../../../css/csslayer.css);
/* Note: you must not use any @import directive other than this one */

===Future support of dark mode===
BGA doesn't support dark mode yet. To have some games compatible when we do, we added a theme data tag you can use as described here:

https://en.doc.boardgamearena.com/Game_interface_stylesheet:_yourgamename.css#Support_of_the_Dark_mode

Bugsclarification stoneage

2026-01-29T21:30:13Z

Inaofr: Add a link on a report on the website.

Please do not report if your bug match one of the followings.

A frequent "won’t fix": sometimes you are not notified of a game update because of a lost message over the Internet. It can results in wrong situation display and in not being notified that it is your turn to play. These is linked to BGA framework and will not be fixed at the Stone Age code level. Please upvote this BGA website [https://boardgamearena.com/bug?id=201639 report].

Here is a list of frequent "not a bug" reports: the user was just not knowing the actual rule.
* Can not put a worker at x place: check the placement limitation rules for two or three players game (and even four players if you are using the trade expansion).
* Did not get the two (might be one with the trade expansion) wild resources of the civilization card: you got it on your player board, you have to click on the wild resource icon to choose them.
* Did not get the free wood/clay/stone of the bought hut (new huts expansion): the free resource is not granted at buy but at start of each following turns.
* Could not insulate bought hut (harsh winter variant): only huts of the standard game and costing three defined resources (not wild resources) can be insulated.
* Can not trade to buy an igloo: trade is allowed to buy a hut or a card, igloos are not huts nor cards.
* Can not trade to buy hut or card, different normal causes here:
** you can trade only one time per game turn (a game turn ends when all workers have been removed from playing area),
** the 2:1, 1:1 or 1:2 trade indicator (depending on your trade level) is not a trade rate, but a trade possibility: for instance for the 1:1, you can trade one resource and only one against another one, you can not trade two or more against the same number,
** you can not trade one resource against itself, even at trade level 9 or 10 (1:2 trade possibility: you can not trade one wood against one wood and one stone for instance).
* Did not get the second resource in my 1:2 trade: all resources gain in a trade are used in the linked buy, even if not needed for it, and it does not add points and can not be used to insulate or pay an extra gold in harsh winter variant.

Bugsclarification stoneage

2026-01-29T21:24:38Z

Inaofr:

Please do not report if your bug match one of the followings.

A frequent "won’t fix": sometimes you are not notified of a game update because of a lost message over the Internet. It can results in wrong situation display and in not being notified that it is your turn to play. These is linked to BGA framework and will not be fixed at the Stone Age code level.

Here is a list of frequent "not a bug" reports: the user was just not knowing the actual rule.
* Can not put a worker at x place: check the placement limitation rules for two or three players game (and even four players if you are using the trade expansion).
* Did not get the two (might be one with the trade expansion) wild resources of the civilization card: you got it on your player board, you have to click on the wild resource icon to choose them.
* Did not get the free wood/clay/stone of the bought hut (new huts expansion): the free resource is not granted at buy but at start of each following turns.
* Could not insulate bought hut (harsh winter variant): only huts of the standard game and costing three defined resources (not wild resources) can be insulated.
* Can not trade to buy an igloo: trade is allowed to buy a hut or a card, igloos are not huts nor cards.
* Can not trade to buy hut or card, different normal causes here:
** you can trade only one time per game turn (a game turn ends when all workers have been removed from playing area),
** the 2:1, 1:1 or 1:2 trade indicator (depending on your trade level) is not a trade rate, but a trade possibility: for instance for the 1:1, you can trade one resource and only one against another one, you can not trade two or more against the same number,
** you can not trade one resource against itself, even at trade level 9 or 10 (1:2 trade possibility: you can not trade one wood against one wood and one stone for instance).
* Did not get the second resource in my 1:2 trade: all resources gain in a trade are used in the linked buy, even if not needed for it, and it does not add points and can not be used to insulate or pay an extra gold in harsh winter variant.

Options and preferences: gameoptions.json, gamepreferences.json

2026-01-01T18:38:09Z

Inaofr: /* Game Options */ Formatting

{{Studio_Framework_Navigation}}

In <code>gameoptions.json</code>, you can define your game options (i.e. game variants).

In <code>gamepreferences.json</code>, you can define user preferences.

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

'''IMPORTANT:''' after edits to these files, you have to go to the control panel and press "Reload game options configuration" on Studio 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 player count, which is automatically handled). For example, whether to include ''The River'' in Carcassonne.
* User preferences - personal choices of each player only visible to that specific player - i.e. layout, whether or not to prompt for action, whether 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 <code>gameoptions.json</code> as an object:

{
"100": { "name": "Game Setup", ... },
"101": { "name": "Draft", ... }
}

Each key corresponds to the option id, and each value is that option definition, which is described below.

'''Note:''' the file must be valid [https://www.json.org/ JSON]. That is, trailing commas and comments are not allowed. However you can use still standard json hack to add a field like "$comment": "Here we go"

'''Note 2:''' the key in json file must be a string type, even its correspond to a number in other places (such as php, or other references in same json).

'''$this->tableOptions->get(int $optionId): int'''

To get the value of a table option from the Game class, using the JSON key.

To access json data (the metadata only) can use
$game_options = $this->getTableOptions();
=== Details of game options format ===

The following are the values of the option definition object:
* '''name''' - '''mandatory'''. The name of the option visible for table creator. This is automatically marked for translation.
* '''values''' - '''mandatory'''. The map representing possible values of this option. The key of the map is possible value of this option, its a number but has to be string in json. The value is an object descring it.
** '''name''' - '''mandatory'''. String representation of the numeric value visible to table creator. This is automatically marked for translation.
** '''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. Note: if there is no description, this should be omitted.
** '''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 options.) '''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''' - (array of conditions) - checks the conditions before displaying the option for selection. All (or any) conditions must be true for the option to be displayed. All or any depends on value of displayconditionoperand
Supported display 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'' condition ensures at most this many players
** ''otheroption'' condition ensures another option is set to given values.
** ''otheroptionisnot'' condition 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''' - (map from value to conditions array) - 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 start condition types:
** ''minplayers'' condition ensures at least this many players (an array of values is not supported here)
** ''maxplayers'' condition ensures 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. <span style="background: #FFCDD2; color: #B71C1C; padding: 2px;">But this should never be used -- see the warning below</span>
* '''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 [[#level|below]] for more informations.

Common (reserved) options for all tables (reserved range 200-299):
*201 (const GAMESTATE_RATING_MODE) - ELO OFF (aka Training mode),
**0 = Normal
**1 = Training
**2 = Arena
*200 (const GAMESTATE_CLOCK_MODE) - game speed profile
**[0, 1, 2] - realtime (technically <10 realtime but you cannot define range in php)
**values >=10 - turn based (currently 10..21)
**Note there are two similar values, 9 = realtime "no time limit with friends only" vs. 20 = turn-based "no time limit with friends only"
GAMESTATE_RATING_MODE and GAMESTATE_CLOCK_MODE are PHP global constants usable in your PHP game code (ex: <code>$this->tableOptions->get(GAMESTATE_CLOCK_MODE)</code>) but not in json.

'''Example:'''
<pre>
{
"100": {
"name": "Game Variant",
"values": {
"1": {
"name": "Learning",
"firstgameonly": true,
"tmdisplay": "Learning"
},
"2": {
"name": "Base",
},
"3": {
"name": "Extended",
"nobeginner": true,
"beta": true,
"tmdisplay": "Extended"
}
},
"default": 2
},
"101": {
"name": "Draft variant",
"values": {
"1": {
"name": "No draft"
},
"2": {
"name": "Draft",
"tmdisplay": "Draft",
"premium": true,
"nobeginner": true
}
},
"displaycondition": [
{
"type": "otheroption",
"id": 100,
"value": [ 2, 3 ]
},
{
"type": "otheroption",
"id": 201,
"value": 1
}
],
"startcondition": {
"1": [],
"2": [
{
"type": "maxplayers",
"value": 3,
"message": "Draft option is available for 3 players maximum."
}
]
}
},
"102": {
"name": "Takeovers",
"values": {
"2": {
"name": "No takeover"
},
"1": {
"name": "Allow takeovers",
"tmdisplay": "Takeovers",
"premium": true,
"nobeginner": true
}
},
"displaycondition": [
{
"type": "otheroption",
"id": 100,
"value": [ 3 ]
}
],
"startcondition": {
"2": [],
"1": [
{
"type": "maxplayers",
"value": 2,
"message": "Rebel vs Imperium Takeover Scenario is available for 2 players only."
}
]
}
}
}
</pre>

'''Example of option that condition on ELO off:'''
{
"100": {
"name": "Learning Game (No Research)",
"values": {
"1": {
"name": "Off",
"tmdisplay": ""
},
"2": {
"name": "On",
"tmdisplay": "Learning Game"
}
},
"startcondition": {
"2": {
"type": "otheroption",
"id": 201,
"value": 1,
"message": "Learning variant available only in friendly mode"
}
}
}
}
'''Example of condition that is only available for REALTIME game mode:'''
<pre>
"displaycondition": [
{ "type": "otheroption", "id": 200, "value": [0, 1, 2] }
],
</pre>

'''Example of using condition on your own option:'''
<pre>
{
"102": {
"name": "Scenarios",
"values": {
"1": {
"name": "Off",
"nobeginner": false
},
"2": {
"name": "On",
"tmdisplay": "Scenarios",
"nobeginner": true
}
},
"displaycondition": [
{
"type": "otheroptionisnot",
"id": 100,
"value": 1
}
],
"notdisplayedmessage": "Scenarios variant is not available if Learning variant is chosen"
}
}

</pre>

'''Example of handling solo vs multiplayer options:'''<pre>
{
"100": {
"name": "Board setup",
"values": {
"1": {
"name": "Mirror setup",
"description": "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": "Mirror setup"
},
"2": {
"name": "Random setup",
"description": "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": "Random setup"
}
},
"displaycondition": [
{
"type": "minplayers",
"value": [
2,
3,
4
]
}
]
},
"102": {
"name": "Solo difficulty",
"values": [
{
"name": "Banana-apprentice",
"description": "Do not remove any seed before starting the game.",
"tmdisplay": "Banana-apprentice"
},
{
"name": "Pear to the Throne",
"description": "Remove 1 seed before starting the game.",
"tmdisplay": "Pear to the Throne"
}
],
"displaycondition": [
{
"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.

The other difference is displaycondition affect option itself, while startcondition affect specific values selected

==== gamestartonly ====

<div style="padding: 1em; background: #FFCDD2; color: #B71C1C">
<b>WARNING:</b> [https://studio.boardgamearena.com/bug?id=104 See studio bug #104]. You should <b>NEVER</b> use <code>gamestartonly</code>! Otherwise, you allow players to (unknowingly!) create a turn-based table with impossible options that can never start. Players receive no indication that the option combination they selected is invalid until the last player joins the table (hours or days later) and the game attempts to auto-start. The table won't start because of the <code>startcondition</code>, and the table options cannot be changed because it's a turn-based table, so the table must be abandoned. This is a horrible user experience. Please don't subject players to this.
</div>

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>
{
"100": {
"name": "Option name",
"values": [],
"startcondition": {
"1": [
{
"type": "maxplayers",
"value": 2,
"message": "This option is available for 2 players only.",
"gamestartonly": true
}
]
}
}
}
</pre>

==== level ====
Note: At this moment this only has an impact in fancy lobby mode; The presentation of level or checkboxes is not available via normal table creation UI (such as in studio, or when you click Play button in control panel).<pre>
{
"100": {
"name": "Option name",
"values": [...],
"level": "major"
}
}
</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). Note: this cannot be tested from Studio as there is not studio-only Game metadata manager, to see Major Variants option - the game has to be deployed at least as alpha.
* the major option can have more than 2 values (there will then be an arrow to slide to the other values, carousel-like)
* the naming of major variant values should be concise and the values should have descriptive text (not just "enabled" or "disabled")
** 👍 Option name "Expansion", option values "Base game", "Bigger is Better" => Displayed as ''"Expansion: Base game"'' or ''"Expansion: Bigger is Better"''
** 👎 Option name "Bigger is Better", option values "Enabled", "Disabled => Displayed as ''"Bigger is Better: Enabled"'' or ''"Bigger is Better: Disabled"''

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

An option WILL be displayed as a '''Checkbox''' instead of a selector if certain conditions are met:

* option has 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 (and also at the bottom on the page in the Options tab).
"Display game logs" and "Display tooltips" are baked-in by default, but you can extend this list as below.

The preference json slightly resembles options, but these are conceptually different. The numbers comes from a different space and do not correspond or conflict with options,
i.e. preference 100 has nothing to do with option 100. You can use range 100-199 with gaps.

[[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>
{
"100": {
"name": "Colorblind Support",
"needReload": true,
"values": {
"1": {
"name": "None",
"cssPref": "colorblind_off"
},
"2": {
"name": "Numbers",
"cssPref": "colorblind_on"
},
"3": {
"name": "Shapes",
"cssPref": "colorblind_shapes"
}
},
"default": 1
}
}
</pre>

There is two ways to check/apply this. In javascript

if (this.userPreferences.get(100) == 2) ...

This checks if preferences 100 has selected value 2.

Second, if cssPref is specified, it will be applied to the '''<html>''' tag. So you can use different css styling for the preference. Note: you also need 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 dev0 account will have it actually working (bug?).

The following are the parameters of preferences description array:
* '''name''' - '''mandatory'''. The name of the preference. This string is marked for translation.
* '''needReload''' - If set to true, the game interface will auto-reload after a change of the preference.
* '''values''' - '''mandatory'''. The map of values with additional parameters per value.
** '''name''' - '''mandatory'''. String representation of the numeric value. This string is marked for translation.
** '''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 and updating preference from code ===
The BGA framework offers read/write and callback for user preference changes. See [[Game interface logic: yourgamename.js#User preferences]]

=== Accessing User Preferences on the server ===
PHP has an object called '''$this->userPreferences''', and you simply have to use its method get ('''get($playerId, $prefId): ?$int''') to know the preference value of a specific player :
<pre>
if ($this->userPreferences->get($playerId, $prefId) == $prefValue) {
....
}
</pre>
Note: it is stored in database table bga_user_preferences

See also: [[Main game logic: Game.php#User preferences]]

== Translations ==
Note that any name or description values in these JSON files are automatically added to the translation system.

== Migration ==
Previously, options and preferences were specified in a single <code>gameoptions.inc.php</code> file.

BGA has switched to a JSON format to make parsing easier on the server-side, and to avoid a reliance on PHP for static config.

The PHP format will continue to work for ''existing'' games, and although preferred, there is no need to migrate unless you want to. However, newly created games must use the new format.

'''Note''': once a game has been committed with a <code>gameoptions.json</code> file, however, it is not possible to go back without admin intervention.

If you want to migrate:

Simple method:
* Go to studio and press Reload game options configuration
* It will dump json on the log window - you can take this, format it and save into 2 files (if you have both). For gamepreference.json remove option "200" - this is default common option, it should not be in your file.

Manual method:
* Remove all calls to <code>totranslate()</code>, and replace with the plain string
* Remove any references to BGA's PHP constants, such as GAMESTATE_RATING_MODE, and replace with the plain value (in this case, 201)
* You can populate <code>gameoptions.json</code> with the result of <code>json_encode($game_options, JSON_PRETTY_PRINT)</code>
* You can populate <code>gamepreferences.json</code> with the result of <code>json_encode($game_preferences, JSON_PRETTY_PRINT)</code>
* If you include gameoptions.inc.php directly, to read the values, then replace those calls with <code>$this->getTableOptions()</code> or <code>$this->getTablePreferences()</code> as appropriate which return arrays parsed from the JSON files
This message was posted to the developer Discord channel:<blockquote>'''Game options change (Optional!)'''

<code>gameoptions.inc.php</code> is now considered legacy, and <code>gameoptions.json</code> and <code>gamepreferences.json</code> are recommended for new projects:

* The wiki and the template project have been updated: [[Options and preferences: gameoptions.json, gamepreferences.json#User Preferences|https://en.doc.boardgamearena.com/Options_and_preferences:_gameoptions.json,_gamepreferences.json]]
* Any questions/problems can come to me, or can be asked here.
* The format of the json files matches the format of the old php files

We realise there are some drawbacks (sorry!):

* No comments in the JSON file, meaning you have to check the wiki for examples
* No PHP constants in the JSON file, meaning magic numbers

However, we hope it's good for BGA because:

* Simpler to parse (for robots and humans)
* Easier to check for errors (we could perhaps use an XSLT one day)
* No need to run game-specific PHP code on the metasite

'''NOTE''': Switching is totally optional, and the legacy files will still work for existing projects, and for those who know about them. </blockquote>
[[Category:Studio]]

Options and preferences: gameoptions.json, gamepreferences.json

2026-01-01T18:36:17Z

Inaofr: Indicate how to use GAMESTATE_RATING_MODE and GAMESTATE_CLOCK_MODE.

{{Studio_Framework_Navigation}}

In <code>gameoptions.json</code>, you can define your game options (i.e. game variants).

In <code>gamepreferences.json</code>, you can define user preferences.

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

'''IMPORTANT:''' after edits to these files, you have to go to the control panel and press "Reload game options configuration" on Studio 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 player count, which is automatically handled). For example, whether to include ''The River'' in Carcassonne.
* User preferences - personal choices of each player only visible to that specific player - i.e. layout, whether or not to prompt for action, whether 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 <code>gameoptions.json</code> as an object:

{
"100": { "name": "Game Setup", ... },
"101": { "name": "Draft", ... }
}

Each key corresponds to the option id, and each value is that option definition, which is described below.

'''Note:''' the file must be valid [https://www.json.org/ JSON]. That is, trailing commas and comments are not allowed. However you can use still standard json hack to add a field like "$comment": "Here we go"

'''Note 2:''' the key in json file must be a string type, even its correspond to a number in other places (such as php, or other references in same json).

'''$this->tableOptions->get(int $optionId): int'''

To get the value of a table option from the Game class, using the JSON key.

To access json data (the metadata only) can use
$game_options = $this->getTableOptions();
=== Details of game options format ===

The following are the values of the option definition object:
* '''name''' - '''mandatory'''. The name of the option visible for table creator. This is automatically marked for translation.
* '''values''' - '''mandatory'''. The map representing possible values of this option. The key of the map is possible value of this option, its a number but has to be string in json. The value is an object descring it.
** '''name''' - '''mandatory'''. String representation of the numeric value visible to table creator. This is automatically marked for translation.
** '''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. Note: if there is no description, this should be omitted.
** '''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 options.) '''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''' - (array of conditions) - checks the conditions before displaying the option for selection. All (or any) conditions must be true for the option to be displayed. All or any depends on value of displayconditionoperand
Supported display 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'' condition ensures at most this many players
** ''otheroption'' condition ensures another option is set to given values.
** ''otheroptionisnot'' condition 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''' - (map from value to conditions array) - 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 start condition types:
** ''minplayers'' condition ensures at least this many players (an array of values is not supported here)
** ''maxplayers'' condition ensures 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. <span style="background: #FFCDD2; color: #B71C1C; padding: 2px;">But this should never be used -- see the warning below</span>
* '''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 [[#level|below]] for more informations.

Common (reserved) options for all tables (reserved range 200-299):
*201 (const GAMESTATE_RATING_MODE) - ELO OFF (aka Training mode),
**0 = Normal
**1 = Training
**2 = Arena
*200 (const GAMESTATE_CLOCK_MODE) - game speed profile
**[0, 1, 2] - realtime (technically <10 realtime but you cannot define range in php)
**values >=10 - turn based (currently 10..21)
**Note there are two similar values, 9 = realtime "no time limit with friends only" vs. 20 = turn-based "no time limit with friends only"
GAMESTATE_RATING_MODE and GAMESTATE_CLOCK_MODE are PHP global constants usable in your PHP game code (ex: $this->tableOptions->get(GAMESTATE_CLOCK_MODE)) but not in json.

'''Example:'''
<pre>
{
"100": {
"name": "Game Variant",
"values": {
"1": {
"name": "Learning",
"firstgameonly": true,
"tmdisplay": "Learning"
},
"2": {
"name": "Base",
},
"3": {
"name": "Extended",
"nobeginner": true,
"beta": true,
"tmdisplay": "Extended"
}
},
"default": 2
},
"101": {
"name": "Draft variant",
"values": {
"1": {
"name": "No draft"
},
"2": {
"name": "Draft",
"tmdisplay": "Draft",
"premium": true,
"nobeginner": true
}
},
"displaycondition": [
{
"type": "otheroption",
"id": 100,
"value": [ 2, 3 ]
},
{
"type": "otheroption",
"id": 201,
"value": 1
}
],
"startcondition": {
"1": [],
"2": [
{
"type": "maxplayers",
"value": 3,
"message": "Draft option is available for 3 players maximum."
}
]
}
},
"102": {
"name": "Takeovers",
"values": {
"2": {
"name": "No takeover"
},
"1": {
"name": "Allow takeovers",
"tmdisplay": "Takeovers",
"premium": true,
"nobeginner": true
}
},
"displaycondition": [
{
"type": "otheroption",
"id": 100,
"value": [ 3 ]
}
],
"startcondition": {
"2": [],
"1": [
{
"type": "maxplayers",
"value": 2,
"message": "Rebel vs Imperium Takeover Scenario is available for 2 players only."
}
]
}
}
}
</pre>

'''Example of option that condition on ELO off:'''
{
"100": {
"name": "Learning Game (No Research)",
"values": {
"1": {
"name": "Off",
"tmdisplay": ""
},
"2": {
"name": "On",
"tmdisplay": "Learning Game"
}
},
"startcondition": {
"2": {
"type": "otheroption",
"id": 201,
"value": 1,
"message": "Learning variant available only in friendly mode"
}
}
}
}
'''Example of condition that is only available for REALTIME game mode:'''
<pre>
"displaycondition": [
{ "type": "otheroption", "id": 200, "value": [0, 1, 2] }
],
</pre>

'''Example of using condition on your own option:'''
<pre>
{
"102": {
"name": "Scenarios",
"values": {
"1": {
"name": "Off",
"nobeginner": false
},
"2": {
"name": "On",
"tmdisplay": "Scenarios",
"nobeginner": true
}
},
"displaycondition": [
{
"type": "otheroptionisnot",
"id": 100,
"value": 1
}
],
"notdisplayedmessage": "Scenarios variant is not available if Learning variant is chosen"
}
}

</pre>

'''Example of handling solo vs multiplayer options:'''<pre>
{
"100": {
"name": "Board setup",
"values": {
"1": {
"name": "Mirror setup",
"description": "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": "Mirror setup"
},
"2": {
"name": "Random setup",
"description": "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": "Random setup"
}
},
"displaycondition": [
{
"type": "minplayers",
"value": [
2,
3,
4
]
}
]
},
"102": {
"name": "Solo difficulty",
"values": [
{
"name": "Banana-apprentice",
"description": "Do not remove any seed before starting the game.",
"tmdisplay": "Banana-apprentice"
},
{
"name": "Pear to the Throne",
"description": "Remove 1 seed before starting the game.",
"tmdisplay": "Pear to the Throne"
}
],
"displaycondition": [
{
"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.

The other difference is displaycondition affect option itself, while startcondition affect specific values selected

==== gamestartonly ====

<div style="padding: 1em; background: #FFCDD2; color: #B71C1C">
<b>WARNING:</b> [https://studio.boardgamearena.com/bug?id=104 See studio bug #104]. You should <b>NEVER</b> use <code>gamestartonly</code>! Otherwise, you allow players to (unknowingly!) create a turn-based table with impossible options that can never start. Players receive no indication that the option combination they selected is invalid until the last player joins the table (hours or days later) and the game attempts to auto-start. The table won't start because of the <code>startcondition</code>, and the table options cannot be changed because it's a turn-based table, so the table must be abandoned. This is a horrible user experience. Please don't subject players to this.
</div>

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>
{
"100": {
"name": "Option name",
"values": [],
"startcondition": {
"1": [
{
"type": "maxplayers",
"value": 2,
"message": "This option is available for 2 players only.",
"gamestartonly": true
}
]
}
}
}
</pre>

==== level ====
Note: At this moment this only has an impact in fancy lobby mode; The presentation of level or checkboxes is not available via normal table creation UI (such as in studio, or when you click Play button in control panel).<pre>
{
"100": {
"name": "Option name",
"values": [...],
"level": "major"
}
}
</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). Note: this cannot be tested from Studio as there is not studio-only Game metadata manager, to see Major Variants option - the game has to be deployed at least as alpha.
* the major option can have more than 2 values (there will then be an arrow to slide to the other values, carousel-like)
* the naming of major variant values should be concise and the values should have descriptive text (not just "enabled" or "disabled")
** 👍 Option name "Expansion", option values "Base game", "Bigger is Better" => Displayed as ''"Expansion: Base game"'' or ''"Expansion: Bigger is Better"''
** 👎 Option name "Bigger is Better", option values "Enabled", "Disabled => Displayed as ''"Bigger is Better: Enabled"'' or ''"Bigger is Better: Disabled"''

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

An option WILL be displayed as a '''Checkbox''' instead of a selector if certain conditions are met:

* option has 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 (and also at the bottom on the page in the Options tab).
"Display game logs" and "Display tooltips" are baked-in by default, but you can extend this list as below.

The preference json slightly resembles options, but these are conceptually different. The numbers comes from a different space and do not correspond or conflict with options,
i.e. preference 100 has nothing to do with option 100. You can use range 100-199 with gaps.

[[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>
{
"100": {
"name": "Colorblind Support",
"needReload": true,
"values": {
"1": {
"name": "None",
"cssPref": "colorblind_off"
},
"2": {
"name": "Numbers",
"cssPref": "colorblind_on"
},
"3": {
"name": "Shapes",
"cssPref": "colorblind_shapes"
}
},
"default": 1
}
}
</pre>

There is two ways to check/apply this. In javascript

if (this.userPreferences.get(100) == 2) ...

This checks if preferences 100 has selected value 2.

Second, if cssPref is specified, it will be applied to the '''<html>''' tag. So you can use different css styling for the preference. Note: you also need 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 dev0 account will have it actually working (bug?).

The following are the parameters of preferences description array:
* '''name''' - '''mandatory'''. The name of the preference. This string is marked for translation.
* '''needReload''' - If set to true, the game interface will auto-reload after a change of the preference.
* '''values''' - '''mandatory'''. The map of values with additional parameters per value.
** '''name''' - '''mandatory'''. String representation of the numeric value. This string is marked for translation.
** '''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 and updating preference from code ===
The BGA framework offers read/write and callback for user preference changes. See [[Game interface logic: yourgamename.js#User preferences]]

=== Accessing User Preferences on the server ===
PHP has an object called '''$this->userPreferences''', and you simply have to use its method get ('''get($playerId, $prefId): ?$int''') to know the preference value of a specific player :
<pre>
if ($this->userPreferences->get($playerId, $prefId) == $prefValue) {
....
}
</pre>
Note: it is stored in database table bga_user_preferences

See also: [[Main game logic: Game.php#User preferences]]

== Translations ==
Note that any name or description values in these JSON files are automatically added to the translation system.

== Migration ==
Previously, options and preferences were specified in a single <code>gameoptions.inc.php</code> file.

BGA has switched to a JSON format to make parsing easier on the server-side, and to avoid a reliance on PHP for static config.

The PHP format will continue to work for ''existing'' games, and although preferred, there is no need to migrate unless you want to. However, newly created games must use the new format.

'''Note''': once a game has been committed with a <code>gameoptions.json</code> file, however, it is not possible to go back without admin intervention.

If you want to migrate:

Simple method:
* Go to studio and press Reload game options configuration
* It will dump json on the log window - you can take this, format it and save into 2 files (if you have both). For gamepreference.json remove option "200" - this is default common option, it should not be in your file.

Manual method:
* Remove all calls to <code>totranslate()</code>, and replace with the plain string
* Remove any references to BGA's PHP constants, such as GAMESTATE_RATING_MODE, and replace with the plain value (in this case, 201)
* You can populate <code>gameoptions.json</code> with the result of <code>json_encode($game_options, JSON_PRETTY_PRINT)</code>
* You can populate <code>gamepreferences.json</code> with the result of <code>json_encode($game_preferences, JSON_PRETTY_PRINT)</code>
* If you include gameoptions.inc.php directly, to read the values, then replace those calls with <code>$this->getTableOptions()</code> or <code>$this->getTablePreferences()</code> as appropriate which return arrays parsed from the JSON files
This message was posted to the developer Discord channel:<blockquote>'''Game options change (Optional!)'''

<code>gameoptions.inc.php</code> is now considered legacy, and <code>gameoptions.json</code> and <code>gamepreferences.json</code> are recommended for new projects:

* The wiki and the template project have been updated: [[Options and preferences: gameoptions.json, gamepreferences.json#User Preferences|https://en.doc.boardgamearena.com/Options_and_preferences:_gameoptions.json,_gamepreferences.json]]
* Any questions/problems can come to me, or can be asked here.
* The format of the json files matches the format of the old php files

We realise there are some drawbacks (sorry!):

* No comments in the JSON file, meaning you have to check the wiki for examples
* No PHP constants in the JSON file, meaning magic numbers

However, we hope it's good for BGA because:

* Simpler to parse (for robots and humans)
* Easier to check for errors (we could perhaps use an XSLT one day)
* No need to run game-specific PHP code on the metasite

'''NOTE''': Switching is totally optional, and the legacy files will still work for existing projects, and for those who know about them. </blockquote>
[[Category:Studio]]

Bugsclarification stoneage

2025-12-28T20:01:38Z

Inaofr: Page creation

Here is a list of frequent "not a bug" reports, where the bug is in fact on the user side: the user was just not knowing the actual rule.
* Can not put a worker at x place: check the placement limitation rules for two or three players game (and even four players if you are using the trade expansion).
* Did not get the two (might be one with the trade expansion) wild resources of the civilization card: you got it on your player board, you have to click on the wild resource icon to choose them.
* Did not get the free wood/clay/stone of the bought hut (new huts expansion): the free resource is not granted at buy but at start of each following turns.
* Could not insulate bought hut (harsh winter variant): only huts of the standard game and costing three defined resources (not wild resources) can be insulated.
* Can not trade to buy an igloo: trade is allowed to buy a hut or a card, igloos are not huts nor cards.
* Can not trade to buy hut or card, different normal causes here:
** you can trade only one time per game turn (a game turn ends when all workers have been removed from playing area),
** the 2:1, 1:1 or 1:2 trade indicator (depending on your trade level) is not a trade rate, but a trade possibility: for instance for the 1:1, you can trade one resource and only one against another one, you can not trade two or more against the same number,
** you can not trade one resource against itself, even at trade level 9 or 10 (1:2 trade possibility: you can not trade one wood against one wood and one stone for instance).
* Did not get the second resource in my 1:2 trade: all resources gain in a trade are used in the linked buy, even if not needed for it, and it does not add points and can not be used to insulate or pay an extra gold in harsh winter variant.

Also a frequent "won’t fix": sometimes you are not notified of a game update because of a lost message over the Internet. It can results in wrong situation display and in not being notified that it is your turn to play. These is linked to BGA framework and will not be fixed at the Stone Age code level (it could but it would be excessively complicated and unstable toward BGA framework changes).

Game meta-information: gameinfos.jsonc

2021-10-01T20:44:36Z

Inaofr: Fix doc on the boolean value effect.

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

Any number of '''Tags''' can be attribute to your game. Tags are useful to place your game in the correct place and to give a good quick overview of what the game is about to players.

Main game category (you MUST specify one tag AND ONLY ONE from this category):
* 1: Abstract game
* 2: Casual games
* 3: For regular players
* 4: For core gamers

Other tags (you can specify any numbers of tags):
* 10: Short game (<10 minutes)
* 11: Medium length game (10 minutes to 30 minutes)
* 12: Long game (>30mn)
* 20: 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]).
* 22: Prototype (This game has not been published yet)
* 23: Classic (This game is a classic from Public Domain)
* 30: 2 players (2p game / best with 2 players)
* 100: Fantasy theme
* 101: Science Fiction them
* 102: Historical theme
* 103: Adventure
* 104: Exploration
* 105: Conquest
* 106: Building
* 200: Card game (Cards plays a central role in this game)
* 201: Dice
* 202: Solo game
* 203: Worker placement
* 204: Hand management
* 205: Bluff
* 206: Tile placement
* 207: Combinations
* 208: Majority
* 209: Race
* 210: Collection
* 211: Cooperative game

== 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"),

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

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
)
)
)
),

Gamehelpstoneage

2021-05-09T14:32:35Z

Inaofr: Describe more precisely the rules for trading (see https://boardgamearena.com/bug?id=35396).

== Goal ==

Gain the most Victory Points by the end of the game.

There are two ways to gain points:

* Acquiring buildings during the game for either a fixed or variable amount
* Acquiring Civilization cards during the game that give extra points at the end of the game

== Rules summary ==

Each round is divided into 3 phases, which are executed in the order described:
* The players take turns placing their people on the game board.
* The players use the actions of their placed people all at once in turn order.
* The players feed their people.

== Phase 1: ==
===Place People on the Board===

In turn order, one area at a time, players place one or more of their people in the different areas of the board. Each "ring" in each area of the board can only be occupied by one person. The exception to this rule is the hunting ground which can be occupied by as many people of any color every turn.

====Special Considerations When Playing With Fewer Than 4 Players====

When playing with '''2 or 3 players''': Of the non-resource areas (Tool Maker, Hut and Field) only two may be occupied per turn. The third place remains empty until the next round.

With '''3 players''': Of the resource areas (Forest, Clay Pit, Quarry and River) only 2 players may place people in each round, even if there are additional spaces for additional people.

With '''2 players''': Of the resource areas (Forest, Clay Pit, Quarry and River) only 1 player may place people in each round, even if there are additional spaces for additional people.

All remaining rules remain unchanged when playing with fewer than 4 players.

== Phase 2: ==
===Use the Actions of Your Placed People===

In turn order each player uses all of his placed people in any order. During this phase, the following actions may be used:

* '''Hunting Grounds (Food), Forest (Wood), Clay Pit (Brick), Quarry (Stone), and River (Gold)''': Roll 1 dice per person placed and acquire resources according to the number rolled (1 Food for each full 2 on Hunting Grounds, 1 Wood for each full 3 on Forest, 1 Brick for each full 4 on Clay Pit, 1 Stone for each full 5 on Quarry, 1 Gold for each full 6 on River).

* '''Field''': Placing a person in the Field increases your Agriculture Level. Each turn during the Feeding Phase, your Agriculture Level is subtracted from the amount of people you have. A higher agriculture level allows you to more easily sustain your population. You may have a maximum agriculture level of 10.

* '''Tool Maker''': Placing a person on the Tool Maker adds one new Tool to your player board. You only have 3 tools on your player board, and each subsequent person placed on the Tool Maker upgrades one of your tools to the next level. You have a maximum of 3 level 4 tools.

* '''Hut''': Place two People on the Hut to gain an extra Person to place (and feed) for the rest of the game. You may have a maximum of 10 people.

* '''Building Card''': Buy the building with the resources shown on the Building Card, scoring the point value shown in the top-left corner (A question mark in the top-left corner is explained below).

* '''Civilization Card''': Buy the card with a number of resources (of any kind) depending on its position in the Civilization Card Track (1 to 4 resources depicted above the card). The immediate effect of the card is applied when purchase. The bottom half of Civilization Card is used for scoring at the end of the game.

===Resources===

Hunting Grounds, Forest, Clay Pit, Quarry, and River:
Roll 1 dice per Person placed in that area and take the corresponding resources:

* 1 Food for each full 2 on Hunting Grounds,
* 1 Wood for each full 3 on Forest,
* 1 Brick for each full 4 on Clay Pit,
* 1 Stone for each full 5 on Quarry,
* 1 Gold for each full 6 on River.

You may use tools to increase the dice result and take more resources. Each of your tool must be used all at once, and can be used once per turn. Some cards give you single-use tools which are lost after they are used, and don't count for final scoring.

===Buildings===

Pay the building cost to get the Building and receive the Point Value listed in the top-left corner of the card.

''If the building cost is Not Fixed'': If there is a question mark in the corner of the card, you win points for each of the resources used to acquire this building. The values of each resource correspond to the numbers it requires when people are placed on them:
* Each Wood is worth 3 Points,
* Each Brick is worth 4 Points,
* Each Stone is worth 5 Points,
* Each Gold is worth 6 Points.

===Civilization Card Details===

Each Civilization Card acquired brings an immediate advantage (depicted on the top half of the card) and some multiplier for final scoring (depicted on the bottom half of the card).

Place the mouse cursor on each card to see details in the tooltip.

Note that at the list of your acquired civilization cards you will see only the bottom half of each card, for the top half is no longer relevant.

== Phase 3: ==
===Feed Your People===

Each Agriculture Level automatically counts as 1 Food during this phase.

You must provide 1 Food per Person.

In the event that you don't have enough food, you may use any resource to feed your people.

If you don't manage (or choose not) to feed your people by the means above, you lose all of your food and 10 points as a penalty.

===Game End===

The game ends when either:

* One Building Stack is empty at the end of a round, or
* There are insufficient Civilization cards to fill the 4 spots at the beginning of a round.

The final number of points for each player is decided by the conditions below:

* Points earned during the game by acquiring Buildings or Civilization, minus Food Penalties,
* Multipliers denoted at the bottom halves of Civilization Cards collected,
* Each Resource that a Player has leftover on his Player Board Scores 1 Point.

== Variants ==
===Harsh Winter===
* Spend an extra stone when building certain buildings to score 5 points.
* Spend an extra gold when purchasing cards to score 6 points.

===Wild Animals===
* Four animal cards are shuffled into the civilization deck. When revealed, animals stay in play until driven off, subtracting 1, 2, or 3 from all dice rolls.
* Players must collectively place a total of X people on the card to drive it off (X = number of players).
* After driving off a wild animal, each player rolls 1 dice per person placed on it and receive the rewards.

===Igloos===
* Spend 3 resources of the same type to buy an igloo, which awards points like a building but does not count for the end-game building bonus.

===The New Huts===
* Adds new buildings that grant fewer points when built in exchange for a bonus (gain a wood/brick/stone each round, or +1 worker/tool/agriculture level). These do count for the end-game building bonus.

===Mammoth Herd===
* At the beginning of each round, a mammoth appears on the resource shown by the top-most bonus tile.
* Players who place their people there can also spend 1 food or resource per person to tame the mammoth.
* Each player who place people to tame the mammoth roll 1 dice per person.
* The player with the highest single dice is the mammoth tamer. Others are challengers.
* The mammoth tamer can choose to take the 1 or all bonus. Others take the all bonus.
* At the end of the game, the player with the most mammoth tile scores 10 points.

===The Expansion===
* A new location is available on the board: Merchant. 2 people are needed to use this place. When using, increase the merchant level by 2 and gain 2 jewelry.
* Once per round, for buying a card or a building, players can trade resources or jewelry to receive one or two resources or jewelry, depending on their levels. However, a player cannot trade if he is on space 0.
* The rules for Hunting Grounds has changed: for each full 2, 1 food or 1 jewelry can be taken.
* There is a new space for civilization cards: 3 jewelry is needed to buy a card on that space. After that, 3 extra jewelry can be spent to buy the topmost face down civilization card without applying its immediate effect.
* Jewelry is not a resource, therefore it can not be used to feed people and is worth nothing at the end of the game.
* When there are only 4 people, only 3 non-resource places are available each round. When there are only 2-3, 2 are available.
* Trade is not allowed for buying an igloo.
* The extra stone and extra gold of the Harsh Winter variant can not be obtained with a trade.

Gamehelpstoneage

2021-05-09T14:16:23Z

Inaofr: /* Mammoth Herd */

== Goal ==

Gain the most Victory Points by the end of the game.

There are two ways to gain points:

* Acquiring buildings during the game for either a fixed or variable amount
* Acquiring Civilization cards during the game that give extra points at the end of the game

== Rules summary ==

Each round is divided into 3 phases, which are executed in the order described:
* The players take turns placing their people on the game board.
* The players use the actions of their placed people all at once in turn order.
* The players feed their people.

== Phase 1: ==
===Place People on the Board===

In turn order, one area at a time, players place one or more of their people in the different areas of the board. Each "ring" in each area of the board can only be occupied by one person. The exception to this rule is the hunting ground which can be occupied by as many people of any color every turn.

====Special Considerations When Playing With Fewer Than 4 Players====

When playing with '''2 or 3 players''': Of the non-resource areas (Tool Maker, Hut and Field) only two may be occupied per turn. The third place remains empty until the next round.

With '''3 players''': Of the resource areas (Forest, Clay Pit, Quarry and River) only 2 players may place people in each round, even if there are additional spaces for additional people.

With '''2 players''': Of the resource areas (Forest, Clay Pit, Quarry and River) only 1 player may place people in each round, even if there are additional spaces for additional people.

All remaining rules remain unchanged when playing with fewer than 4 players.

== Phase 2: ==
===Use the Actions of Your Placed People===

In turn order each player uses all of his placed people in any order. During this phase, the following actions may be used:

* '''Hunting Grounds (Food), Forest (Wood), Clay Pit (Brick), Quarry (Stone), and River (Gold)''': Roll 1 dice per person placed and acquire resources according to the number rolled (1 Food for each full 2 on Hunting Grounds, 1 Wood for each full 3 on Forest, 1 Brick for each full 4 on Clay Pit, 1 Stone for each full 5 on Quarry, 1 Gold for each full 6 on River).

* '''Field''': Placing a person in the Field increases your Agriculture Level. Each turn during the Feeding Phase, your Agriculture Level is subtracted from the amount of people you have. A higher agriculture level allows you to more easily sustain your population. You may have a maximum agriculture level of 10.

* '''Tool Maker''': Placing a person on the Tool Maker adds one new Tool to your player board. You only have 3 tools on your player board, and each subsequent person placed on the Tool Maker upgrades one of your tools to the next level. You have a maximum of 3 level 4 tools.

* '''Hut''': Place two People on the Hut to gain an extra Person to place (and feed) for the rest of the game. You may have a maximum of 10 people.

* '''Building Card''': Buy the building with the resources shown on the Building Card, scoring the point value shown in the top-left corner (A question mark in the top-left corner is explained below).

* '''Civilization Card''': Buy the card with a number of resources (of any kind) depending on its position in the Civilization Card Track (1 to 4 resources depicted above the card). The immediate effect of the card is applied when purchase. The bottom half of Civilization Card is used for scoring at the end of the game.

===Resources===

Hunting Grounds, Forest, Clay Pit, Quarry, and River:
Roll 1 dice per Person placed in that area and take the corresponding resources:

* 1 Food for each full 2 on Hunting Grounds,
* 1 Wood for each full 3 on Forest,
* 1 Brick for each full 4 on Clay Pit,
* 1 Stone for each full 5 on Quarry,
* 1 Gold for each full 6 on River.

You may use tools to increase the dice result and take more resources. Each of your tool must be used all at once, and can be used once per turn. Some cards give you single-use tools which are lost after they are used, and don't count for final scoring.

===Buildings===

Pay the building cost to get the Building and receive the Point Value listed in the top-left corner of the card.

''If the building cost is Not Fixed'': If there is a question mark in the corner of the card, you win points for each of the resources used to acquire this building. The values of each resource correspond to the numbers it requires when people are placed on them:
* Each Wood is worth 3 Points,
* Each Brick is worth 4 Points,
* Each Stone is worth 5 Points,
* Each Gold is worth 6 Points.

===Civilization Card Details===

Each Civilization Card acquired brings an immediate advantage (depicted on the top half of the card) and some multiplier for final scoring (depicted on the bottom half of the card).

Place the mouse cursor on each card to see details in the tooltip.

Note that at the list of your acquired civilization cards you will see only the bottom half of each card, for the top half is no longer relevant.

== Phase 3: ==
===Feed Your People===

Each Agriculture Level automatically counts as 1 Food during this phase.

You must provide 1 Food per Person.

In the event that you don't have enough food, you may use any resource to feed your people.

If you don't manage (or choose not) to feed your people by the means above, you lose all of your food and 10 points as a penalty.

===Game End===

The game ends when either:

* One Building Stack is empty at the end of a round, or
* There are insufficient Civilization cards to fill the 4 spots at the beginning of a round.

The final number of points for each player is decided by the conditions below:

* Points earned during the game by acquiring Buildings or Civilization, minus Food Penalties,
* Multipliers denoted at the bottom halves of Civilization Cards collected,
* Each Resource that a Player has leftover on his Player Board Scores 1 Point.

== Variants ==
===Harsh Winter===
* Spend an extra stone when building certain buildings to score 5 points.
* Spend an extra gold when purchasing cards to score 6 points.

===Wild Animals===
* Four animal cards are shuffled into the civilization deck. When revealed, animals stay in play until driven off, subtracting 1, 2, or 3 from all dice rolls.
* Players must collectively place a total of X people on the card to drive it off (X = number of players).
* After driving off a wild animal, each player rolls 1 dice per person placed on it and receive the rewards.

===Igloos===
* Spend 3 resources of the same type to buy an igloo, which awards points like a building but does not count for the end-game building bonus.

===The New Huts===
* Adds new buildings that grant fewer points when built in exchange for a bonus (gain a wood/brick/stone each round, or +1 worker/tool/agriculture level). These do count for the end-game building bonus.

===Mammoth Herd===
* At the beginning of each round, a mammoth appears on the resource shown by the top-most bonus tile.
* Players who place their people there can also spend 1 food or resource per person to tame the mammoth.
* Each player who place people to tame the mammoth roll 1 dice per person.
* The player with the highest single dice is the mammoth tamer. Others are challengers.
* The mammoth tamer can choose to take the 1 or all bonus. Others take the all bonus.
* At the end of the game, the player with the most mammoth tile scores 10 points.

===The Expansion===
* A new location is avaliable on the board: Merchant. 2 people are needed to use this place. When using, increase the merchant level by 2 and gain 2 jewelry.
* Once per round, players can trade with the rate on their levels. However, a player cannot trade if he is on space 0.
* The rules for Hunting Grounds has changed: for each full 2, 1 food or 1 jewelry can be taken.
* There is a new space for civilization cards: 3 jewelry is needed to buy a card on that space. After that, 3 extra jewelry can be spent to buy the topmost facedown civilization card without applying its immediate effect.
* Jewelry is not a resource, therefore it can not be used to feed people and is worth nothing at the end of the game.
* When there are only 4 people, only 3 non-resource places are avaliable each round. When there are only 2-3, 2 are avaliable.

Options and preferences: gameoptions.json, gamepreferences.json

2021-04-27T17:09:58Z

Inaofr: Remove assertion on displaycondition, now it seems to be effect less.

{{Studio_Framework_Navigation}}

In this file, you can define your game options (= 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 in your SFTP folder you have to go to the control panel and press "Reload game options configuration" for your changes to take effect.

== Game Options ==

Game options is something selected by table creator and usually correspond to game variant, for example if game includes expansion or certain special rule.

These variants defined in gameoptions.inc.php as variable
$game_options = array(...); // exactly named that

Each option is pair number => 'option description array'.

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 ( array (
...
"my_game_variant" => 100,
) );

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, usually if variant "names" are On and Off, but the description would be same as option name when On, and nothing 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.)
** '''nobeginner''' - Set to true if not recommended for begginers
** '''beta''' - Option in beta stage on development
** '''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
** ''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
** ''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'''.
* '''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

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, values 11-21 - turn based

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>

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

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Notation style'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Classic' ), 'cssPref' => 'notation_classic' ),
2 => array( 'name' => totranslate( 'Tournament' ), 'cssPref' => 'notation_tournament' )
),
'default' => 2
)
);
</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.setupPreference();
},

setupPreference: function () {
// Extract the ID and value from the UI control
var _this = this;
function onchange(e) {
var match = e.target.id.match(/^preference_[cf]ontrol_(\d+)$/);
if (!match) {
return;
}
var prefId = +match[1];
var prefValue = +e.target.value;
_this.prefs[prefId].value = prefValue;
_this.onPreferenceChange(prefId, prefValue);
}

// Call onPreferenceChange() when any value changes
dojo.query(".preference_control").connect("onchange", onchange);

// Call onPreferenceChange() now
dojo.forEach(
dojo.query("#ingame_menu_content .preference_control"),
function (el) {
onchange({ target: el });
}
);
},

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>

Options and preferences: gameoptions.json, gamepreferences.json

2021-04-27T12:41:08Z

Inaofr: /* User Preferences */

{{Studio_Framework_Navigation}}

In this file, you can define your game options (= 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 in your SFTP folder you have to go to the control panel and press "Reload game options configuration" for your changes to take effect.

== Game Options ==

Game options is something selected by table creator and usually correspond to game variant, for example if game includes expansion or certain special rule.

These variants defined in gameoptions.inc.php as variable
$game_options = array(...); // exactly named that

Each option is pair number => 'option description array'.

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 ( array (
...
"my_game_variant" => 100,
) );

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, usually if variant "names" are On and Off, but the description would be same as option name when On, and nothing 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.)
** '''nobeginner''' - Set to true if not recommended for begginers
** '''beta''' - Option in beta stage on development
** '''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
** ''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
** ''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'''.
* '''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

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, values 11-21 - turn based

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>

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

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Notation style'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Classic' ), 'cssPref' => 'notation_classic' ),
2 => array( 'name' => totranslate( 'Tournament' ), 'cssPref' => 'notation_tournament' )
),
'default' => 2
)
);
</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).

If you try to use a displaycondition like for an option, your preference will always be hidden (bug).

=== 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.setupPreference();
},

setupPreference: function () {
// Extract the ID and value from the UI control
var _this = this;
function onchange(e) {
var match = e.target.id.match(/^preference_[cf]ontrol_(\d+)$/);
if (!match) {
return;
}
var prefId = +match[1];
var prefValue = +e.target.value;
_this.prefs[prefId].value = prefValue;
_this.onPreferenceChange(prefId, prefValue);
}

// Call onPreferenceChange() when any value changes
dojo.query(".preference_control").connect("onchange", onchange);

// Call onPreferenceChange() now
dojo.forEach(
dojo.query("#ingame_menu_content .preference_control"),
function (el) {
onchange({ target: el });
}
);
},

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>

Options and preferences: gameoptions.json, gamepreferences.json

2021-04-27T12:39:26Z

Inaofr: /* User Preferences */

{{Studio_Framework_Navigation}}

In this file, you can define your game options (= 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 in your SFTP folder you have to go to the control panel and press "Reload game options configuration" for your changes to take effect.

== Game Options ==

Game options is something selected by table creator and usually correspond to game variant, for example if game includes expansion or certain special rule.

These variants defined in gameoptions.inc.php as variable
$game_options = array(...); // exactly named that

Each option is pair number => 'option description array'.

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 ( array (
...
"my_game_variant" => 100,
) );

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, usually if variant "names" are On and Off, but the description would be same as option name when On, and nothing 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.)
** '''nobeginner''' - Set to true if not recommended for begginers
** '''beta''' - Option in beta stage on development
** '''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
** ''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
** ''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'''.
* '''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

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, values 11-21 - turn based

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>

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

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Notation style'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Classic' ), 'cssPref' => 'notation_classic' ),
2 => array( 'name' => totranslate( 'Tournament' ), 'cssPref' => 'notation_tournament' )
),
'default' => 2
)
);
</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 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).

If you try to use a displaycondition like for an option, your preference will always be hidden (bug).

=== 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.setupPreference();
},

setupPreference: function () {
// Extract the ID and value from the UI control
var _this = this;
function onchange(e) {
var match = e.target.id.match(/^preference_[cf]ontrol_(\d+)$/);
if (!match) {
return;
}
var prefId = +match[1];
var prefValue = +e.target.value;
_this.prefs[prefId].value = prefValue;
_this.onPreferenceChange(prefId, prefValue);
}

// Call onPreferenceChange() when any value changes
dojo.query(".preference_control").connect("onchange", onchange);

// Call onPreferenceChange() now
dojo.forEach(
dojo.query("#ingame_menu_content .preference_control"),
function (el) {
onchange({ target: el });
}
);
},

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>

Options and preferences: gameoptions.json, gamepreferences.json

2021-04-27T12:38:47Z

Inaofr: Add missing parameters

{{Studio_Framework_Navigation}}

In this file, you can define your game options (= 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 in your SFTP folder you have to go to the control panel and press "Reload game options configuration" for your changes to take effect.

== Game Options ==

Game options is something selected by table creator and usually correspond to game variant, for example if game includes expansion or certain special rule.

These variants defined in gameoptions.inc.php as variable
$game_options = array(...); // exactly named that

Each option is pair number => 'option description array'.

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 ( array (
...
"my_game_variant" => 100,
) );

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, usually if variant "names" are On and Off, but the description would be same as option name when On, and nothing 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.)
** '''nobeginner''' - Set to true if not recommended for begginers
** '''beta''' - Option in beta stage on development
** '''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
** ''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
** ''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'''.
* '''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

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, values 11-21 - turn based

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>

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

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Notation style'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Classic' ), 'cssPref' => 'notation_classic' ),
2 => array( 'name' => totranslate( 'Tournament' ), 'cssPref' => 'notation_tournament' )
),
'default' => 2
)
);
</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 would 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 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).

If you try to use a displaycondition like for an option, your preference will always be hidden (bug).

=== 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.setupPreference();
},

setupPreference: function () {
// Extract the ID and value from the UI control
var _this = this;
function onchange(e) {
var match = e.target.id.match(/^preference_[cf]ontrol_(\d+)$/);
if (!match) {
return;
}
var prefId = +match[1];
var prefValue = +e.target.value;
_this.prefs[prefId].value = prefValue;
_this.onPreferenceChange(prefId, prefValue);
}

// Call onPreferenceChange() when any value changes
dojo.query(".preference_control").connect("onchange", onchange);

// Call onPreferenceChange() now
dojo.forEach(
dojo.query("#ingame_menu_content .preference_control"),
function (el) {
onchange({ target: el });
}
);
},

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>

Options and preferences: gameoptions.json, gamepreferences.json

2021-04-27T12:28:22Z

Inaofr: /* Updating preference from code */

{{Studio_Framework_Navigation}}

In this file, you can define your game options (= 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 in your SFTP folder you have to go to the control panel and press "Reload game options configuration" for your changes to take effect.

== Game Options ==

Game options is something selected by table creator and usually correspond to game variant, for example if game includes expansion or certain special rule.

These variants defined in gameoptions.inc.php as variable
$game_options = array(...); // exactly named that

Each option is pair number => 'option description array'.

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 ( array (
...
"my_game_variant" => 100,
) );

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, usually if variant "names" are On and Off, but the description would be same as option name when On, and nothing 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.)
** '''nobeginner''' - Set to true if not recommended for begginers
** '''beta''' - Option in beta stage on development
** '''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
** ''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
** ''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'''.
* '''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

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, values 11-21 - turn based

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>

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

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Notation style'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Classic' ), 'cssPref' => 'notation_classic' ),
2 => array( 'name' => totranslate( 'Tournament' ), 'cssPref' => 'notation_tournament' )
),
'default' => 2
)
);
</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.
* '''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.
* '''default''' - indicates the default value to use for this preference (optional, if not present the first value listed is the default).

If you try to use a displaycondition like for an option, your preference will always be hidden (bug).

=== 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.setupPreference();
},

setupPreference: function () {
// Extract the ID and value from the UI control
var _this = this;
function onchange(e) {
var match = e.target.id.match(/^preference_[cf]ontrol_(\d+)$/);
if (!match) {
return;
}
var prefId = +match[1];
var prefValue = +e.target.value;
_this.prefs[prefId].value = prefValue;
_this.onPreferenceChange(prefId, prefValue);
}

// Call onPreferenceChange() when any value changes
dojo.query(".preference_control").connect("onchange", onchange);

// Call onPreferenceChange() now
dojo.forEach(
dojo.query("#ingame_menu_content .preference_control"),
function (el) {
onchange({ target: el });
}
);
},

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>

Options and preferences: gameoptions.json, gamepreferences.json

2021-04-27T12:27:43Z

Inaofr: Add how to update a preference from the code.

{{Studio_Framework_Navigation}}

In this file, you can define your game options (= 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 in your SFTP folder you have to go to the control panel and press "Reload game options configuration" for your changes to take effect.

== Game Options ==

Game options is something selected by table creator and usually correspond to game variant, for example if game includes expansion or certain special rule.

These variants defined in gameoptions.inc.php as variable
$game_options = array(...); // exactly named that

Each option is pair number => 'option description array'.

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 ( array (
...
"my_game_variant" => 100,
) );

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, usually if variant "names" are On and Off, but the description would be same as option name when On, and nothing 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.)
** '''nobeginner''' - Set to true if not recommended for begginers
** '''beta''' - Option in beta stage on development
** '''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
** ''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
** ''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'''.
* '''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

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, values 11-21 - turn based

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>

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

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Notation style'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Classic' ), 'cssPref' => 'notation_classic' ),
2 => array( 'name' => totranslate( 'Tournament' ), 'cssPref' => 'notation_tournament' )
),
'default' => 2
)
);
</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.
* '''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.
* '''default''' - indicates the default value to use for this preference (optional, if not present the first value listed is the default).

If you try to use a displaycondition like for an option, your preference will always be hidden (bug).

=== 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.setupPreference();
},

setupPreference: function () {
// Extract the ID and value from the UI control
var _this = this;
function onchange(e) {
var match = e.target.id.match(/^preference_[cf]ontrol_(\d+)$/);
if (!match) {
return;
}
var prefId = +match[1];
var prefValue = +e.target.value;
_this.prefs[prefId].value = prefValue;
_this.onPreferenceChange(prefId, prefValue);
}

// Call onPreferenceChange() when any value changes
dojo.query(".preference_control").connect("onchange", onchange);

// Call onPreferenceChange() now
dojo.forEach(
dojo.query("#ingame_menu_content .preference_control"),
function (el) {
onchange({ target: el });
}
);
},

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>

Options and preferences: gameoptions.json, gamepreferences.json

2021-04-27T12:11:11Z

Inaofr: Add preferences parameters description.

{{Studio_Framework_Navigation}}

In this file, you can define your game options (= 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 in your SFTP folder you have to go to the control panel and press "Reload game options configuration" for your changes to take effect.

== Game Options ==

Game options is something selected by table creator and usually correspond to game variant, for example if game includes expansion or certain special rule.

These variants defined in gameoptions.inc.php as variable
$game_options = array(...); // exactly named that

Each option is pair number => 'option description array'.

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 ( array (
...
"my_game_variant" => 100,
) );

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, usually if variant "names" are On and Off, but the description would be same as option name when On, and nothing 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.)
** '''nobeginner''' - Set to true if not recommended for begginers
** '''beta''' - Option in beta stage on development
** '''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
** ''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
** ''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'''.
* '''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

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, values 11-21 - turn based

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>

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

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Notation style'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Classic' ), 'cssPref' => 'notation_classic' ),
2 => array( 'name' => totranslate( 'Tournament' ), 'cssPref' => 'notation_tournament' )
),
'default' => 2
)
);
</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.
* '''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.
* '''default''' - indicates the default value to use for this preference (optional, if not present the first value listed is the default).

If you try to use a displaycondition like for an option, your preference will always be hidden.

=== 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.setupPreference();
},

setupPreference: function () {
// Extract the ID and value from the UI control
var _this = this;
function onchange(e) {
var match = e.target.id.match(/^preference_[cf]ontrol_(\d+)$/);
if (!match) {
return;
}
var prefId = +match[1];
var prefValue = +e.target.value;
_this.prefs[prefId].value = prefValue;
_this.onPreferenceChange(prefId, prefValue);
}

// Call onPreferenceChange() when any value changes
dojo.query(".preference_control").connect("onchange", onchange);

// Call onPreferenceChange() now
dojo.forEach(
dojo.query("#ingame_menu_content .preference_control"),
function (el) {
onchange({ target: el });
}
);
},

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

Options and preferences: gameoptions.json, gamepreferences.json

2021-04-27T11:44:40Z

Inaofr: Fix sample formatting

{{Studio_Framework_Navigation}}

In this file, you can define your game options (= 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 in your SFTP folder you have to go to the control panel and press "Reload game options configuration" for your changes to take effect.

== Game Options ==

Game options is something selected by table creator and usually correspond to game variant, for example if game includes expansion or certain special rule.

These variants defined in gameoptions.inc.php as variable
$game_options = array(...); // exactly named that

Each option is pair number => 'option description array'.

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 ( array (
...
"my_game_variant" => 100,
) );

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, usually if variant "names" are On and Off, but the description would be same as option name when On, and nothing 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.)
** '''nobeginner''' - Set to true if not recommended for begginers
** '''beta''' - Option in beta stage on development
** '''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
** ''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
** ''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'''.
* '''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

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, values 11-21 - turn based

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>

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

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Notation style'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Classic' ), 'cssPref' => 'notation_classic' ),
2 => array( 'name' => totranslate( 'Tournament' ), 'cssPref' => 'notation_tournament' )
),
'default' => 2
)
);
</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?).

=== 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.setupPreference();
},

setupPreference: function () {
// Extract the ID and value from the UI control
var _this = this;
function onchange(e) {
var match = e.target.id.match(/^preference_[cf]ontrol_(\d+)$/);
if (!match) {
return;
}
var prefId = +match[1];
var prefValue = +e.target.value;
_this.prefs[prefId].value = prefValue;
_this.onPreferenceChange(prefId, prefValue);
}

// Call onPreferenceChange() when any value changes
dojo.query(".preference_control").connect("onchange", onchange);

// Call onPreferenceChange() now
dojo.forEach(
dojo.query("#ingame_menu_content .preference_control"),
function (el) {
onchange({ target: el });
}
);
},

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

Options and preferences: gameoptions.json, gamepreferences.json

2021-04-23T19:08:54Z

Inaofr: Add default parameter

{{Studio_Framework_Navigation}}

In this file, you can define your game options (= 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 in your SFTP folder you have to go to the control panel and press "Reload game options configuration" for your changes to take effect.

== Game Options ==

Game options is something selected by table creator and usually correspond to game variant, for example if game includes expansion or certain special rule.

These variants defined in gameoptions.inc.php as variable
$game_options = array(...); // exactly named that

Each option is pair number => 'option description array'.

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 ( array (
...
"my_game_variant" => 100,
) );

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, usually if variant "names" are On and Off, but the description would be same as option name when On, and nothing 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.)
** '''nobeginner''' - Set to true if not recommended for begginers
** '''beta''' - Option in beta stage on development
** '''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
** ''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
** ''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'''.
* '''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

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, values 11-21 - turn based

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

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

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>

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

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Notation style'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Classic' ), 'cssPref' => 'notation_classic' ),
2 => array( 'name' => totranslate( 'Tournament' ), 'cssPref' => 'notation_tournament' )
),
'default' => 2
)
);
</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?).

=== 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.setupPreference();
},

setupPreference: function () {
// Extract the ID and value from the UI control
var _this = this;
function onchange(e) {
var match = e.target.id.match(/^preference_[cf]ontrol_(\d+)$/);
if (!match) {
return;
}
var prefId = +match[1];
var prefValue = +e.target.value;
_this.prefs[prefId].value = prefValue;
_this.onPreferenceChange(prefId, prefValue);
}

// Call onPreferenceChange() when any value changes
dojo.query(".preference_control").connect("onchange", onchange);

// Call onPreferenceChange() now
dojo.forEach(
dojo.query("#ingame_menu_content .preference_control"),
function (el) {
onchange({ target: el });
}
);
},

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

Translations

2020-11-08T13:29:52Z

Inaofr: /* On server side (PHP) */

{{Studio_Framework_Navigation}}

Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.

== How translation works? ==

When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.

Before the release of the game, BGA team will do the French translation of the game.

After the release of the game, the BGA players community will translate the game in every language.

== What should be translated? ==

Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages, ...

This does NOT include error messages that are not supposed to happen (unexpected errors).

== What rules should I follow for the original English strings? ==

For a coherent and homogeneous interface, here are some rules about ending a sentence with a final dot '.'

* As a general rule:
** If a sentence is displayed isolated in the interface => no final dot
** If a sentence is followed or could be followed by another sentence in the same interface space => final dot.

* In detail:
** No final dot:
*** button labels
*** section titles
*** menu elements
*** links triggering an isolated action
*** anything that is not a full sentence
*** current action in the status bar
** Final dot:
*** complete explanation sentence, that can be chained with another sentence
** We can tolerate a dot or no dot (but it should be consistent inside the game) for:
*** isolated tooltip / isolated small sentence
*** game log (no dot is usually preferable)
*** error messages (except if more than one sentence in the error message => final dot mandatory in this case)

Otherwise, you should try to follow as closely as possible the general style and format (including capitalization) used in the English rulebook and game material of the game.

== Focus on translating notifications ==

Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.

However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.

== WARNING: how to make sure your strings will be translated ==

For each game, our translation tool is doing a full scan of the code, looking for translator markers like "_()" or "clientranslate()"... (see below the list of translation markers).

If your original string is not "physically" inside one of this marker, it won't be translated.

<pre>
// Examples: the following strings will be translated:
var mystring_translated = _("my string"); // JS
$mystring_translated = self::_("my string"); // PHP
$mystring_translated = sprintf( self::_("my string with an %s argument"), $argument ); // PHP

// Examples: the following strings WILL NOT be translated:
$my_string = "my string";
$not_translated = self::_( $my_string ); // The original string is not bordered by a translator marker => no translation
$not_translated = self::_( sprintf( "my string with a %s argument", $argument ) ); // Same thing
</pre>

== How to not make translators crazy ;) ==

* When you need the same string twice, try to reuse exactly the same string (with the same case) to minimize the number of strings.
* Do not mark as translatable a game element that does not have to be translated (ex: if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:
<pre>self::_("First part of the string, ").$argument.' '.self::_("second part of the string")</pre>
Write instead:
<pre>sprintf( self::_("First part of the string, %s second part of the string"), $argument )</pre>
(or the equivalent "dojo.string.substitute" in Javascript)
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The more the string is a short insignificant string, the more difficult is the task for them. As a rule of thumb, try to avoid insignificant short strings. You can also leave a comment on what is the context of the string in the translation program (English to English) if you are the developer of the game.
* The BGA translation policy is to be flexible on grammar... We prefer to write "player gets 1 coin(s)" than write two versions of the same string for plural and singular - it reduces the number of strings to translate.
* Instead of writing nice strings like "With the effect of ZZZ, player XXX gets a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".
* Use present tense instead of past, i.e. "player gets wood" instead of "player got wood"
* Avoid using gender specific pronouns, i.e. instead of "player returns card to *his* hand" use "player returns card to *their* hand" or just avoid using it, i.e. "player picks up the card"

== On client side (Javascript) ==

On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.

Examples:
<pre>
// Get a string in player's language:
var translated = _("original english string");

// Get a string in player's language with parameter:
var translated = dojo.string.substitute( _("You can pick ${p} cards and discard ${d}"), {
p: 2,
d: 4
} );
</pre>

'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.

'''ANOTHER WARNING:''' you cannot use this function _() in the javascript object constructor, but you can achieve the same if you use it the setup method

== On server side (PHP) ==

On PHP side, you can use 3 different functions to specify that a string must be translated.

'''clienttranslate( "my string to translate" ):'''

This function is '''transparent''': it will return the original English string without any change. It's only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.

In general, you use clienttranslate:
* On your states.inc.php, for field "description" and "descriptionmyturn".

<pre>
"description" => clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),
</pre>

* On "material.inc.php", when defining texts for game material that must be displayed on client side.
<pre>
$this->card_types = array(

1 => array(
'name' => clienttranslate("Amulet of Air"), // Thus, we can use "_( card_name )" on Javascript side.
</pre>

* When sending a notification with "notifyAllPlayers" or "notifyPlayer", for the game log string and all game log arguments that need a translation.

<pre>
// A game log string with no argument:
self::notifyAllPlayers( 'pickLibraryCards', clienttranslate("Everyone draw cards from his library"), array() );
</pre>

As a consequence there is no point passing variables to this function, i.e.
<pre>
notif="foo"; self::notifyAllPlayers( 'log', clienttraslate(notif)); // BAD
notif=clienttranslate("foo"); self::notifyAllPlayers( 'log', notif); // GOOD
</pre>

Translating arguments is a little bit more complex. It is using the "i18n" special argument as below:

<pre>
// In the following example, we translate the game log itself, but also the "card_name" argument:

self::notifyAllPlayers( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'points' => $points,
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.
) );
</pre>

To ensure the translation of the i18n argument will be made, clienttranslate must have been used somewhere, for instance:

<pre>
$this->card_types = array(
...
8 => array(
'name' => clienttranslate("Amulet of Fire"),
...
</pre>

Pay attention when using 'i18n' argument when translating argument for client : do NOT use same argument for both translation AND key code for client side action (like using 'card_name' to move it on player board as described in the example). It's pretty obvious in the example, but it can be very tricky when translation is made at the end of the development (which is often the case). Use explicit argument name like 'card_name_translated' by example.

'''WARNING:''' you should NEVER use concatenation with clienttranslate, as it would result in a different string to translate at runtime than the one retrieved statically in the translation system, and so translation would not be applied. If you need to compose a string, use substitution and the i18n parameter (but you also have to pay attention not to compose sentences in a way that is dependent upon the English language specific syntax, or it may be impossible to translate correctly in another language: sometimes, you need multiple full sentences rather than relying on substitution).

'''self::_( "my string to translate" ):'''

This function returns a string translated in the language of CURRENT user (i.e. player who send the request to the server) (be careful, this is NOT the active player).

Most of the time, you don't need to translate strings on server side, except on the following 3 situations:
* When throwing an exception because the player did a forbidden move.

<pre>
// This will display a translatable red message to the player that just did some wrong action:
throw new BgaUserException( self::_('You must choose 3 cards') );

// ... notice the use of BgaUserException that signals that this exception is "expected". In theory, all exception that are expected should be translated.
</pre>

* In "yourgame.view.php", when creating the labels for the game interface used in your template (.tpl) file.

<pre>
$this->tpl['CARDS_FOR_YEAR_2'] = self::_("Your cards for year II");
</pre>

* Eventually, in your material.inc.php, if for example you need to use some string elements in your exceptions.

<pre>
// In material.inc.php, $this->energies[n]['nametr'] has been created with the self::_() method. Now we can do this:
throw new BgaUserException( self::_("To execute this action you need more: ").' '.$this->energies[$resource_id]['nametr'] );
</pre>

* Eventually, in your "getAllDatas" PHP method, as the data return by this method is used only by current user.

'''totranslate( "my string to translate" ):'''

This function works exactly like 'clienttranslate', except it tells BGA that the string is not needed on client side.

You should not use this function, except on the following cases:
* Statistics name in stats.inc.php
* Option names and option values name in gameoptions.inc.php

Translations

2020-11-08T13:29:37Z

Inaofr: /* On server side (PHP) */

{{Studio_Framework_Navigation}}

Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.

== How translation works? ==

When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.

Before the release of the game, BGA team will do the French translation of the game.

After the release of the game, the BGA players community will translate the game in every language.

== What should be translated? ==

Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages, ...

This does NOT include error messages that are not supposed to happen (unexpected errors).

== What rules should I follow for the original English strings? ==

For a coherent and homogeneous interface, here are some rules about ending a sentence with a final dot '.'

* As a general rule:
** If a sentence is displayed isolated in the interface => no final dot
** If a sentence is followed or could be followed by another sentence in the same interface space => final dot.

* In detail:
** No final dot:
*** button labels
*** section titles
*** menu elements
*** links triggering an isolated action
*** anything that is not a full sentence
*** current action in the status bar
** Final dot:
*** complete explanation sentence, that can be chained with another sentence
** We can tolerate a dot or no dot (but it should be consistent inside the game) for:
*** isolated tooltip / isolated small sentence
*** game log (no dot is usually preferable)
*** error messages (except if more than one sentence in the error message => final dot mandatory in this case)

Otherwise, you should try to follow as closely as possible the general style and format (including capitalization) used in the English rulebook and game material of the game.

== Focus on translating notifications ==

Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.

However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.

== WARNING: how to make sure your strings will be translated ==

For each game, our translation tool is doing a full scan of the code, looking for translator markers like "_()" or "clientranslate()"... (see below the list of translation markers).

If your original string is not "physically" inside one of this marker, it won't be translated.

<pre>
// Examples: the following strings will be translated:
var mystring_translated = _("my string"); // JS
$mystring_translated = self::_("my string"); // PHP
$mystring_translated = sprintf( self::_("my string with an %s argument"), $argument ); // PHP

// Examples: the following strings WILL NOT be translated:
$my_string = "my string";
$not_translated = self::_( $my_string ); // The original string is not bordered by a translator marker => no translation
$not_translated = self::_( sprintf( "my string with a %s argument", $argument ) ); // Same thing
</pre>

== How to not make translators crazy ;) ==

* When you need the same string twice, try to reuse exactly the same string (with the same case) to minimize the number of strings.
* Do not mark as translatable a game element that does not have to be translated (ex: if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:
<pre>self::_("First part of the string, ").$argument.' '.self::_("second part of the string")</pre>
Write instead:
<pre>sprintf( self::_("First part of the string, %s second part of the string"), $argument )</pre>
(or the equivalent "dojo.string.substitute" in Javascript)
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The more the string is a short insignificant string, the more difficult is the task for them. As a rule of thumb, try to avoid insignificant short strings. You can also leave a comment on what is the context of the string in the translation program (English to English) if you are the developer of the game.
* The BGA translation policy is to be flexible on grammar... We prefer to write "player gets 1 coin(s)" than write two versions of the same string for plural and singular - it reduces the number of strings to translate.
* Instead of writing nice strings like "With the effect of ZZZ, player XXX gets a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".
* Use present tense instead of past, i.e. "player gets wood" instead of "player got wood"
* Avoid using gender specific pronouns, i.e. instead of "player returns card to *his* hand" use "player returns card to *their* hand" or just avoid using it, i.e. "player picks up the card"

== On client side (Javascript) ==

On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.

Examples:
<pre>
// Get a string in player's language:
var translated = _("original english string");

// Get a string in player's language with parameter:
var translated = dojo.string.substitute( _("You can pick ${p} cards and discard ${d}"), {
p: 2,
d: 4
} );
</pre>

'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.

'''ANOTHER WARNING:''' you cannot use this function _() in the javascript object constructor, but you can achieve the same if you use it the setup method

== On server side (PHP) ==

On PHP side, you can use 3 different functions to specify that a string must be translated.

'''clienttranslate( "my string to translate" ):'''

This function is '''transparent''': it will return the original English string without any change. It's only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.

In general, you use clienttranslate:
* On your states.inc.php, for field "description" and "descriptionmyturn".

<pre>
"description" => clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),
</pre>

* On "material.inc.php", when defining texts for game material that must be displayed on client side.
<pre>
$this->card_types = array(

1 => array(
'name' => clienttranslate("Amulet of Air"), // Thus, we can use "_( card_name )" on Javascript side.
</pre>

* When sending a notification with "notifyAllPlayers" or "notifyPlayer", for the game log string and all game log arguments that need a translation.

<pre>
// A game log string with no argument:
self::notifyAllPlayers( 'pickLibraryCards', clienttranslate("Everyone draw cards from his library"), array() );
</pre>

As a consequence there is no point passing variables to this function, i.e.
<pre>
notif="foo"; self::notifyAllPlayers( 'log', clienttraslate(notif)); // BAD
notif=clienttranslate("foo"); self::notifyAllPlayers( 'log', notif); // GOOD
</pre>

Translating arguments is a little bit more complex. It is using the "i18n" special argument as below:

<pre>
// In the following example, we translate the game log itself, but also the "card_name" argument:

self::notifyAllPlayers( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'points' => $points,
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.
) );
</pre>

To ensure the translation of the i18n argument will be made, clienttranslate must have been used somewhere, for instance:

<pre>
$this->card_types = array(
...
8 => array(
'name' => clienttranslate("Amulet of Air"),
...
</pre>

Pay attention when using 'i18n' argument when translating argument for client : do NOT use same argument for both translation AND key code for client side action (like using 'card_name' to move it on player board as described in the example). It's pretty obvious in the example, but it can be very tricky when translation is made at the end of the development (which is often the case). Use explicit argument name like 'card_name_translated' by example.

'''WARNING:''' you should NEVER use concatenation with clienttranslate, as it would result in a different string to translate at runtime than the one retrieved statically in the translation system, and so translation would not be applied. If you need to compose a string, use substitution and the i18n parameter (but you also have to pay attention not to compose sentences in a way that is dependent upon the English language specific syntax, or it may be impossible to translate correctly in another language: sometimes, you need multiple full sentences rather than relying on substitution).

'''self::_( "my string to translate" ):'''

This function returns a string translated in the language of CURRENT user (i.e. player who send the request to the server) (be careful, this is NOT the active player).

Most of the time, you don't need to translate strings on server side, except on the following 3 situations:
* When throwing an exception because the player did a forbidden move.

<pre>
// This will display a translatable red message to the player that just did some wrong action:
throw new BgaUserException( self::_('You must choose 3 cards') );

// ... notice the use of BgaUserException that signals that this exception is "expected". In theory, all exception that are expected should be translated.
</pre>

* In "yourgame.view.php", when creating the labels for the game interface used in your template (.tpl) file.

<pre>
$this->tpl['CARDS_FOR_YEAR_2'] = self::_("Your cards for year II");
</pre>

* Eventually, in your material.inc.php, if for example you need to use some string elements in your exceptions.

<pre>
// In material.inc.php, $this->energies[n]['nametr'] has been created with the self::_() method. Now we can do this:
throw new BgaUserException( self::_("To execute this action you need more: ").' '.$this->energies[$resource_id]['nametr'] );
</pre>

* Eventually, in your "getAllDatas" PHP method, as the data return by this method is used only by current user.

'''totranslate( "my string to translate" ):'''

This function works exactly like 'clienttranslate', except it tells BGA that the string is not needed on client side.

You should not use this function, except on the following cases:
* Statistics name in stats.inc.php
* Option names and option values name in gameoptions.inc.php

Translations

2020-11-08T13:28:45Z

Inaofr: /* On server side (PHP) */

{{Studio_Framework_Navigation}}

Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.

== How translation works? ==

When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.

Before the release of the game, BGA team will do the French translation of the game.

After the release of the game, the BGA players community will translate the game in every language.

== What should be translated? ==

Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages, ...

This does NOT include error messages that are not supposed to happen (unexpected errors).

== What rules should I follow for the original English strings? ==

For a coherent and homogeneous interface, here are some rules about ending a sentence with a final dot '.'

* As a general rule:
** If a sentence is displayed isolated in the interface => no final dot
** If a sentence is followed or could be followed by another sentence in the same interface space => final dot.

* In detail:
** No final dot:
*** button labels
*** section titles
*** menu elements
*** links triggering an isolated action
*** anything that is not a full sentence
*** current action in the status bar
** Final dot:
*** complete explanation sentence, that can be chained with another sentence
** We can tolerate a dot or no dot (but it should be consistent inside the game) for:
*** isolated tooltip / isolated small sentence
*** game log (no dot is usually preferable)
*** error messages (except if more than one sentence in the error message => final dot mandatory in this case)

Otherwise, you should try to follow as closely as possible the general style and format (including capitalization) used in the English rulebook and game material of the game.

== Focus on translating notifications ==

Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.

However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.

== WARNING: how to make sure your strings will be translated ==

For each game, our translation tool is doing a full scan of the code, looking for translator markers like "_()" or "clientranslate()"... (see below the list of translation markers).

If your original string is not "physically" inside one of this marker, it won't be translated.

<pre>
// Examples: the following strings will be translated:
var mystring_translated = _("my string"); // JS
$mystring_translated = self::_("my string"); // PHP
$mystring_translated = sprintf( self::_("my string with an %s argument"), $argument ); // PHP

// Examples: the following strings WILL NOT be translated:
$my_string = "my string";
$not_translated = self::_( $my_string ); // The original string is not bordered by a translator marker => no translation
$not_translated = self::_( sprintf( "my string with a %s argument", $argument ) ); // Same thing
</pre>

== How to not make translators crazy ;) ==

* When you need the same string twice, try to reuse exactly the same string (with the same case) to minimize the number of strings.
* Do not mark as translatable a game element that does not have to be translated (ex: if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:
<pre>self::_("First part of the string, ").$argument.' '.self::_("second part of the string")</pre>
Write instead:
<pre>sprintf( self::_("First part of the string, %s second part of the string"), $argument )</pre>
(or the equivalent "dojo.string.substitute" in Javascript)
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The more the string is a short insignificant string, the more difficult is the task for them. As a rule of thumb, try to avoid insignificant short strings. You can also leave a comment on what is the context of the string in the translation program (English to English) if you are the developer of the game.
* The BGA translation policy is to be flexible on grammar... We prefer to write "player gets 1 coin(s)" than write two versions of the same string for plural and singular - it reduces the number of strings to translate.
* Instead of writing nice strings like "With the effect of ZZZ, player XXX gets a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".
* Use present tense instead of past, i.e. "player gets wood" instead of "player got wood"
* Avoid using gender specific pronouns, i.e. instead of "player returns card to *his* hand" use "player returns card to *their* hand" or just avoid using it, i.e. "player picks up the card"

== On client side (Javascript) ==

On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.

Examples:
<pre>
// Get a string in player's language:
var translated = _("original english string");

// Get a string in player's language with parameter:
var translated = dojo.string.substitute( _("You can pick ${p} cards and discard ${d}"), {
p: 2,
d: 4
} );
</pre>

'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.

'''ANOTHER WARNING:''' you cannot use this function _() in the javascript object constructor, but you can achieve the same if you use it the setup method

== On server side (PHP) ==

On PHP side, you can use 3 different functions to specify that a string must be translated.

'''clienttranslate( "my string to translate" ):'''

This function is '''transparent''': it will return the original English string without any change. It's only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.

In general, you use clienttranslate:
* On your states.inc.php, for field "description" and "descriptionmyturn".

<pre>
"description" => clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),
</pre>

* On "material.inc.php", when defining texts for game material that must be displayed on client side.
<pre>
$this->card_types = array(

1 => array(
'name' => clienttranslate("Amulet of Air"), // Thus, we can use "_( card_name )" on Javascript side.
</pre>

* When sending a notification with "notifyAllPlayers" or "notifyPlayer", for the game log string and all game log arguments that need a translation.

<pre>
// A game log string with no argument:
self::notifyAllPlayers( 'pickLibraryCards', clienttranslate("Everyone draw cards from his library"), array() );
</pre>

As a consequence there is no point passing variables to this function, i.e.
<pre>
notif="foo"; self::notifyAllPlayers( 'log', clienttraslate(notif)); // BAD
notif=clienttranslate("foo"); self::notifyAllPlayers( 'log', notif); // GOOD
</pre>

Translating arguments is a little bit more complex. It is using the "i18n" special argument as below:

<pre>
// In the following example, we translate the game log itself, but also the "card_name" argument:

self::notifyAllPlayers( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'points' => $points,
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.
) );
</pre>

To ensure the translation of the i18n argument will be made, clienttranslate must have been used somewhere, for instance:

<pre>
$this->card_types = array(
1 => array(
'name' => clienttranslate("Amulet of Air"),
...
</pre>

Pay attention when using 'i18n' argument when translating argument for client : do NOT use same argument for both translation AND key code for client side action (like using 'card_name' to move it on player board as described in the example). It's pretty obvious in the example, but it can be very tricky when translation is made at the end of the development (which is often the case). Use explicit argument name like 'card_name_translated' by example.

'''WARNING:''' you should NEVER use concatenation with clienttranslate, as it would result in a different string to translate at runtime than the one retrieved statically in the translation system, and so translation would not be applied. If you need to compose a string, use substitution and the i18n parameter (but you also have to pay attention not to compose sentences in a way that is dependent upon the English language specific syntax, or it may be impossible to translate correctly in another language: sometimes, you need multiple full sentences rather than relying on substitution).

'''self::_( "my string to translate" ):'''

This function returns a string translated in the language of CURRENT user (i.e. player who send the request to the server) (be careful, this is NOT the active player).

Most of the time, you don't need to translate strings on server side, except on the following 3 situations:
* When throwing an exception because the player did a forbidden move.

<pre>
// This will display a translatable red message to the player that just did some wrong action:
throw new BgaUserException( self::_('You must choose 3 cards') );

// ... notice the use of BgaUserException that signals that this exception is "expected". In theory, all exception that are expected should be translated.
</pre>

* In "yourgame.view.php", when creating the labels for the game interface used in your template (.tpl) file.

<pre>
$this->tpl['CARDS_FOR_YEAR_2'] = self::_("Your cards for year II");
</pre>

* Eventually, in your material.inc.php, if for example you need to use some string elements in your exceptions.

<pre>
// In material.inc.php, $this->energies[n]['nametr'] has been created with the self::_() method. Now we can do this:
throw new BgaUserException( self::_("To execute this action you need more: ").' '.$this->energies[$resource_id]['nametr'] );
</pre>

* Eventually, in your "getAllDatas" PHP method, as the data return by this method is used only by current user.

'''totranslate( "my string to translate" ):'''

This function works exactly like 'clienttranslate', except it tells BGA that the string is not needed on client side.

You should not use this function, except on the following cases:
* Statistics name in stats.inc.php
* Option names and option values name in gameoptions.inc.php

Game layout: view and template: yourgamename.view.php and yourgamename yourgamename.tpl

2020-10-27T19:10:04Z

Inaofr: /* Variables */

{{Studio_Framework_Navigation}}

These 2 files work together to provide the HTML layout of your game.

Using these 2 files, you specify what HTML is rendered in your game client interface.

In <yourgame.tpl>, you can directly write raw HTML that will be displayed by the browser.

Example: extract of "hearts_hearts.tpl":

<pre>
<div id="myhand_wrap" class="whiteblock">
<h3>{MY_HAND}</h3>
<div id="myhand">
</div>
</div>
</pre>

== WARNING ==

Your view and your template are supposed to generate only the BASE layout of the game

You shouldn't try to setup the current game situation in the view: this is the role of your Javascript code. Why? Because you'll have to write Javascript code to put game elements in place anyway, and you don't want to write it twice :)

Example of things to generate in your view:
* The overall layout of your game interface (what is displayed where).
* The board and fixed elements on the board (ex: places for cards, squares, ...).

Example of things that shouldn't be generate by your view:
* Game elements that come and go from the game area.
* Game elements that normally hidden from players (other players cards, cards in the deck).

== phplib template system ==

BGA is using the phplib template system, used for example in PHPbb forums.

More details about how to use phplib template system here:
https://web.archive.org/web/20170506065401/http://www.phpbuilder.com:80/columns/david20000512.php3

== Variables ==

In your template ("tpl") file, you can use variables. Then in your view (".view.php") file, you fill these variables with value.

In the example above, "{MY_HAND}" is a variable. As you can see, a variable is uppercase characters border by "{" and "}".

To give a value to this variable in your view.php:

Examples:
<pre>

// Display a translated version of "My hand" at the place of the variable in the template
$this->tpl['MY_HAND'] = self::_("My hand");

// Display some raw HTML material at the place of the variable
$this->tpl['MY_HAND'] = self::raw( "<div class='myhand_icon'></div>" );

</pre>

WARNING: do not use a variable called {id} as it will interfere with action buttons.

WARNING: do not use a variable called {LB_[whatever]} as any variable starting with LB_ will interfere with the translation system.

== Blocks ==

Using "blocks", you can repeat a piece of HTML from your template several time.

You should use "blocks" whenever you have a block of HTML that must be repeated many times. For example, for ''Reversi'', we have to generate 64 (8x8) squares:

<pre>

(in reversi_reversi.tpl)

<div id="board">

<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div>


<div id="discs">
</div>
</div>

(in reversi.view.php)

$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}

</pre>

Explanations:
* You specify a block in your template file, using "BEGIN" and "END" keywords. In the example above, we are creating a block named "square".
* In your view, you declare your block using "begin_block" method.
* Then, you can insert as many block as you want to, using "insert_block" method.

The insert_block method takes 2 parameters:
* the name of the block to insert.
* an associative array you can use to assign values to template variables of this block. In the example above, there are 4 parameters in the block (X, Y, LEFT and TOP).

== Nested blocks ==

You can use nested blocks. In the example below, we are going to add a mini-board for each player of the game, with 4 card places on each of it:

<pre>

(In template file)


<div class="miniboard" id="miniboard_{PLAYER_ID}">

<div class="card_places">

<div id="card_place_{PLAYER_ID}_{PLACE_ID}">
</div>

</div>

</div>


(In view file)

$this->page->begin_block( "mygame_mygame.tpl", "card_place" ); // Nested block must be declared first
$this->page->begin_block( "mygame_mygame.tpl", "player" );

foreach( $players as $player_id => $player )
{
// Important: nested block must be reset here, otherwise the second player miniboard will
// have 8 card_place, the third will have 12 card_place, and so one...
$this->page->reset_subblocks( 'card_place' );

for( $i=1; $i<=4; $i++ )
{
$this->page->insert_block( "card_place", array(
'PLAYER_ID' => $player_id,
'PLACE_ID' => $i
)
);
}

$this->page->insert_block( 'player', array( 'PLAYER_ID' => $player_id );
}

</pre>

== Javascript templates ==

For game elements that come and go from the game area, we suggest you to define a Javascript template.

A Javascript template is defined in your template file like this:

(Reversi Token from Reversi example):
<pre>
<script type="text/javascript">

// Templates

var jstpl_disc='<div class="disc disccolor_${color}" id="disc_${xy}"></div>';

</script>
</pre>

Note: a section for javascript templates is already available at the end of your template skeleton file.

Then, you can use this javascript template to insert this piece of HTML in your game interface, like this:

<pre>
dojo.place( this.format_block( 'jstpl_disc', {
xy: x+''+y,
color: color
} ) , 'discs' );
</pre>

WARNING: always use lowercase for substitution variables in your Javascript templates, in order to avoid collision with phplib template variables (in particular, do not use ${ID}).

Note that '''you must translate''' any text arguments passed to ''this.format_block()'' that will be rendered on the screen, for example [[Translations#On_client_side_.28Javascript.29|using "_()"]].

== How to access game information from .view.php? ==

From your .view.php, you can access the following:

=== Access current player id===

<pre>
global $g_user;
$current_player_id = $g_user->get_id();
</pre>

=== Access game object ===

In your view file, "$this->game" contains an instance of your main game class.

Example:
<pre>

// Access to some game elements description described in your "material.inc.php":
$my_cards_types = $this->game->card_types;

// Access to any (public) method defined in my .game.php file:
$result = $this->game->myMethod();
</pre>

== Tips: displaying a nice button ==

From time to time, you need to display a standard button in your interface. BGA framework provides you a standard button that you can use directly in your interface:

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_gray"><span>My gray button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_red"><span>My red button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

Note: To see it in action, check for example a Coloretto game

Game layout: view and template: yourgamename.view.php and yourgamename yourgamename.tpl

2020-10-27T19:09:50Z

Inaofr: Add a warning on variable name.

{{Studio_Framework_Navigation}}

These 2 files work together to provide the HTML layout of your game.

Using these 2 files, you specify what HTML is rendered in your game client interface.

In <yourgame.tpl>, you can directly write raw HTML that will be displayed by the browser.

Example: extract of "hearts_hearts.tpl":

<pre>
<div id="myhand_wrap" class="whiteblock">
<h3>{MY_HAND}</h3>
<div id="myhand">
</div>
</div>
</pre>

== WARNING ==

Your view and your template are supposed to generate only the BASE layout of the game

You shouldn't try to setup the current game situation in the view: this is the role of your Javascript code. Why? Because you'll have to write Javascript code to put game elements in place anyway, and you don't want to write it twice :)

Example of things to generate in your view:
* The overall layout of your game interface (what is displayed where).
* The board and fixed elements on the board (ex: places for cards, squares, ...).

Example of things that shouldn't be generate by your view:
* Game elements that come and go from the game area.
* Game elements that normally hidden from players (other players cards, cards in the deck).

== phplib template system ==

BGA is using the phplib template system, used for example in PHPbb forums.

More details about how to use phplib template system here:
https://web.archive.org/web/20170506065401/http://www.phpbuilder.com:80/columns/david20000512.php3

== Variables ==

In your template ("tpl") file, you can use variables. Then in your view (".view.php") file, you fill these variables with value.

In the example above, "{MY_HAND}" is a variable. As you can see, a variable is uppercase characters border by "{" and "}".

To give a value to this variable in your view.php:

Examples:
<pre>

// Display a translated version of "My hand" at the place of the variable in the template
$this->tpl['MY_HAND'] = self::_("My hand");

// Display some raw HTML material at the place of the variable
$this->tpl['MY_HAND'] = self::raw( "<div class='myhand_icon'></div>" );

</pre>

WARNING: do not use a variable called {id} as it will interfere with action buttons.
WARNING: do not use a variable called {LB_[whatever]} as any variable starting with LB_ will interfere with the translation system.

== Blocks ==

Using "blocks", you can repeat a piece of HTML from your template several time.

You should use "blocks" whenever you have a block of HTML that must be repeated many times. For example, for ''Reversi'', we have to generate 64 (8x8) squares:

<pre>

(in reversi_reversi.tpl)

<div id="board">

<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div>


<div id="discs">
</div>
</div>

(in reversi.view.php)

$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}

</pre>

Explanations:
* You specify a block in your template file, using "BEGIN" and "END" keywords. In the example above, we are creating a block named "square".
* In your view, you declare your block using "begin_block" method.
* Then, you can insert as many block as you want to, using "insert_block" method.

The insert_block method takes 2 parameters:
* the name of the block to insert.
* an associative array you can use to assign values to template variables of this block. In the example above, there are 4 parameters in the block (X, Y, LEFT and TOP).

== Nested blocks ==

You can use nested blocks. In the example below, we are going to add a mini-board for each player of the game, with 4 card places on each of it:

<pre>

(In template file)


<div class="miniboard" id="miniboard_{PLAYER_ID}">

<div class="card_places">

<div id="card_place_{PLAYER_ID}_{PLACE_ID}">
</div>

</div>

</div>


(In view file)

$this->page->begin_block( "mygame_mygame.tpl", "card_place" ); // Nested block must be declared first
$this->page->begin_block( "mygame_mygame.tpl", "player" );

foreach( $players as $player_id => $player )
{
// Important: nested block must be reset here, otherwise the second player miniboard will
// have 8 card_place, the third will have 12 card_place, and so one...
$this->page->reset_subblocks( 'card_place' );

for( $i=1; $i<=4; $i++ )
{
$this->page->insert_block( "card_place", array(
'PLAYER_ID' => $player_id,
'PLACE_ID' => $i
)
);
}

$this->page->insert_block( 'player', array( 'PLAYER_ID' => $player_id );
}

</pre>

== Javascript templates ==

For game elements that come and go from the game area, we suggest you to define a Javascript template.

A Javascript template is defined in your template file like this:

(Reversi Token from Reversi example):
<pre>
<script type="text/javascript">

// Templates

var jstpl_disc='<div class="disc disccolor_${color}" id="disc_${xy}"></div>';

</script>
</pre>

Note: a section for javascript templates is already available at the end of your template skeleton file.

Then, you can use this javascript template to insert this piece of HTML in your game interface, like this:

<pre>
dojo.place( this.format_block( 'jstpl_disc', {
xy: x+''+y,
color: color
} ) , 'discs' );
</pre>

WARNING: always use lowercase for substitution variables in your Javascript templates, in order to avoid collision with phplib template variables (in particular, do not use ${ID}).

Note that '''you must translate''' any text arguments passed to ''this.format_block()'' that will be rendered on the screen, for example [[Translations#On_client_side_.28Javascript.29|using "_()"]].

== How to access game information from .view.php? ==

From your .view.php, you can access the following:

=== Access current player id===

<pre>
global $g_user;
$current_player_id = $g_user->get_id();
</pre>

=== Access game object ===

In your view file, "$this->game" contains an instance of your main game class.

Example:
<pre>

// Access to some game elements description described in your "material.inc.php":
$my_cards_types = $this->game->card_types;

// Access to any (public) method defined in my .game.php file:
$result = $this->game->myMethod();
</pre>

== Tips: displaying a nice button ==

From time to time, you need to display a standard button in your interface. BGA framework provides you a standard button that you can use directly in your interface:

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_gray"><span>My gray button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_red"><span>My red button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

Note: To see it in action, check for example a Coloretto game

Main game logic: Game.php

2020-05-07T21:18:05Z

Inaofr: /* Multiactivate player handling */

{{Studio_Framework_Navigation}}

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

== File Structure ==

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

Here is the basic structure:

* EmptyGame (constructor): where you define global variables.
* setupNewGame: initial setup of the game.
* getAllDatas: where you retrieve all game data during a complete reload of the game.
* getGameProgression: where you compute the game progression indicator.
* Utility functions: your utility functions.
* Player actions: the entry points for players actions.
* Game state arguments: methods to return additional data on specific game states ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#args more info here]).
* Game state actions: the logic to run when entering a new game state ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#action more info here]).
* zombieTurn: what to do it's the turn of a zombie player.

== Accessing player information ==

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

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

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

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

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

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

; getCurrentPlayerName()
: Get the "current_player" name
: Be careful using this method (see above).

; getCurrentPlayerColor()
: Get the "current_player" color
: Be careful using this method (see above).

; isCurrentPlayerZombie()
: Check the "current_player" zombie status. If true, player is zombie, i.e. left or was kicked out of the game.

== Accessing the database ==

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

'''IMPORTANT'''

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

; DbQuery( $sql )
: This is the generic method to access the database.
: It can execute any type of SELECT/UPDATE/DELETE/REPLACE query on the database.
: You should use it for UPDATE/DELETE/REPLACE queries. For SELECT queries, the specialized methods below are much better.

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

; getCollectionFromDB( $sql, $bSingleValue=false )
: Returns an associative array of rows for a sql SELECT query.
: The key of the resulting associative array is the first field specified in the SELECT query.
: The value of the resulting associative array if an associative array with all the field specified in the SELECT query and associated values.
: First column must be a primary or alternate key.
: The resulting collection can be empty.
: If you specified $bSingleValue=true and if your SQL query request 2 fields A and B, the method returns an associative array "A=>B"

Example 1:
<pre>
self::getCollectionFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );

Result:
array(
1234 => array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),
1235 => array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )
)
</pre>
Example 2:
<pre>
self::getCollectionFromDB( "SELECT player_id id, player_name name FROM player", true );

Result:
array(
1234 => 'myuser0',
1235 => 'myuser1'
)

</pre>

; getNonEmptyCollectionFromDB( $sql )
: Idem than previous one, but raise an exception if the collection is empty

; getObjectFromDB( $sql )
: Returns one row for the sql SELECT query as an associative array or null if there is no result
: Raise an exception if the query return more than one row

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

Result:
array(
'id'=>1234, 'name'=>'myuser0', 'score'=>1
)
</pre>

; getNonEmptyObjectFromDB( $sql )
: Idem than previous one, but raise an exception if no row is found

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

Example 1:
<pre>
self::getObjectListFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );

Result:
array(
array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),
array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )
)
</pre>
Example 2:
<pre>
self::getObjectListFromDB( "SELECT player_name name FROM player", true );

Result:
array(
'myuser0',
'myuser1'
)

</pre>

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

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

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

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

<pre>

</pre>

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

== Use globals ==

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

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

'''initGameStateLabels'''

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

You can define up to 79 globals, with IDs from 10 to 89 (inclusive). You must '''not''' use globals outside this range, as those values are used by other components of the framework.

<pre>
self::initGameStateLabels( array(
"my_first_global_variable" => 10,
"my_second_global_variable" => 11
) );
</pre>

'''setGameStateInitialValue( $value_label, $value_value )'''

Initialize your global value. Must be called before any use of your global, so you should call this method from your "setupNewGame" method.

'''getGameStateValue( $value_label )'''

Retrieve the current value of a global.

'''setGameStateValue( $value_label, $value_value )'''

Set the current value of a global.

'''incGameStateValue( $value_label, $increment )'''

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

Return the final value of the global.

== Game states and active players ==

=== Activate player handling ===

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

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

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

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

=== Multiactivate player handling ===

; $this->gamestate->setAllPlayersMultiactive()
: All playing players are made active. Update notification is sent to all players (triggers onUpdateActionButtons).
: Usually, you use this method at the beginning (ex: "st" action method) of a multiplayer game state when all players have to do some action.

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

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

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

; $this->gamestate->setPlayerNonMultiactive( $player_id, $next_state )
: During a multiactive game state, make the specified player inactive.
: Usually, you call this method during a multiactive game state after a player did his action.
: If this player was the last active player, the method trigger the "next_state" transition to go to the next game state.
: returns true if state transition happened, false otherwise

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

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

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

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

; $this->checkAction( $actionName, $bThrowException=true )
: Check if an action is valid for the current game state, and optionally, throw an exception if it isn't.
: The action is valid if it is listed in the "possibleactions" array for the current game state (see game state description).
: This method MUST be the first one called in ALL your PHP methods that handle player actions, in order to make sure a player doesn't perform an action not allowed by the rules at the point in the game.
: If "bThrowException" is set to "false", the function returns '''false''' in case of failure instead of throwing an exception. This is useful when several actions are possible, in order to test each of them without throwing exceptions.

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

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

== Players turn order ==

'''getNextPlayerTable()'''

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

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

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

'''getPrevPlayerTable()'''

Same as above, but the associative array associate the previous player around the table.

'''getPlayerAfter( $player_id )'''

Get player playing after given player in natural playing order.

'''getPlayerBefore( $player_id )'''

Get player playing before given player in natural playing order.

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

== Notify players ==

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

'''IMPORTANT'''

Notifications are sent at the very end of the request, when it ends normally. It means that if you throw an exception for any reason (ex: move not allowed), no notifications will be sent to players.
Notifications sent between the game start (setupNewGame) and the end of the "action" method of the first active state will never reach their destination.

'''notifyAllPlayers( $notification_type, $notification_log, $notification_args )'''

Send a notification to all players of the game.

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

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

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

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

If you define a real string here, you should use "clienttranslate" method to make sure it can be translate.

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

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

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

Complete notifyAllPlayers example (from "Reversi"):

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

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

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

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

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

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

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

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

'''notifyPlayer( $player_id, $notification_type, $notification_log, $notification_args )'''

Same as above, except that the notification is sent to one player only.

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

Important: the variable for player name must be ${player_name} in order to be highlighted with the player color in the game log

== About random and randomness ==

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

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

=== Dices and bga_rand ===

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

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

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

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

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

=== shuffle and cards shuffling ===

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

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

=== Other methods ===

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

== Game statistics ==

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

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

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

Create a statistic entry with a default value.
This method must be called for each statistics of your game, in your setupNewGame method.

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

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

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

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

Set a statistic $name to $value.

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

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

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

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

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

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

== Translations ==

See [[Translations]]

== Manage player scores and Tie breaker ==

=== Normal scoring ===

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

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

Examples:
<pre>

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

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

</pre>

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

=== Tie breaker ===

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

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

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

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

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

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

=== Co-operative game ===

To make everyone lose in full-coop game:

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

And score zero to everyone.

=== Semi-coop ===

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

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

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

Examples:
* Coup
* Not Alone
* Werewolves
* Quantum

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

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

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

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

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

=== Solo ===

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

=== Player elimination ===

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

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

Usage:

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

=== Scoring Helper functions ===

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

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

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

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

== Reflexion time ==

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

== Undo moves ==

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

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

; function undoSavepoint( )
: Save the whole game situation inside an "Undo save point".
: There is only ONE undo save point available (see BGA Undo policy).

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

== Managing errors and exceptions ==

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

; throw new BgaUserException ( $error_message)
: Base class to notify a user error
: You must throw this exception when a player wants to do something that he is not allowed to do.
: The error message will be shown to the player as a "red message", so it must be translated.
: Throwing such an exception is NOT considered a bug, so it is not traced in BGA error logs.

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

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

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

== Zombie mode ==

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

While developing your zombie mode, keep in mind that:
* Do not refer to the rules, because this situation is not planned by the rules.
* Try to figure that you are playing with your friends and one of them has to leave: how can we finish the game without killing the spirit of the game?
* The idea is NOT to develop an artificial intelligence for the game.

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

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

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

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

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

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

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

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

== Player color preferences ==

BGA players (Club members) may now choose their preferred color for playing. For example, if they are used to play green for every board game, they can select "green" in their BGA preferences page.

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

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

// Favorite colors support : if set to "true", support attribution of favorite colors based on player's preferences (see reattributeColorsBasedOnPreferences PHP method)
'favorite_colors_support' => true,

Then, on your main <your_game>.game.php file, find the "reloadPlayersBasicInfos" call in your "setupNewGame" method and replace :

$sql .= implode( $values, ',' );
self::DbQuery( $sql );
self::reloadPlayersBasicInfos();

By :

$sql .= implode( $values, ',' );
self::DbQuery( $sql );
self::reattributeColorsBasedOnPreferences( $players, array( /* LIST HERE THE AVAILABLE COLORS OF YOUR GAME INSTEAD OF THESE ONES */"ff0000", "008000", "0000ff", "ffa500", "773300" ) );
self::reloadPlayersBasicInfos();

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

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

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

Colours currently listed as a choice in preferences:

* #ff0000 Red
* #008000 Green
* #0000ff Blue
* #ffa500 Yellow
* #000000 Black
* #ffffff White
* #e94190 Pink
* #982fff Purple
* #72c3b1 Cyan
* #f07f16 Orange
* #bdd002 Khaki green
* #7b7b7b Gray

== Debugging and Tracing ==

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

self::debug("Ahh!");
self::dump('my_var',$my_var);

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