BGB v2.29
BGB v2.28
BGB v2.22
BGB v2.19
BGB v2.16
BGB v2.14
BGB v2.10
BGB v2.06
If there is a board game that you want a Smart Scoresheet (Game Template) for but it currently doesn't exist on the BoardGameBuddy server, you can write it yourself!
You can even send it to me to put up on the BoardGameBuddy server for everyone to use! (best current method is to send a Private Message to user AndyMo on the BoardGameGeek.com website)
A Game template is just a text file that outlines how many scoring columns you want and what they do. It also defines fancy things like background images, colours, and fun icons.
To create a Smart Game Template for BoardGameBuddy all you need is:
As of Android 10, the Game Templates are kept in the storage area of your device at:
android/data/ca.boardgamebuddy.free/files/GameTemplates.
When you plug your device into your computer and open a File Explorer / Finder window you should be able to navigate to there.
Each game scoresheet gets is own folder containing the Game Template file, and all the images that you want to use.
A game Template is just a text file written in XML. XML is a format that both humans and computers can read. You can copy-paste an existing Game Template and modify that, or use the big reference guide below to help create one from scratch.
Also in this folder are any additional files that you want to use, such as backgrounds, images, fonts, etc.
Key things to think about
Download the Game Template of a similar game, or download the Game Template "Andy's Fake Game" to your copy of BoardGameBuddy - there are examples of different ways to score in there.
Technical steps:
I hope this helps you get started. If you need more help come to the BoardGameBuddy Guild on BoardGameGeek.com.
Game templates are written in XML, which is a format that is easy to read for both the application and humans. The following are the main blocks of a BoardGameBuddy Game Template:
<GameTemplate>
<BGBV>2.0</BGBV>
<game>
information about the board game this template is for (eg. Catan)
</game>
<template>
information about the template itself, such as who wrote it, images to use etc.
</template>
<expansion>
optional blocks defining what scoring columns are specific to particular expansions
there can be multiple <expansion> blocks
</expansion>
<column name="MY_SCORING_COLUMN">
Columns for keeping track of the various scoring elements of the game
and how they interact with the user. This is where you chose what dialogs or
events happen when the user touches the screen.
There can be multiple column blocks
</column>
</GameTemplate>
Everything needs to be inside a GameTemplate tag.
example:
<GameTemplate>
..
..
..
</GameTemplate>
.
The minimum version of BoardGameBuddy required to run this Game Template. If a new feature is implemented in BoardGameBuddy the future and your template relies on that feature, this is where we can help let the user know they need to upgrade.
For now this should be 2.0.
example
<GameTemplate>
<BGBV>2.0</BGBV>
..
..
..
</GameTemplate>
.
the game tag holds the characteristics of the game that you are playing (eg. Settlers of Catan, Monopoly)
full example.
<!-- Game Information, including initial base game columns -->
<!-- if no <usecolumns> tag, then all columns EXCEPT those listed in expansions will be used by the program-->
<game>
<name>Catan</name>
<bggID>13</bggID>
<image>catan.png</image>
<winScore>10</winScore>
</game>
Details of the sub-tags of <game> follow:
.
(required)
Use this to tell everyone what game this template is for. This is the name that people will search for when downloading new games from the cloud.
example:
<name>Monopoly</name>
.
(optional)
Use this tag to specify the filename of the Game Image, usually a photo of the game box. You can easily find and download one from BoardGameGeek.com or by using Google image search.
example:
<image>box_photo.jpg</image>
.
(optional)
Here you can store this game's numeric ID from BoardGameGeek.com. This is currently not used, but may be used in the future.
You can find it by going to the main page for the game on BoardGameGeek.com and look for BGG Item ID under Community Stats (usually)
example (for the game Wingspan):
<bggID>266192</bggID>
.
(optional - a trigger score to put a glowing box around a players total)
This tag highlights a player's score by putting a glowing box on their total score when it is equal to or greater the specified value. This is usually used to indicate that a player has reached the end-of-game-state. **This will not end the game. **
If <winScore> is defined in <game> as well as one or more <expansion> tags, the highest value will be used.
example. Any player that gets 10 or more points will get the glow box on their score:
<winScore>10</winScore>
.
(optional - a trigger score to put a glowing box around a players total)
This is the opposite of <winScore>, in that it highlights a player's score when it is equal to or lower than the stated value. This is for those games that count down to an initial loser as opposed to those that count up for a winner. **This will not end the game. **
If <loseScore> is defined in <game> as well as one or more <expansion> tags, the lowest value will be used.
example:
<1-- in 6 nimnt! players start at 66 points and first one to zero triggers the end of the game -->
<startingScore>66</startingScore>
<loseScore>0</loseScore>
NOTE: you can have both a winScore and a loseScore. The glow-box indicator will light up if either of the conditions is triggered.
.
(optional)
This only affects the automatic guess of the winner when you press Game Over and the Archive-Game dialog shows up. It doesn't impact the main scoring at all.
example:
<!-- in Golf or Slide 5, the player with the lowest score wins -->
<lowestScoreWins>true</lowestScoreWins>
.
(optional)
This just starts every player with an initial value at the start of a game.
This value is not be added again after multiple rounds if in <roundsMode>.
example:
<!-- in 6 nimnt! players start at 66 points and first one to zero triggers the end of the game -->
<startingScore>66</startingScore>
<loseScore>0</loseScore>
.
(in the base game)
(very optional)
If there is no <useColumns> tag in the <game> block, then the base game will use all columns except those defined in the expansions. This is the recommended usage.
You can use the <useColumns> tag in the <game> block if you wish, and in that case the base game will only show those scoring columns that you list.
For more detail, see the <useColumns> entry under <expansions>
The <template> tag holds information about the template itself, like who wrote it. It also has some customizations such as default background image or font.
Here is a full example of a template definition for the game 7 Wonders. Further details on the additional tags is found below.
<template>
<name>Supports all expansions up to Armada</name>
<description>Optionally choose any available expansion. Smart-Scoring of COINS and SCIENCE cards. This template will likely be mostly used for end of game scoring, but you could use it during the game as well.</description>
<background>zeus.jpg</background>
<author>Andy Mo</author>
<language>EN</language>
<font>cafeteria-bold.ttf</font>
<id>7w_BGB_GT1581013081388yytf</id>
<date>1581020605746</date>
<version>2</version>
</template>
.
This is the name of the Template, which should be a one-line description of this template. This is also what shows up under the Game Name when a user is picking a game or searching the cloud for new templates.
In the example below you can see the Template <name> underneath the game name.
example:
<name>Supports all expansions up to Armada</name>
.
This tag is a more verbose description of the features of the template. Users see this when they tap on a template for more information.
(note that the features and expansion information shown here are automatically generated)
example:
<description>Optionally choose any available expansion. Smart-Scoring of COINS and SCIENCE cards. This template will likely be mostly used for end of game scoring, but you could use it during the game as well.</description>
.
(optional)
Use this tag to specify a custom background image when using this template.
example:
<background>wood_background.jpg</background>
.
(optional)
This tag allows you to specify an alternate background image for when the device is in Portrait orientation. If not specified, then the image in <background> will be used and rotated accordingly if necessary.
example:
<background>castle_landscape.jpg</background>
<verticalBackground>castle_portrait.jpg</verticalBackground>
.
(optional)
Use this tag to define a custom divider image between the rows of player scores. For example this image (200x25 px) would look like this on the scoring screen:
example:
<divider>road.png</divider>
.
(optional)
Use this tag to put your name so we know who created the template (and who to thank!)
example:
<author>John Smith the template master</author>
.
(optional)
The language tag tells the user what language the template is written in (English, French, Spanish ...). It is not used by the program except for in the download listings to identify the language.
The two-letter international short code should be used to specify the language (eg. EN, FR, ES ... )
example:
<language>FR</language>
.
You can tell BoardGameBuddy to use a different font on the scoring screen by specifying the file name here.
example:
<font>comic_sans.ttf</font>
.
(optional)
Setting <roundsMode> to 'true' will make the last column show the current overall total of all rounds/games played, instead of just the round in play.
Note that means there is no automatically created column for the total of the current round - you would have to create that column yourself, just like creating any other scoring column, and use <scoring>0</scoring> so that the app doesn't count your total twice.
.
(optional)
Use this tag to change the word that at the top left of the screen next to the current round number. If a game consists of several rounds you may wish BGB to say 'round'. If you are playing a short game multiple times you may wish this to say 'game'. Or 'battle'. Whatever you wish.
When not specified, the default value is 'Game'.
example: Each round in The Crew: Quest for Planet Nine is called a 'MISSION':
<game>
<name>The Crew: Quest for Planet Nine</name>
<bggID>284083</bggID>
<image>crewbox.jpg</image>
</game>
<template>
<name>Simple attempt tracking for your team.</name>
<description>Create your crew, but just score on the first player. And the end of each mission press the next round button at the top.</description>
<background>space.jpg</background>
<roundsMode>true</roundsMode>
<roundName>Mission</roundName>
<font>AMOSB__.TTF</font>
</template>
(optional)
Numbers in columns that are automatically calculated (ie. they are not inputs for the user) are coloured differently. The default is a cyan-blue colour, however you can change that to match your template theme using this tag.
<template>
<name>Make your bids and it determines scores</name>
...
<calcTextColour>255,215,0</calcTextColour>
</template>
These tags are automatically generated and added to the XML file when it is uploaded to the BGB database. You don't have to worry about them.
A lot of games these days have 'expansions' that you can optionally add to your game session. You can define multiple game expansions using the <expansion> tag, which will then add the additional scoring columns required to support them. You can also change other features like the background and the end-of-game-state score.
When one or more expansions are defined in your Game Template file the user will be prompted to optionally add the expansions to their game session :
here is a complete example of a couple of expansions in a template :
<!-- OPTIONAL EXPANSIONS. User will be prompted to choose which ones to use
- you should specify which columns are specific to this expansion by listing the
column tags (separated by commas) in the <usecolumns> tag
- a background image here will override the main template background. if not used, delete the <background> line -->
<expansion>
<name>The Abbott</name>
<description>Adds a scoring column for the Abbott</description>
<usecolumns>ABBOTT</usecolumns>
</expansion>
<expansion>
<name>Traders and Builders</name>
<bggID>5405</bggID>
<description>Adds smart scoring for Collected Goods. A column for each good you collect, and a smart column that figures out the points.</description>
<usecolumns>GOODSA,GOODSB,GOODSC,GOODSSCORE</usecolumns>
</expansion>
<expansion>
<name>The Princess and the Dragon</name>
<bggID>15158</bggID>
<description>Adds a scoring column for the Fairy. Tapping the score auto-increments by +1.</description>
<usecolumns>FAIRY</usecolumns>
</expansion>
And it looks like this when the user gets to choose what expansion they would like to use:
Descriptions of the sub-tags: .
(required)
Here you can define the name of the expansion that will be shown in the list.
example:
<expansion>
<name>Traders and Builders</name>
</expansion>
.
(optional)
Here you can enter BoardGameGeek.com's unique ID number for this expansion. Currently this is not used by the program but is here for potential future use (like play recording).
To find out what the BGG ID is, you have to do a Search for the expansion on boardgamegeek.com and you will see the number in the address bar of your browser, or on it's detailed page as "BGG Item ID"
example:
<expansion>
<name>Traders and Builders</name>
<bggID>5405</bggID>
</expansion>
.
(optional)
Use this tag if you want to have a different background image when using this expansion.
example:
<expansion>
<name>Traders and Builders</name>
<background>traders.jpg</background>
</expansion>
.
(optional)
This tag allows you to specify an alternate background image for when the device is in Portrait orientation. If not specified, then the image in <background> will be used and rotated accordingly if necessary.
example:
<background>castle_landscape.jpg</background>
<verticalBackground>castle_portrait.jpg</verticalBackground>
.
(optional - a trigger score to put a glowing box around a players total)
This tag sets the trigger for when a glowing box will appear on the player's total score. This is usually used to indicate that a player has reached the end-of-game-state. This will not end the game.
<winScore> within an expansion tag will override any <winScore> value defined in the base <game>
example, the base game of Catan triggers end game state at 10 points, but this expansion changes it to 13:
<expansion>
<name>Seafarers of Catan</name>
<winScore>13</winScore>
</expansion>
.
(for expansions)
(optional)
This tag identifies what scoring columns this expansion adds to the base game. If listed here, these scoring columns will not appear in the base game or any other expansion (unless that expansion specifies the same column as well).
List the scoring COLUMN_NAMEs here, separated by commas.
example: in the Carcassone expansion Traders and Builders you get a score based on the number of each good you collect. These are not required in the regular version of Carcassonne, so we identify these scoring columns for the expansion and not the base game:
<expansion>
<name>Traders and Builders</name>
<description>Adds smart scoring for Collected Goods. A column for each good you collect, and a smart column that figures out the points.</description>
<usecolumns>GOODSA,GOODSB,GOODSC,GOODSSCORE</usecolumns>
</expansion>
.
(for expansions)
(optional)
This tag identifies what scoring columns from the base game should not be used when selecting this expansion. It is essentially the opposite of the <useColumns> tag.
This tag is a more verbose description of the features of the expansion. Users see this when they are choosing what expansions to use for their scoring round. Try to give a brief idea of what template features you are using in this expansion.
example:
<expansion>
<name>Traders and Builders</name>
<description>Adds smart scoring for Collected Goods. A column for each good you collect, and a smart column that figures out the points.</description>
</expansion>
.
Scoring columns are the primary feature that users interact with. A scoring column tallies objects or scores, depending on the game. You define all the characteristics of a scoring column within <column> .
It is important that you give each column a COLUMN NAME so that you can reference it elsewhere in the Game Template XML file (eg. assigning it to a particular expansion, or in a scoring formula)
example:
<column name="SETTLEMENTS">
...
...
</column>
<column name="CITIES">
...
...
</column>
Column names must:
Here are some working examples of a column definition. Note this only shows a few of the options available. Further delaits follow for each tag.
<column name="SETTLEMENTS">
<title show="false">Settlements</title>
<info>Add a settlement by tapping on your Settlement count. You get 1 point for each. </info>
<imageName>settlement.png</imageName>
<type>INPUT</type>
<startingValue>0</startingValue>
<click>RUN_FORMULA</click>
<formula>#SETTLEMENTS# = #SETTLEMENTS# + 1</formula>
<historyText>Built a Settlement</historyText>
</column>
<column name="LROAD">
<title show="true">Longest Road</title>
<info>Claim the Longest Road by tapping here, scoring 2 points. It will be automatically be removed from other players. (tap again to un-claim the Longest Road and assign to nobody) </info>
<imageName>longestroad.png</imageName>
<type>INPUT</type>
<startingValue>0</startingValue>
<startingToggle>false</startingToggle>
<click>TOGGLE_EXCLUSIVE</click>
<formula>#LROAD# = 2</formula>
<historyText>Claimed longest road</historyText>
</column>
.
This tag defines the title of the scoring column as seen by the user. It is displayed at the top of the scoring column (optionally) and in the info-help dialog. (see the <info> tag below for more details).
If <title show="true"> then the title will be displayed in the scoring column header. This is useful when:
if <title show="false"> then the title will not be displayed in the scoring column header, however it will still be visible on the information pop-up when someone taps on the scoring column header (see the <info> tag below for more details)
example code and image:
<column name="CITIES">
<title show="false">Cities</title>
...
</column>
<column name="LROAD">
<title show="true">Longest Road</title>
...
</column>
.
(optional)
This tag gives the user some helpful information on what is happening in this scoring column. It is a good place to let the user know if the column is tracking objects (like cities) or points, and how to interact with it.. When a user taps on the top header of a scoring column the Information Pop-up appears, showing the column title and any text that you define in <info>
examples:
<column name="CITIES">
<title show="false">Cities</title>
<info>Add a city by tapping on your City count (your settlement count is auto reduced by 1).
You get 2 points for each City. </info>
</column>
<column name="LROAD">
<title show="true">Longest Road</title>
<info>Claim the Longest Road by tapping here, scoring 2 points. It will be automatically
be removed from other players. (tap again to un-claim the Longest Road and assign to nobody) </info>
</column>
Result: (Notice that the column's <title> is automatically added to the information pop-up.)
.
NOTE: xml does not play well with some symbols, so they need to be replaced with the following:
operation | replace with | example |
---|---|---|
\n (a new line) | | <info>This description has two lines. This is the second line</info> |
(optional)
This is where you can tell the program what icon you want on the top of the scoring column by identifying the filename of the image file.
example, adding the following image :
<column name="CITIES">
<title show="false">Cities</title>
<imageName>city_token.png</imageName>
</column>
result:
.
(optional)
This tag will highlight the scoring column with a specific colour.
Example from the game 7 Wonders (which has a lot of colour cards):
<column name="MILITARY">
<title show="false">Military Conflicts</title>
<imageName>military.png</imageName>
<color>255,0,0</color>
</column>
<column name="COINS">
<title show="false">Coins</title>
<imageName>coins.png</imageName>
<color>248,222,127</color>
</column>
<column name="BLUECARDS">
<title show="false">Civilian Structures (blue)</title>
<imageName>bluecard.png</imageName>
<color>0,0,255</color>
</column>
<column name="YELLOWCARD">
<title show="false">Commercial Structures (yellow)</title>
<imageName>yellowcard.png</imageName>
<color>255,255,0</color>
</column>
<column name="PURPLECARD">
<title show="false">Guilds (purple)</title>
<imageName>purplecard.png</imageName>
<color>128,0,128</color>
</column>
resulting in the following :
.
This tells the program what type of scoring column this is. Valid types are:
type | description |
---|---|
INPUT | user will be able to click on this value to enter or change. What effect happens is defined by the <click> tag. |
AUTO_FORMULA | the value is calculated automatically by a formula in <formula>. User will not be able to manually modify |
TOGGLE_FORMULA | Acts like AUTO_FORMULA, however the user can click on the value to toggle between the formula result and zero. |
NOTHING | (this is the default) |
Examples:
<column name="SETTLEMENTS">
<title show="false">Settlements</title>
<type>INPUT</type>
<click>RUN_FORMULA</click>
<formula>#SETTLEMENTS# = #SETTLEMENTS# + 1</formula>
</column>
<column name="DEVCARDS">
<title show="false">Development Cards</title>
<type>INPUT</type>
<click>OPEN_SCORE_GRID</click>
</column>
// notice how the followwing formula is calculated using a value from COINS
<column name="COINSCORE">
<title show="true">Coin Score</title>
<info>You get a Victory Point for every 3 coins that you have</info>
<type>AUTO_FORMULA</type>
<formula>#COINSCORE# = ROUNDDOWN[#COINS#/3]</formula>
</column>
.
(optional)
Defines the value of this column at the start of the game. Defaults to 0.
Example:
// for example, a game usually starts you at Empire Level 1, not 0.
<column name="EMPIRE_LEVEL">
<title show="true">Empire Level</title>
<type>INPUT</type>
<startingValue>1</startingValue>
</column>
<column name="LIFE">
<title show="true">Life Counter</title>
<type>INPUT</type>
<startingValue>20</startingValue>
</column>
.
(optional)
If your scoring column is a TOGGLE input, this is where you define the value of a toggled input at the start of the game. Defaults to false (i.e. not toggled).
Applies to
Example:
<column name="LROAD">
<title show="true">Longest Road</title>
<type>INPUT</type>
<startingToggle>false</startingToggle>
<click>TOGGLE_EXCLUSIVE</click>
</column>
.
(optional)
Defines the minimum value allowed in the column. Default is -999,999.
Example:
<column name="CITIES">
<title show="false">Cities</title>
<type>INPUT</type>
<startingValue>0</startingValue>
<min>0</min> // you can't have negative cities
</column>
<column name="EMPIRE_LEVEL">
<title show="true">Empire Level</title>
<type>INPUT</type>
<startingValue>1</startingValue>
<min>1</min> // you can't be below Empire Level 1
<max>6</max> // maximum Empire Level is 6
</column>
.
(optional)
Defines the maximum value allowed in the column. Default is 999,999.
Example:
<column name="EMPIRE_LEVEL">
<title show="true">Empire Level</title>
<type>INPUT</type>
<startingValue>1</startingValue>
<min>1</min> // you can't be below Empire Level 1
<max>6</max> // maximum Empire Level is 6
</column>
.
(optional)
If the user clicks on this column, this tag defines what action the program will perform. Options are:
option | description |
---|---|
PLUS_MINUS_BUTTONS | the left and right halves of the score box will be invisible + / - buttons |
OPEN_SCORE_GRID | A scoring grid will open |
TOGGLE | The value of the column will toggle betwen 0 and the value set in ##### |
TOGGLE_EXCLUSIVE | Same as TOGGLE, but only one player can get the score. |
RUN_FORMULA | Run the formula defined in <formula> |
OPEN_SCORE_ADJUST | Opens the manual score adjustment dialog |
OPEN_SCORE_TRAIN | Opens a score dialog that works well for a popular line of train games |
Further details on each of these options are below :
This will make the left and right halves of a scoring box act like invisible + / - buttons, like in the Simple Scoring mode.
This example is a simple in-game resource tracker (no scoring). The user can simply tap the left or right side of the respective resource count to increase or decrease it.
<column name="POWER">
<title show = "false">Power</title>
<info>Tap on the left or right of the cell to decrease or increase this resource</info>
<imageName>power.png</imageName>
<type>INPUT</type>
<click>PLUS_MINUS_BUTTONS</click>
<historyText>Added / spent power resource</historyText>
<scoring>0</scoring>
</column>
Here is a screen capture of the above scoresheet. I took it immediately after pressing the right side of the Power resource:
This will open up a dialog offering the user a grid of quick-scoring buttons based on values you provide via the<values> tag.
Example 1 (from Carcassonne):
<column name="MONASTARIES">
<title show="true">Monastaries</title>
<type>INPUT</type>
<click>OPEN_SCORE_GRID</click>
<values>1,2,3,4,5,6,7,8,9</values>
</column>
will open the following Score Grid:
Example 2 (from 7 Wonders):
<column name="MILITARY">
<title show="false">Military Conflicts</title>
<type>INPUT</type>
<click>OPEN_SCORE_GRID</click>
<values>5,3,1,-1</values>
</column>
will open the following Score Grid:
And a real busy example 3 (from Ticket To Ride, end of game ticket counting). Notice the order the values are listed to give the two-column effect on the Score Grid :
<column name="TICKETS">
<type>INPUT</type>
<click>OPEN_SCORE_GRID</click>
<values>2,3,4,5,-2,-3,-4,-5,6,7,8,9,-6,-7,-8,-9,10,11,12,13,-10,-11,-12,-13,14,15,16,17,-14,-15,-16,-17,18,19,20,21,-18,-19,-20,-21,22,23,24,25,-22,-23,-24,-25</values>
<pinned>true</pinned>
</column>
will open the following Score Grid:
.
This will open up a dialog offering the user a grid for quick multiplication scoring. The dialog configuration is based on values you provide via the<values> tag. This is useful for games where you get X points per tile/meeple/carrot. (eg. Carcassonne, KingDomino)
Behaviour:
The multiplier dialog is configured using entries in the <values> tag. (apologies for having RIGHT and LEFT switched, but we're kind of stuck with it now 😃 ):
or optionally:
where
Other options:
The right/bottom grid should have the same or more numbers as the top/left.
Example from Carcassone :
<!-- in Carcassonne, when you complete a City you score a certain number of points for every tile.
since this is usually 2 points-per-tile, the multiplier defaults to 2 (but can be easily changed) -->
<column name="CITIES">
<title show="true">Cities</title>
<type>INPUT</type>
<click>OPEN_MULTIPLIER_GRID</click>
<values>20,4,0,2</values>
<labels>Tiles, VP/Tile</labels>
</column>
Gives us the following dialog. Notice that the selected values can be manually edited to any number.
.
another example from Kingdomino:
<!-- In this example from Kingdomino, a dialog opens allowing the user to say how many CROWNS they have on their Swamps(1-12), and multiply it by the number of Swamp TILES they have(1-20). The starting values are 1 and 0 respectively. -->
<column name="SWAMPS">
<title show="false">Swamps</title>
<info>Score your completed Swamps section of your Kingdom here. </info>
<color>185,174,149</color>
<startingValue>0</startingValue>
<min>0</min>
<type>INPUT</type>
<click>OPEN_MULTIPLIER_GRID</click>
<values>20,12,0,1</values>
<labels>Tiles,Crowns</labels>
<historyText>Scored a group of swamps</historyText>
</column>
Give us the following dialog:
and one more example from Mr.Cabbagehead's Garden. In this game the vegetables score from 3 to 8 points depending on what vegetable, so we will only show values 3-8 in the left grid. You can only score a vegetable when you have at least 2 of them, so the right grid starts at 2.
<column name="VEGGIES">
<title show="false">Vegetables</title>
<info>Score groups of vegetables here.</info>
<type>INPUT</type>
<click>OPEN_MULTIPLIER_GRID</click>
<values>9,8,0,3,2,3</values>
<labels>Count,Points per</labels>
<min>0</min>
<imageName>vegetables.png</imageName>
<historyText>Scored a group of vegetables</historyText>
</column>
WHen the user taps this column the TOGGLE function will alternate between TRUE and FALSE. When the toggle is TRUE this column evaluates the formula in <formula>.
Example:
<!-- pressing a player score in this column will give that player 15 pts.
pressing it again will remove the 15pts and set back to 0. -->
<column name="ALVIN">
<title show="false">Alvin</title>
<info>The player with the most Alvin cards scores 15pts. All players tied for most get the 15pts.</info>
<type>INPUT</type>
<click>TOGGLE</click>
<formula>#ALVIN# = 15</formula>
<startingToggleState>false</startingToggleState>
</column>
tricky TOGGLE example from & Wonders:
<!-- with the Great Projects expansion, you may earn a "science token" which gives you 3pts for each set of
the 3 science cards you have. If you get that token you just tap the column and it will calculate the
extra points you get based on the values in the science card columns (GREENA, GREENB, GREENC) -->
<column name="SCIENCE3PT">
<title show="false">Science Token (Projects)</title>
<info>If you get a special science token from completing a Great Project that gives you 3pts for each comepleted set. Just tap to toggle the resulting score.</info>
<type>INPUT</type>
<click>TOGGLE</click>
<startingValue>0</startingValue>
<startingToggleState>false</startingToggleState>
<formula>#SCIENCE3PT# = 3*MIN[#GREENA#,#GREENB#,#GREENC#]</formula>
</column>
.
This click action performs the same way as TOGGLE, however only one player can claim this score at a time. If a new player claims this feature all the other players value in this column are zeroed out.
Example, Longest Road card in Catan:
<column name="LROAD">
<title show="true">Longest Road</title>
<type>INPUT</type>
<click>TOGGLE_EXCLUSIVE</click>
<startingToggle>false</startingToggle>
<formula>#LROAD# = 2</formula>
</column>
This click action will run the formulas in <formula> when the column is tapped. For more details on how to create formulas see the <formula> tag entry.
Example 1, scoring Settlements in Catan:
<!-- you essentially only build one or two Settlements at a time, so here the user just taps the column
and the settlement count is automatcally increased by 1. -->
<column name="SETTLEMENTS">
<title show="false">Settlements</title>
<type>INPUT</type>
<click>RUN_FORMULA</click>
<formula>#SETTLEMENTS# = #SETTLEMENTS# + 1</formula>
</column>
Example 2, scoring Cities in Catan:
<! -- in Catan, Cities are made by 'upgrading' Settlements
this formula automatically decreases your Settlement count while increasing your City cout.
also notice the use of <scoring> since Cities are worth two points each. This way the
Cities column reflects the number of tokens on the board, but scores you correctly. -->
<column name="CITIES">
<title show="false">Cities</title>
<type>INPUT</type>
<click>RUN_FORMULA</click>
<formula>#CITIES# = #CITIES# + 1 | #SETTLEMENTS# = #SETTLEMENTS# - 1</formula>
<scoring>#CITIES#*2</scoring>
</column>
This click action brings up a manual score editing dialog. This is a full fledged calculator that users can use and then determine whether their calculations add to the existing score, or replace it with a new one.
This is the default action for long-pressing on a score if <longClick> is not defined.
This click action brings up a scoring dialog that works well with a particular line of train-themed games 😉. No other parameters are required.
This dialog can be <pinned> for easy bulk-scoring.
.
(optional)
If the user LONG clicks on this column (i.e. presses and holds for 2 seconds) this tag defines what action the program will perform.
Example:
Here the user can tap for a quick +1, but long press to open a big scoring grid. Note that it is no longer possible to manually adjust this score since both interactions (click and longclick) have been assigned to an action.
<!-- in this example, long pressing will open a big scoring grid. -->
<column name="VEGGIES">
<info>Tap to add a vegetable. Long press to add many more </info>
<type>INPUT</type>
<click>RUN_FORMULA</click>
<formula>#VEGGIES# = #VEGGIES# + 1</formula>
<longClick>OPEN_SCORE_GRID</longClick>
<values>1,2,3,4,5,6,7,8,9</values>
</column>
.
(required for OPEN_SCORE_GRID, and OPEN_MULTIPLIER_GRID )
This tag holds data used by other functions in your template.
This example opens a Scoring Grid for user to select any of the scores listed in <values>
<column name="COINS">
<title show="false">Coins</title>
<type>INPUT</type>
<click>OPEN_SCORE_GRID</click>
<values>1,2,3,4,5,6,7,8,9,10,-1,-2,-3,-4,-5,-6,-7,-8,-9,-10</values>
</column>
In this example (CHICKENS), a dialog opens allowing the user to multiply a number between (1-12) by another number between (1-9). The starting values are 2 and 5 respectively.
<column name="CHICKENS">
<title show="true">Chickens</title>
<type>INPUT</type>
<click>OPEN_MULTIPLIER_GRID</click>
<values>12,9,2,5</values>
</column>
.
(optional)
This tag lets you override the default rows and columns configuration in a Scoring Grid by specifying the number of columns to use.
Example:
An example of forcing the scoring grid to a particular width. In this example, the default organization of ten objects would be 4x3 (with a couple blanks)
<gridWidth> not set :
but here we set the gridwidth 5 so the scores are organized 5x2 for a more pleasing result
<column name="NAVAL">
<title show="false">Naval Conflicts</title>
<info>An example of forcing the scoring grid to a particular width. In this example, the default organization of ten objects would be 4x3 (with a couple blanks) but here we set the gridwidth 5 so the scores are organized 5x2</info>
<type>INPUT</type>
<click>OPEN_SCORE_GRID</click>
<values>9,7,5,3,1,-1,-2,-3,-4,-5</values>
<gridWidth>5</gridWidth>
</column>
<gridWidth> set :
.
(optional)
If a Score Grid is 'pinned' the user can enter as many values as they want, and the total is added to their score when they press ok.
If a Score Grid is not 'pinned', the dialog will close as soon as they touch a number.
The user can manually pin/unpin a dialog by pressing the yellow-pin icon at the top left:
<column name="BONUS_TILES">
<type>INPUT</type>
<click>OPEN_SCORE_GRID</click>
<values>2,3,4</values>
<pinned>true</pinned>
</column>
.
(optional)
This tag specifies if the values chosen in a scoring dialog such as OPEN_SCORE_GRID or OPEN_MULTIPLIER_GRID are either added to the column score, or they replace the column score.
If TRUE, the value chosen from the scoring dialog replaces the current column score.
If FALSE, the value chose from the scoring dialog is added to the current column score. (this is the default)
Example from a round of Wizard-The Card Game:
<column name="BID">
<title show = "true">Bids</title>
<info>Enter here how many tricks you think you are going to win this round</info>
<type>INPUT</type>
<click>OPEN_SCORE_GRID</click>
<replaceScore>true</replaceScore>
<values>0,1,2,3,4,5,6,7,8,9,10,11</values>
<scoring>0</scoring>
</column>
<column name="RESULT">
<title show = "true">Result</title>
<info>Enter here how many tricks you actually won this round</info>
<type>INPUT</type>
<click>OPEN_SCORE_GRID</click>
<replaceScore>true</replaceScore>
<values>0,1,2,3,4,5,6,7,8,9,10,11</values>
<scoring>0</scoring>
</column>
.
(optional, but you really should do it)
This tag specifies what text will be added to the Move History dialog when that particular action/score occurs. Scoring and Multiplier Grids will also send the resulting score.
Example:
<column name="MONASTARIES">
<title show="true">Monastaries</title>
<type>INPUT</type>
<click>OPEN_SCORE_GRID</click>
<values>1,2,3,4,5,6,7,8,9</values>
<historyText>Completed a Monastary</historyText>
</column>
.
(required for AUTO_FORMULA, RUN_FORMULA, TOGGLE, TOGGLE_EXCLUSIVE)
This tag specifies the formula or formulae that are to be executed when AUTO_FORMULA, RUN_FORMULA, TOGGLE, TOGGLE_EXCLUSIVE are defined.
Formulas are evaluated in the following order, amnd are calculated from left to right:
The following formula function s are supported. More details and examples follow:
function | description |
---|---|
#COLUMN_NAME# | Putting number-signs on both sides of a Column Tag Name Returns the current value of that scoring column (for that player). |
+ - * / ( ) | You can use basic math operators with numbers or values of the current or other columns |
@ROUND@ | A special variable that returns the current round number. (v2.10) |
@PLAYERS@ | A special variable that returns the number of players. (v2.10) |
LOOKUP[ ] | This function returns a value from the numbers listed in <values>based on the position specified. |
MOST[ ] | Returns scores if the player has the most, second-most, etc. of a certain column. Options for how to deal with ties. |
MOSTORZERO[ ] | Same as MOST[], but having zero also counts. |
LEAST[ ] | Returns scores if the player has the least, second-least, etc. of a certain column. Options for how to deal with ties. |
LEASTORZERO[ ] | Determines what player(s) have the least OR NONE of something |
ROUNDDOWN[ ] | Rounds a fraction down |
MIN[...] | Returns the lowest value of a list of COLUMN_NAMES |
MAX[...] | Returns the highest value of a list of COLUMN_NAMES |
IF[...] | An IF statement that has a condition that if true returns a certain value, if false it returns another |
Basic examples :
<column name="SCIENCE_CARD_A">
<info>Tap to increase how many of these cards you have. </info>
<type>INPUT</type>
<click>RUN_FORMULA</click>
<formula>#SCIENCE_CARD_A# = #SCIENCE_CARD_A# + 1</formula>
<scoring>0</scoring>
</column>
Example with two formulae:
In Catan you 'upgrade' a Settlement to a City. So we can automatically reduce our Settlement count when we add a City.
<column name="CITIES">
<title show="false">Cities</title>
<type>INPUT</type>
<click>RUN_FORMULA</click>
<formula>#CITIES# = #CITIES# + 1 | #SETTLEMENTS# = #SETTLEMENTS# - 1</formula>
<scoring>#CITIES#*2</scoring>
</column>
You can use basic math operators with numbers, or values of any column. Standard order-of-operation rules apply. Straight division will round down below .5 and round up at .5 and above.
examples:
<formula> #GOLD# = #GOLD# + 1 </formula>
<formula> #BATTLESCORE# = (#ARMY# * 2) - (#DEAD#) </formula>
<formula> #LONGEST_ROAD# = 2 </formula>
NOTE: xml does not play well with some symbols, so they need to be replaced with the following:
operation | replace with | example |
---|---|---|
> | > | <formula>#MILK# = IF[#COWS# > #FARMERS#, #FARMERS# * 10, 0] </formula> |
< | < | <formula>#LEFTOVERBONUS# = IF[#GOLDSPENT# < #GOLD#, 10, 0] </formula> |
Many games score over multiple rounds, and some have scoring based on what round you are on. This variable returns the current round number.
examples:
<formula> #SCORE# = @ROUND@ * 10 </formula>
// Skull King scores 10 points times the number of the current round if you bid zero, so combining with an IF statement looks like:
<formula> #ZEROBIDPOINTS# = IF[ #BID# = 0,@ROUND@ * 10, 0] </formula>
This function returns the n-th value from a list of parameters based on the value of this or another column. This is useful for non-linear scoring in some games, or scoring when only a certain situation occurs.
For example, if #BONUSTOKENS# for the current player is equal to 3 then the LOOKUP function would return "5" from the list of 0,1,3,5,8,10 (remember, the first number is the zero-th value). And we would write it like:
<scoring>LOOKUP[#BONUSTOKENS#,0,1,3,5,8,10]</scoring>
In the an example from Agricola, your score is based on how much grain you have and there is a chart you have to refer to to get your score.
<scoring>LOOKUP[#GRAIN#,-1,1,1,1,2,2,3,3,4]</scoring>
At the start of the game you have none (#GRAIN# = 0) so your score is -1pts. When you have 4 grain your score is 2pts, and when you have 8 or more grain your score is 4pts. To put this into a table it would look like:
GRAIN | POINTS |
---|---|
0 | -1 |
1 | 1 |
2 | 1 |
3 | 1 |
4 | 2 |
5 | 2 |
6 | 3 |
7 | 3 |
8 | 4 |
In the second example from Tiny Epic Galaxies, the value of EMPIRE_POINTS is determined based on the value of another column (EMPIRE_LEVEL). In this game, EMPIRE_LEVEL starts at 1 (earning 0pts) , but in the list of values we still need to define a value for EMPIRE_LEVEL 0 (also 0pts) . Once EMPIRELEVEL = 2 the player will score 1pt .
<formula>#EMPIRE_POINTS# = LOOKUP[#EMPIRE_LEVEL#,0,0,1,2,3,5,8]</formula>
to put this into a table it would look like:
EMPIRE_LEVEL | EMPIRE_POINTS |
---|---|
0 | 0 |
1 | 0 |
2 | 1 |
3 | 2 |
4 | 3 |
5 | 5 |
6 | 8 |
and here is a tricky one from Cat Lady. If you only have 1 Catnip card you lose 2 points, but otherwise your score is the number of Catnip cards multiplied by the number of another set of cards (FEDCATS). I broke this up into two LOOKUPs: the first only returns a value when #CATNIP# is equal to one (it returns -2). The second lookup only determines the scores for higher counts of catnip cards. (this is now easier with IF statements, but this is a good example of how much you can do with the lookup)
<formula>#CATNIPSCORE# = (LOOKUP[#CATNIP#,0,-2,0,0,0]) + (LOOKUP[#CATNIP#,0,0,1,1,2] * #FEDCATS# ) </formula>
If you have 0 catnip cards the formula would be CATNIPSCORE = 0 + (0 * #FEDCATS#)
If you have 1 catnip cards the formula would be CATNIPSCORE = -2 + (0 * #FEDCATS#)
If you have 2 catnip cards the formula would be CATNIPSCORE = 0 + (1 * #FEDCATS#)
If you have 3 catnip cards the formula would be CATNIPSCORE = 0 + (1 * #FEDCATS#)
If you have 4 or more catnip cards the formula would be CATNIPSCORE = 0 + (2 * #FEDCATS#)
Returns a score if the player has the most, second most... (etc) of a certain column. If no player has any score (eg. all zero) then no points are awarded for having the most.
First parameter is the COLUMN_NAME we are measuring. Note! there are no ##'s before and after the TAG because we want the name, not the value.
Second parameter is what to do if there is a tie.
The third parameter, and any after that, are the resulting scores for MOST (and 2nd most, and third ...)
Examples:
in the first example, the player with the most in GOODSA will get 10pts, second 7pts, third 5pts. If two players tie for first, they both get 10pts and the player that is third will get 5pts.
#GOODSSCORE# = MOST[GOODSA,ALL,10,7,5]
In the second example, if two players tie for first they each get 5pts, and the player that is third gets 5pts. If two players tie for second-most, the first player will get 10pts, and the second and third player will get 3pts each.
in both examples, any player that has 0 GOODSA points are not included in the MOST awards
#GOODSSCORE# = MOST[GOODSA,SPLIT,10,7,5]
The next example uses the LOWER parameter. If two players tie for the most, they will both get the points for second-most (which is 7pts) and the next player will get 5. If two players tie for the second and thrid most, they will each get the points for the third most which is 5pts. (Board Game Buddy needs to be at least version 2.28 to use the LOWER parameter)
#GOODSSCORE# = MOST[GOODSA,LOWER,10,7,5]
Same as the MOST function, but having zero also counts. This is handy when combining rules with most and least at the same time.
Example:
This example from Sushi Go! gives 6 points for the most pudding, and -6 points for the least. We used MOSTORZERO so that at the start of the game the "mosts" and "leasts" cancel each other out and players start with 0 points until at least one pudding is scored. (that one hurt my head a bit)
#PUDDINGSCORE# = MOSTORZERO[PUDDINGCOUNT,SPLIT,6] + LEASTORZERO[PUDDINGCOUNT,SPLIT,-6]
similar to the MOST function, with the same parameters. Note that a player with 0 is not counted in the LEAST calculation (for that use LEASTORZERO)
#GOODSSCORE# = LEAST[GOODSA,SPLIT,-4,-2,-1]
Determines what player(s) had the least OR NONE of something and awards points/penalties accordingly. Same as LEAST function but includes a score of 0 in the comparison.
#GOODSSCORE# = LEASTORZERO[GOODSA,SPLIT,-4,-2,-1]
Rounds a fractional number down.
In this example from 7 Wonders, players get a VP for every 3 coins they have at the end of the game. So here we divide their #COINS# by 3, and then round that down.
#COINSCORE# = ROUNDDOWN[#COINS#/3]
Rounds a fractional number up.
In this example from players get a VP for every 3 coins they have at the end of the game - rounded up. So here we divide their #COINS# by 3, and then round that up.
#COINSCORE# = ROUNDUP[#COINS#/3]
The MIN function will return the lowest value of a list of COLUMN_NAMES.
In this example from an expansion to 7 Wonders, the player gets 3 points for each complete set of the three different science tokens. Do do this we just get the lowest number of the three types (GREENA, GREENB, GREENC) and multiply by three. (clever, eh?)
If #GREENA# = 4, #GREENA# = 2, and #GREENA# = 3, the MIN function would return a value of 2.
#SCIENCE3PT# = 3*MIN[#GREENA#,#GREENB#,#GREENC#]
The MAX function will return the highest value of a list of COLUMN_NAMES.
In this example, we just want to know the highest JUMP.
If #TRY_1# = 10, #TRY_2# = 12, and #TRY_3# = 7, the MAX function would return a value of 12.
#HIGHEST_JUMP# = MAX[#TRY_1#,#TRY_2#,#TRY_3#]
The SUM function will return the sum total of all players scores for the specified column
First parameter is the COLUMN_NAME we are adding up. Note! there are no ##'s before and after the TAG because we want the name, not the value.
Examples:
In the first example we simply add up the total of all players settlements.
<column name="SUMCOL">
<title show="true">Sum of Settlements</title>
<type>AUTO_FORMULA</type>
<formula>#SUMCOL# = SUM[SETTLEMENTS]</formula>
<scoring>0</scoring> <!-- we are just SUMMING for other comparisons. It would be silly if everybody got the same score -->
</column>
In this example, we use SUM in a formula to determine the sum of all OTHER players settlements..
<column name="SUMOTHERS">
<title show="true">Sum of Others</title>
<type>AUTO_FORMULA</type>
<formula>#SUMOTHERS# = SUM[SETTLEMENTS] - #SETTLEMENTS#</formula>
</column>
The IF statement allows you to apply different scoring depending on a certain condition, like if two numbers are equal or not. There are three parameters that you have to supply to the IF statement:
parameter | description |
---|---|
condition | This is a standard mathematical comparison like '=' or '>'. You can use column names (eg #BID# and all of the above functions within the IF statement. Valid operators are equal (=), not equal (!=), greater than (>), less than (<), greater or equal to (>=), and less than or equal to (<=) |
score if TRUE | if the above condition is TRUE , then this is the value that will be given by the IF statement |
score if FALSE | if the above condition is FALSE, then this is the value that will be given by the IF statement |
Example:
In Skull King you score 20 points for each trick you won, but only if you guessed the correct number of tricks before, otherwise you lose 10 points for each trick you are off from your original guess.
<column name="TRICKSCORE">
<title show="false">Trick Taking Score</title>
<type>INPUT</type>
<click>RUN_FORMULA</click>
<formula>#TRICKSCORE# = IF[#GUESS# = #RESULT#, 20 * #GUESS#, -10 * ABS[#GUESS# - #RESULT#] ]</formula>
<scoring>#CITIES#*2</scoring>
</column>
.
(optional)
This tag allows you to specify how this column impacts the players total score. If not specified, the player's total score is augmented by the number displayed.
By default, the number displayed in the column is the value added to a player's total score. However in some cases you want to show the number of objects instead (for easy tracking) and the player gets more than one point per object. Or, you just want to show number of objects for calculation in another column and don't want them to count.
<scoring> understands the same formulas functions as <formula>, with the only difference is that you don't need to write it as an equation (B+C, not A=B+C) because the left side of the equals sign is implied to be this column. Refer to <formula> for more detail on how to write formulas.
Example:
In Catan it is easier for the player to keep track of the Cities they have built (it's the number of city tokens on the board), but each City is worth 2 points. So we specify this in the <scoring> tag :
<column name="CITIES">
<title show="false">Cities</title>
<type>INPUT</type>
<click>RUN_FORMULA</click>
<formula>#CITIES# = #CITIES# + 1 | #SETTLEMENTS# = #SETTLEMENTS# - 1</formula>
<scoring>#CITIES#*2</scoring>
</column>
In Carcassone:Traders and Builders, players get points for whoever has the most of certain "goods". We want to track the number of each "good" each player has, but not add that to the score. So here we have columns to track each "good" quantity, and a column to determine the score:
<column name="WINE_GOODS">
<type>INPUT</type>
<click>RUN_FORMULA</click>
<formula>#WINE_GOODS# = #WINE_GOODS# + 1</formula>
<scoring>0</scoring>
</column>
<column name="GRAIN_GOODS">
<type>INPUT</type>
<click>RUN_FORMULA</click>
<formula>#GRAIN_GOODS# = #GRAIN_GOODS# + 1</formula>
<scoring>0</scoring>
</column>
<column name="CLOTH_GOODS">
<type>INPUT</type>
<click>RUN_FORMULA</click>
<formula>#CLOTH_GOODS# = #CLOTH_GOODS# + 1</formula>
<scoring>0</scoring>
</column>
<column name="GOODSSCORE">
<info>This column automatically calculates final Goods Score based on MOST of each type. 10pts for most, 7pts for second most, 5pts for thrid most. </info>
<type>AUTO_FORMULA</type>
<formula>#GOODSSCORE# = MOST[WINE_GOODS,ALL,10,7,5] + MOST[GRAIN_GOODS,ALL,10,7,5] + MOST[CLOTH_GOODS,ALL,10,7,5]</formula>
</column>
.
(optional)
The need for this tag came from bidding games like Wizard and Skull King. It was confusing that the whole grid of cells was calculating your scores based on your BIDS when you haven't even played the round yet (the RESULT).
By using this tag, you can use a <startingValue> of -1 in a RESULT type of column (eg. how many tricks did you win) to indicate that this is not the final value. By hiding it (ie. showing a blank cell) it makes it less confusing and easier to see who does not have a RESULT tallied.
In this example from Skull King, you can see there are 3 columns: BID, RESULT, and POINTS. The RESULT column will be blank until the user taps it to show how many tricks the player took.
// several <tag lines> have been removed from this example for clarity
<column name="BID">
<title show = "true">Bids</title>
<type>INPUT</type>
<click>RUN_FORMULA</click>
<formula>#BID# = #BID# + 1</formula>
<scoring>0</scoring>
</column>
<column name="RESULT">
<title show = "true">Result</title>
<type>INPUT</type>
<click>RUN_FORMULA</click>
<formula>#RESULT# = #RESULT# + 1</formula>
<scoring>0</scoring>
<startingValue>-1</startingValue>
<hideIfNegative>true</hideIfNegative>
</column>
<column name="TRICKPOINTS">
<title show = "true">Trick Points</title>
<info>Points from this round</info>
<imageName>penalty.png</imageName>
<type>AUTO_FORMULA</type>
<formula>#TRICKPOINTS# = IF[#RESULT# >= 0,IF[#BID# = #RESULT#, 20 * #BID#,-10*ABS[#BID#-#RESULT#]], 0]</formula>
// simpler example:
<formula>#TRICKPOINTS# = IF[#RESULT# >= 0, calculate points, 0 ]</formula>
</column>
.
(optional)
This tag will make a scoring box span across all players, so there is effectively only one scoring box for a particular game item.
A good example is Deep Sea Adventure. All players share the same air supply, so it is reduced communally. When it reaches zero all players not back in the submarine drown (a frequent occurrence LOL).
In this example the AIR column :
<column name="AIR">
<title show = "false">Air Supply</title>
<span>true</span>
<info>Tap to reduce your air supply by 1 unit. Long press to reset to full (25). (this does not add to anyone's score)</info>
<imageName>air.png</imageName>
<type>INPUT</type>
<click>PLUS_MINUS_BUTTONS</click>
<longClick>RUN_FORMULA</longClick>
<formula>#AIR# =25</formula>
<replace>true</replace>
<scoring>0</scoring>
<startingValue>25</startingValue>
</column>
(bottom of document)