Documentation Changes

BGB v2.06

Creating a Smart Game Template for BoardGameBuddy

If there is a board game that you want a Smart Game Template for, but it currently doesn't exist on the BoardGameBuddy server, you can write it yourself!

You then you can even send it to me to put up on the BoardGameBuddy server for everyone to use!

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.

What you need

To create a Smart Game Template for BoardGameBuddy all you need is:

Main components of a Game Template

The Game Templates are kept on the storage area of your device. When you plug your device into your computer and open a File Explorer / Finder window you should see a folder called BoardGameBuddy. The game templates are in there.

Each Game Template gets is own folder containing the Game Template and all the images that you want to use.

game template folder example

Creating a new Game Template

Key things to think about

Download the Game Template "Andy's Fake Game" to your copy of BoardGameBuddy - there are lots of examples of different ways to score in there.

Technical steps:

  1. connect your device to your computer
  2. on your device, go to the BoardGameBuddy \ GameTemplates folder
  3. create new folder for the game (eg. new_game_template). Keep all the files associated with your template here (the XML file, images, fonts etc.)
  4. Copy an existing XML file from another similar game over to changes and modify.
  5. Edit the XML file by adding the columns you want, the game information etc. (see the detailed reference section below) Depending on your computer set-up, you can either edit the file directly off your device, or edit it on your computer and then drag-n-drop it to your device.
  6. test it - when you are on the screen that lets you choose the game template, you just have to press the refesh button on the far left and your template should show up!
  1. send it to me! Done lots of testing and the template is great ? Reach out to me at the BoardGameBuddy Guild on BoardGameGeek and we'll get it on the server !

I hope this helps you get started. If you need more help come to the BoardGameBuddy Guild on BoardGameGeek.com.

Game Template Reference

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>

<GameTemplate>

Everything needs to be inside a GameTemplate tag.

example:

<GameTemplate>
..
..
..
</GameTemplate>

.


<BGBV>

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>

.


<game> - what board game is this?

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:

.


<game>

<name>

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

.


<image>

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

.


<bggID>

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

.


<winScore>

(optional)

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 here

example:

<winScore>10</winScore>

.



<template> - information about the template

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>

.


<name>

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.

Pick Game Template example

example:

<name>Supports all expansions up to Armada</name>

.


<description>

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.

template summary panel

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

.


<background>

(optional)

Use this tag to specify a custom background image when using this template.

example:

<background>wood_background.jpg</background>

.


<divider>

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

Catan Scoring Screen example

example:

<divider>road.png</divider>

.


<author>

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

.


<language>

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

.


<font> or <fontFile>

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>

.



<expansion> - Add an optional game expansion

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:

Expanions example

Descriptions of the sub-tags: .


<name>

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

.


<bggID>

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

.


<background>

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

.


<winScore>

(optional)

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>

.


<useColumns>

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

.


<description>

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>

.



<column name = "COLUMN_NAME"> - Define a scoring column

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

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

.


<title show="true">

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>

Column title examples

.


<info>

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

column info eg 1

column info eg 2

.


<imageName>

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

city_token.png

<column name="CITIES">
    <title show="false">Cities</title>
    <imageName>city_token.png</imageName>
</column>

result:

column imagename example

.


<color>

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

column color

.


<type>

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

.


<startingValue>

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

.


<startingToggleState>

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

.


<min>

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

.


<max>

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

.


<click>

(optional)

If the user clicks on this column, this tag defines what action the program will perform. Options are:

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

OPEN_SCORE_GRID

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:

colum score grid - carcassone

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:

column score grid - 7 wonders

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:

column score grid - TTR

.

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

The multiplier dialog is configured using entries in the <values> tag:

where

The user taps the values they want to use, and the resulting score to be added in shown on the far right. Note that the multiplier values can also be manually edited for very rare/extreme circumstances (so you don't have to make a massive grid with tiny buttons)

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>
</column>

Gives us the following dialog. Notice that the used values can be manually edited.

click_open_multiplier_grid .

another example:

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

Give us the following dialog:

score multiplier grid eg2

TOGGLE

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>

.

TOGGLE_EXCLUSIVE

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>

RUN_FORMULA

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>

column_scoring

OPEN_SCORE_ADJUST

This click action brings up a manual score editing dialog. Users can manually change the score by typing in the value, or using the + and - buttons.

OPEN_SCORE_ADJUST

OPEN_SCORE_TRAIN

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.

score train dialog

.


<longClick>

(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 not possible to manually adjust this score since OPEN_SCORE_ADJUST is now not assigned to any 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>

.


<values>

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

.


<gridWidth>

(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 : colum_gridWidth_no_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 : colum_gridWidth_set

.


<pinned>

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

dialog pin

.


<replaceScore>

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

.


<historyText>

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

move history

.


<formula>

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

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

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>

formula function : Basic Operators

You can use basic math operators with numbers, or values of any column. Standard order-of-operation rules apply.

examples:

<formula> #GOLD# = #GOLD# + 1 </formula>
<formula> #BATTLESCORE# = (#ARMY# * 2)  - (#DEAD#) </formula>
<formula> #LONGEST_ROAD# = 2 </formula>

formula function : LOOKUP

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.

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

formula function : MOST

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 points are not included in the MOST awards

#GOODSSCORE# = MOST[GOODSA,SPLIT,10,7,5]

formula function : MOSTORZERO

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]

formula function : LEAST

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]

formula function : LEASTORZERO

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]

formula function : ROUNDDOWN

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]

formula function : MIN

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#]

formula function : MAX

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#]

.


<scoring>

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