Score Module Docs

From Ryan's Docs

Contents 1 Score Module Docs 1.1 Links 1.2 Example PLIST Files 1.3 PLIST File Structure 1.3.1 ui Array 1.3.1.1 label 1.3.1.2 seg 1.3.1.3 segVar 1.3.1.4 textbox 1.3.1.5 textboxVar 1.3.2 info Dictionary 1.3.3 calcs Array 1.3.3.1 type=multiplyAdd 1.3.3.2 type=divideAdd 1.3.3.3 type=bracket 1.3.3.4 other keys

[edit] Score Module Docs

Use these docs to create your own scoring modules for Score. The modules are used to create UI elements and scoring logic for board games. Note the scoring modules are only available in [Score] 1.3. (which is out now)

The files are stored in plist files. Plist files are generic settings files that are used commonly on Macs. The files are xml files that contain different data structures, like Strings, Numbers, Booleans, Lists, and Dictionaries.

I recommend you edit the plist on Mac OSX using the plist editor, or find a plist tool on the pc. Also, I believe you can use MS Office 2007 to edit the plist. The plist files are xml files so technically you could edit in any text editor.

When you have your module ready, please email it to ryanch at gmail dot com to have it listed with the rest of the modules.

[edit] Links

• BoardGameGeek Forum for Score
• Known modules for Score

[edit] Example PLIST Files

• Simple example, Agricola: agricola.plist
• Complex example, Puerto Rico: puertorico.plist

[edit] PLIST File Structure

• Root Type: Dictionary
  • key: ui type: Array - This contains the ui elements that will be displayed.
  • key: info type: Dictionary - This contains information about this module.
  • key: calcs type: Array - This contains a list of calculations that need to be done to build the score.

[edit] ui Array

The ui array contains all of the ui elements in your module. Each ui element is defined as a Dictionary. Common fields in UI elements

• title - this is what is shown as a label next to a control.
• type - this is the type of control to be shown.
• color - this is text color to be shown for the label text.

Note: Provide color as a string in the format: "255,255,255,255". The numbers are Red,Green,Blue,Alpha. For the most part, Alpha will always be 255. If you don't provide a color, white will be used. Here color picker that provides colors in this format: colorschemer

Types of UI elements

For each of the ui element types you need to pick a type the type will tell Score what type of user interface element to show the user.

Here are the types of user interface elements you can create, these are the possible values of the "type" attribute for each ui element:

[edit] label

Here is some example xml for a label:

<dict>
 <key>title</key>
 <string>Production Buildings</string>
 <key>type</key>
 <string>label</string>
 <key>color</key>
 <string>0,61,245,255</string>
</dict>

[edit] seg

This is a segmented control. Where the user has a limited number of choices. This control has 2 additional values.

• values (array) - These strings are used to set the values displayed in the control
• points (array) - These are the numbers that will be awarded if that segment is active

The points array must contain numbers. The values and points arrays must contain the same amount of elements.

Sample xml:

<dict>
 <key>title</key>
 <string>Fields</string>
 <key>type</key>
 <string>seg</string>
 <key>values</key>
 <array>
  <string>0-1</string>
  <string>2</string>
  <string>3</string>
  <string>4</string>
  <string>5+</string>
 </array>
 <key>points</key>
 <array>
  <integer>-1</integer>
  <string>1</string>
  <string>2</string>
  <string>3</string>
  <string>4</string>
 </array>
</dict>

[edit] segVar

This is a segmented control which drives a variable to be used for calculation.

• varname (string) - This is the name of the variable that the points will be stored in.
• values (array) - These strings are used to set the values displayed in the control.
• points (array) - These are the numbers that will be assigned to the variable if that segment is active.
• cpoints (array) - This is optional. These points will be awarded to the player if this segment is active.

The points and cpoints array must contain numbers. The values, points and cpoints arrays must contain the same amount of elements.

Sample xml:

<dict>
 <key>tint</key>
 <string>102,51,0,255</string>
 <key>title</key>
 <string>coffee roaster</string>
 <key>type</key>
 <string>segVar</string>
 <key>varname</key>
 <string>coffee roaster</string>
 <key>values</key>
 <array>
  <string>no</string>
  <string>yes</string>
 </array>
 <key>points</key>
  <array>
   <integer>0</integer>
   <string>1</string>
  </array>
 <key>cpoints</key>
 <array>
  <integer>0</integer>
  <string>3</string>
 </array>
