Field Description

Rationale for challenge description file

Every year there is a new Challenge, containing a new playing field and new missions. Including each new challenge description in the code would create a need for yearly updates, by people familiar with the code. By keeping it as a separate data file anybody can assist in creating new mission descriptions. It even allows the use of these tools for a tournament with a challenge you designed yourself.

Overview

The information in the description is used for three main purposes:

• Letting the system calculate scores
• Translating the scoring form to other natural languages; it is not desirable to only have an English version available
• Generating a scoring form (either on paper or electronically) with which to input scores

The scoring form is used by referees to record the state of the field at the end of a match. This state is divided into multiple missions. Each missions contains one or more objectives (and one or more scoring rules, which are not part of the state). The distinction between objectives and scoring rules is made because the calculation of how many points a mission is worth can, in some cases, be quite a complex process, for which referees do not always have time.

An objective is a question about what the field looks like and a corresponding set of possible answers. The scoring rules use the chosen answers to determine how many points are awarded for that mission. If an electronic version of the scoring form is used, it can immediately show the score awarded for each of the missions. When a paper version is used, the mission scores will need to be calculated later (a tool to make this easier is also available).

The remainder of this document describes the file format in detail. It is mainly aimed at people who want to use the file and have to be able to read it. However, some important notes to people who want to create such a file are included as well. One general guideline when writing a challenge description is to always copy the contents for attributes called "descriptions" verbatim from the official scoring form provided by FIRST. This is a vital because tiny changes in wording can cause dramatic changes in meaning and we have to score all events equally.

Example

As an example of a complete challenge file, here is the description for the "Senior Solutions" challenge from 2012. All examples in this documentation are from that challenge file. The file as a whole can also be referred to if any part of this explanation is not sufficiently clear; the 2012 challenge contains examples of everything the file format can do.

Specification of challenge description file

The challenge description is provided to the system as an XML file. The first two lines are always the following boilerplate code, just copy this verbatim:

<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type="text/xsl" href="../xsl/challenge.xsl"?>

Then we have the top-level fll:challenge element; on the one hand it contains a reference to the schema definition (more boilerplate), but it also has year, version and name attributes, to tell which Challenge this files describes. The year is simply a four-digit number, signifying in which calender year the current challenge was released. In other words, for the 2012-2013 season, the year attribute is set to 2012. During the season there can be small updates to the description of the missions, or clarifications to the scoring rules. The version number of the file (an integer; a higher number means a newer revision) allows for updating the challenge description file and easily tell the newest file apart from older versions. There is also a name attribute which contains the actual name of the Challenge. This is a human-readable string, only used for display to users.

<fll:challenge xmlns:fll="http://fll-tools.com/applications/scoring/v1/challenge.xsd" year="2012" version="1" name="Senior Solutions">

Strings element

In order to make the description easier to translate, all text which is shown to users has been collected in one place, at the top of the file. These messages are grouped in strings elements. Each strings element has a language attribute, containing the ISO 639-1 code of the natural language its strings are written in. Each file needs at least one strings element, but in regions which use multiple languages it is possible to include as many as desired. Note that each strings element needs to include a full translation; every string has to be defined.

Strings element

Within a strings element is a number of string elements, one for each piece of text used. Each string element has an id, which is used to reference it. When translating, it is important to not change the id value at all; only the text which comes behind it should be translated. Most texts can simply be entered, but (due to limitations of the XML file format) there are a few cases which require special attention. Any text which contains a line break or uses smaller-than or larger-than sign needs to have a the special marker "" behind it.

<strings language="en-US">
    <string id="medicine-name">Medicine</string>
    <string id="medicine-desc"><![CDATA[The bottles are arranged randomly before the start of each match (See Field Setup).
    Robot gets the green medicine bottle to Base without disturbing orange ones.]]></string>
</strings>

The sample above shows two strings, the one which can be referenced with the identifier "medicine-name" (the name for the Medicine mission) displays to users as "Medicine". The next string is the description of that mission, which is referenced as "medicine-desc" and shown as:

The bottles are arranged randomly before the start of each match (See Field Setup).
Robot gets the green medicine bottle to Base without disturbing orange ones.

If we had omitted the special tags, the line break would have been lost.

Apart from translations for mission names and such, two additional string ids need to be defined: "yes" and "no". These are used for objectives which have either been accomplished or not.

For translators, this is all they need to know. If you want to create your own challenge or write a tool which can work with challenge descriptions, read on.

End-of-translation marker

While not technically a part of the file format, we recommend including the following line between the strings element and the remainder of the file:

    <!-- Do NOT edit below this line -->

This in order to make sure translators do not accidentally change anything about the logic of the file.

Mission element

Each mission has an attribute name for display to the referee and team members. It is shown on both the paper and electronic version of the scoring sheet and makes for easy reference. There is also a description attribute, which can describe the mission in some detail. However, in the case of paper scoring sheets, it is unlikely for there to be enough room to include this description. Even on the electronic version it will be hidden by default, only being shown when the user asks for it. For this reason, please do not include any crucial information in here.