</dict>

[edit] textbox

This is a text box control. The value entered will be added to the players points.

Sample xml:

<dict>
 <key>title</key>
 <string>Production Buildings</string>
 <key>type</key>
 <string>textbox</string>
 <key>color</key>
 <string>0,61,245,255</string>
</dict>

[edit] textboxVar

This is a text box control. The value entered will be assigned to a variable to be used for calculations later.

• varname (string) - This is the name of the variable that the points will be stored in.
• addAlso (boolean) - This is optional. The default is NO. If YES, then the value entered will also be added to the current players score.

Sample xml:

<dict>
 <key>title</key>
 <string>Production Buildings</string>
 <key>type</key>
 <string>textboxVar</string>
 <key>color</key>
 <string>0,61,245,255</string>
 <key>varname</key>
 <string>buildings</string>
</dict>

[edit] info Dictionary

This dictonary contains the information about the module.

• name (string) - The name of the module.
• version (string) - This is the version of this module.
• author (string) - This is who made this module.
• downloadURL (string) - This should point at where your modules is currently being hosted. By adding this feature it adds a download button to the module UI so that you can quickly reload your module. Note, this attribute should only be used for development.

[edit] calcs Array

This contains a list of calculations that need to be done to build the score, in addition to the seg and textbox controls. For example in Agricola, the number of rooms it multiplied by the type of house. rooms * roomType.. where roomType is 0, 1 or 2.

Each item in the calcs array is a Dictionary. Like ui elements each has a type.

[edit] type=multiplyAdd

This takes the value of var1 and var2 , multiplys them and adds them to points. Example:

totalPoints = (var1 * var2) + totalPoints;

with fixed:

totalPoints = (var1 * fixed) + totalPoints;

[edit] type=divideAdd

This takes the value of var1 and var2 , divides them and adds them to points. Example:

totalPoints = (var1 / var2) + totalPoints;

with fixed:

totalPoints = (var1 / fixed) + totalPoints;

Note by default it will round down. If you want to round up, add a roundDown key/value with the value "NO".

[edit] type=bracket

This allows for a points to be awarded based on a bracket of values. For example 5 points for 0-6, 6 points for 7-8, 7 points for 9-10. To use this you need to provide var1, a values array, and a points array. var1 will act as number used to test in the ranges. values will contain a list of strings that define the ranges. points will contain the points that are awarded for each range.

[edit] other keys

• values (comma delimited string) - This is optional, used for bracket. This is a list of strings like "5-23" where 5 is the value that is tested on the low end, and 23 is the number that is tested on the high end. For example:

if ( var1 >= 5 && var1 <= 23 )

An example value is:

0-9,10-10,11-11,12-15

• points (comma delimited string, list of numbers) - This is optional, used for bracket. This is a list of numbers that are awarded if a value is found in a range. The number of numbers in this array must match the number that are in the values array.

• roundDown (string) - This is optional, used for divideAdd. If it is YES or not provided, then left over numbers after the division will be dropped. If this is NO, then if there are any values left over after division, then 1 point extra will be added.

• outVarname (string) - If you set an outVarname for a calculation, the output of the calculation will not be added to the final score, instead the calculation value will be set on the outVarname. Then other calculations can use the named variable and get the value the calculation had. Note, calculations are done in order. So if you want to use a outVarname, put the

calculations that use it AFTER the outVarname.

• var1 (string) - This is the name of a variable to use for the value of var1. Note, if you want, you can use a list of var names. For example:

var1=bigBoat,smallBoat,fish

If you provide multiple values, they will all be resolved, and added together to create the value of var1. For example, if bigBoat=1 and smallBoat=2 and fish=1, then var1 would be 4.

Note: You can use a special variable name _CURRENT_TOTAL_ to get the current total point total. Note that this current value will be value calculated currently when this calculation is evaluated. The order of evaluation is all ui controls, then all calcs in the order defined.

• var2 (string) - This is the name of a variable to use for the value of var2. This is optional, but if you skip this variable, you MUST include a fixed key. The rules for values of var2 are the same as var1.

• fixed (number) - This is a fixed value for a variable. This is used in place of var2.

• controlVar (string) This is the name of a variable to check. The value of that variable is greater than or equal to 1, then this calculation is active. If it is less than 1, then the calculation is not active. Note, this is an optional key, if you do not provide a controlVar then the calculation is always active. Just like var1 and var2, you can use a list of var names.