Because we wanted to collect all strings in a single location, to ease the work of translators, the name and description attributes do not actually contain the string to display. Instead, they contain the id of a string in the strings section.

Below is a mission definition, for easy reference, which demonstrates many (but not all) capabilities of the format. It will be used as running example.

<mission name="woodwork-name" description="woodwork-desc">
    <objective-yesno id="chairbase"  description="chairbase-desc"  default="no" />
    <objective-yesno id="chairtable" description="chairtable-desc" default="no" />
    <score>
        <indexes>
            <index objective="chairbase" /><index objective="chairtable" />
        </indexes>
        <cases>
            <case> <index-ref value="no"  /> <index-ref value="no"  /> <points amount="0"  /> </case>
            <case> <index-ref value="no"  /> <index-ref value="yes" /> <points amount="25" /> </case>
            <case> <index-ref value="yes" /> <index-ref value="no"  /> <points amount="15" /> </case>
            <case> <index-ref value="yes" /> <index-ref value="yes" /> <error message="chairposition-error" /> </case>
        </cases>
    </score>
</mission>

Objective element

Within each mission we first have to define one or more objectives. There are currently three types: objective-yesno, objective-number and objective-enum. Each of these has an id and a description. The id is used to refer to this objective in other parts of the file, but is not visible to users. It is required to be unique (no other objective in this challenge can have the same id) and recommended to be short yet descriptive. The textual description holds, just like in the case of the mission itself, the id of a string in the strings section.

All types of objectives can hold an optional default attribute. If present, it gives the value the objective has after field setup, but before the match starts. On paper scoring forms this information is unused, but on the electronic version it can be used to automatically fill out the form to the starting position (some referees like this, some prefer filling out the entire form each time, to guard against error).

While the above is true for all three types of objectives, there are also some differences:

• When objective-yesno is used, no further attributes or child elements are used; the scoring form shows two options: the strings with ids "yes" and "no".
• When objective-number is used, two more attributes, "min" and "max" are used to define the range of answers (note the range is inclusive of the min and max values).
• When objective-enum (short for "enumeration") is used, the possible values are listed by two or more child elements of type "option". Each of these contains an name and a description attribute. An example can be found in the 2012 challenge, in the "Ball Game" mission.

Both the objective-yesno type and the objective-number type are effectively shorthand for enumerations; they exist because they are very common (almost all objectives are of this type; very few explicit enumerations are used) and would take much more work to write out in full enum notation.

Score element

Next come a number of score elements. Most missions will only have a single such element, but it is allowed to have multiple; in this case, each is treated completely separately from the other(s) and the points from each are simply added together.

Each score element begins with an indexes element, containing one or more index elements. This provides a list of the objectives this score considers. The index elements have one attribute, objective, which contains the name of an objective (its id). For a mission with just a single objective this might seem a little strange, but it is very important for missions containing multiple objectives.

After the indexes we have the cases element, which contains a (potentially large) number of case elements. Each of these describes the result of one way of choosing a value for each of the objectives.

Specifying the values of the objectives is done by a number of index-ref elements, one for each of the index elements in the indexes element. An index-ref has a value attribute, giving a possible value of the objective it references. Note the index-ref elements need to be in the same order as the index elements. For the three types of objective, these values are possible:

• An objective-yesno can have a value of either "yes" or "no".
• An objective-number objective can be any of the numbers in its range. For instance when min="0" and max="2" are chosen, the possible values are "0", "1" and "2".
• An objective-enum objective can be any of the values defined by its child elements.

For various reasons, such as automatically checking the challenge description for errors, we require each combination of values of the relevant objectives is described by a case element. If a combination cannot happen, it must still be listed, but with an error message explaining why it is impossible. For the other cases a score is given, specifying a positive, negative or zero number of points awarded.

Scores are awarded using a points element, with the number of points awarded in an amount attribute. When a combination is impossible, an error element is used instead, with the id of a string in its message attribute.

In the 2014 season a new scoring mechanic was introduced: a bonus percentage elements. We support this through percentage elements. Like points elements these have one attribute, amount, which means the percentage bonus. We currently implement this in the following way:

• At most one mission is allowed to contain percentage elements.
• The percentage bonus is calculated over the total score of all other missions. Note this means any points awarded in the same mission will not receive the bonus.
• The bonus is calculated over both actual score points, as well as penalty points.
• Calculating the percentage is unfortunately not guaranteed to result in an integer. We resolve this by rounding up: a 10 percent bonus over a score of 20 points would result in 0.2 bonus points, which is rounded up to 1, resulting in a total score of 21 points.

Various notes

In various places in this file we use numbers. All of these are required to be integers; we have for instance no support for awarding something-and-a-half points for a mission.