CHECKLIST DEFINITIONS

The <checklist_filename>.xml file goes in the Checklist folder beside the other aircraft folders and should be formatted as follows:

<?xml version="1.0" encoding="UTF-8"?>
<SimBase.Document Type="Checklist" version="1,0">
    <Checklist.Checklist>
        <!-- LIBRARY INCLUDES HERE -->
        <Step ChecklistStepId="<ID>">
            <Page SubjectTT="<PAGE_TITLE>">
                <!-- CHECKPOINTS OR BLOCKS HERE -->
            </Page>
        </Step>
        <!-- FURTHER STEPS HERE -->
    </Checklist.Checklist>
</SimBase.Document>

Here you must include the <SimBase.Document> element (where the type attribute should be "Checklist"), as well as the <Checklist.Checklist> element, which acts as a container for the checklist itself. The rest of the XML is comprised of the elements listed on this page.

 

If you are creating a checkpoint library to be shared then this would also go in the same Checklist folder as the checklist and be named <library_filename>.xml. It would then have the following formatting:

<?xml version="1.0" encoding="UTF-8"?>
<SimBase.Document Type="CheckpointLibrary" version="1,0">
    <Checklist.CheckpointLibrary>
        <!-- CHECKPOINTS HERE -->
    </Checklist.CheckpointLibrary>
</SimBase.Document>

As with checklists, you must include the <SimBase.Document> element (where the type attribute should now be "CheckpointLibrary"), as well as the <Checklist.CheckpointLibrary> element, which acts as a container for the checkpoints themselves. The rest of the XML is comprised of the elements listed on this page.

 

You can find examples of the layout for the checklist and checkpoint library XML here:

 

You can find a tutorial that explains all the component parts of a checklist in great detail and that also goes through how to create them from the following links:

 

 

<Checklist.Checklist>

This element is a container element for all the checklist details. This element can contain <IncludeCheckpointLibrary /> and <Step> elements, and has the following attribute:

 

Attribute Description Type Required
Type Type of the xml file, in this case "Checklist" String Yes

 

 

<Checklist.CheckpointLibrary>

This element is a container element for all the checkpoints in a shared checklist library. This element can contain the <Checkpoint> sub-element, and has no attributes.

 

 

<IncludeCheckpointLibrary />

This sub-element can be added to a <Checklist.Checklist> to point the checklist to a relevant shared checkpoint library. This is a self-closing element that takes one attribute:

 

Attribute Description Type Required
FileName Path to an *.xml file for a checkpoint library. String Yes

 

Note that you can also link here to a default Checkpoint library that is part of the simulation instalation. For more information please see here: XML files

 

 

<Step>

This sub-element can be added to a <Checklist.Checklist> and acts as a container element used to group one or several pages by logical steps. The element can contain <Page> sub-elements, and takes one attribute:

 

Attribute Description Type Required
ChecklistStepId A key used to reference the step by a mission. Must be one of the given enum strings.

Enum:

  1. "PREFLIGHT_GATE"
  2. "PREFLIGHT_PUSHBACK"
  3. "PREFLIGHT_TAXI_OUT"
  4. "FLIGHT_RUNWAY"
  5. "FLIGHT_TAKEOFF"
  6. "FLIGHT_CRUISE"
  7. "FLIGHT_DESCENT"
  8. "LANDING_APPROACH"
  9. "LANDING_APPROACH_VFR"
  10. "LANDING_APPROACH_IFR"
  11. "LANDING_TOUCHDOWN"
  12. "LANDING_GROUNDROLL"
  13. "LANDING_TAXI_IN"
  14. "LANDING_GATE"
Yes

 

 

<Page>

This sub-element is added to the <Step> element as a container to hold a list of checkpoints, which will be displayed in the Microsoft Flight Simulator UI with a title. It is basically used to group one or several checkpoints in a single page of the checklist. The element can contain <Checkpoint> and <Block> sub-elements and has the following attribute:

 

Attribute Description Type Required
SubjectTT A translation key to the page title. See Localization for more details. String Yes

 

NOTE: A <Page> must contain at least one <Checkpoint>, or a <Block> containing at least one <Checkpoint>. Order between checkpoints that are direct elements of the page, and blocks of checkpoints, is important.

 

 

<Block>

This sub-element is added to the <Page> element as a container for a block of checkpoints, with a title, and possibly a condition. The element can contain <BlockCondition>, <Checkpoint> and nested <Block> elements, and has the following attribute:

 

Attribute Description Type Required
SubjectTT A translation key to the block title. See Localization for more details. String Yes

 

NOTE: Order between each element, whether <Checkpoint> or <Block>, is important. A block without a <BlockCondition> will always be evaluated.

 

<BlockCondition>

This element is a container element with a condition to execute the block's checkpoints. In non- Manual mode, these checkpoints will be skipped if the condition is FALSE when their evaluation starts. The element has no attributes and can contain <Val /> and <Operator> elements.

 

 

<Checkpoint>

A checkpoint element is a single item from a checklist and there can be multiple of them in each <Page>, <Block> or <Checklist.CheckpointLibrary>. This element can contain the following sub-elements:

  1. <CheckpointDesc />
  2. <Sequence>
  3. <Test>
  4. <Action />
  5. <SetTemplateValue>
  6. <SetTemplateAction>
  7. <Instrument />
  8. <ForceCamera />
  9. <Feedback>
  10. <Clue />

 

The <Checkpoint> element has the following attributes:

 

Attribute Description Type Required
ReferenceId The ID of a checkpoint from a loaded Library. This is used to load a shared checkpoint for an aircraft checklist. String Yes
Id The ID of a checkpoint in a Library. This is set in Library files, and used as a reference in aircraft checklist files. String

 

NOTE: Only one <Sequence> or <Test> should be defined per <Checkpoint>. If both are defined, one of them will be ignored. If neither is defined, the checkpoint will be automatically validated in all modes except Manual.

NOTE: All elements except <CheckpointDesc> and <Clue> are ignored while in Manual mode.

 

 

<CheckpointDesc />

This self-closing element is the text description of the checkpoint which will be displayed in the Microsoft Flight Simulator UI. It has the following attributes:

 

Attribute Description Type Required
SubjectTT A translation key to the checkpoint subject. See Localization for more details. String Yes
ExpectationTT A translation key to the checkpoint expected action or state. See Localization for more details. String

 

 

<Sequence>

This element is for listing a sequence of tests that are required to validate the checkpoint. The element can contain the following sub-elements: <Sequence>, <Test>, <Once>, <Duration />, <Instrument />, <Action />. The element has the following attribute:

 

Attribute Description Type Required
SeqType The type of sequence to be used.

Enum:

  • Ordered - Every test and sequence element of this sequence is ordered as in the XML. Whenever the sequence is evaluated, each of those element is evaluated in order, from the first one up until an element that is evaluated to FALSE. Any later element is thus not evaluated during this frame, and their actions will not be executed. The next frame evaluation will start over from the first element.
  • Parallel - Whenever the sequence is evaluated, every test and sequence element of this sequence is evaluated (in order of their XML order) during the same frame.
  • Unordered - Without Copilot mode, the evaluation of this sequence works exactly as the Parallel one: every element is evaluated. However, in Copilot mode, the evaluation will follow the Ordered SeqType. This difference is important to avoid a copilot doing everything (especially actions) at the same time, while still permitting thew user without Copilot mode to complete this sequence in any order.
Yes

 

NOTE: "Frame", as used in the descriptions above, refers to a portion of time during which some computations are done by the simulator, such as the evaluation of various tests and sequences. Usually, one second is composed of at least 30 consecutive frames. Actions and test evaluations can be executed at most once per frame.

 

 

<Test>

This is a container element that contains the logic for a single test to perform. It has no attributes and can contain the following sub-elements: <TestValue>, <Action />, <Once>, <Duration />, <Instrument />.

NOTE: If no <TestValue> is defined, this test will be automatically validated in all modes except Manual.

 

 

<TestValue>

This container element is for a value computation that needs to evaluate to TRUE for the test to be validated. It has no attributes and must contain either the <Val /> or <Operator> sub-elements.

 

 

<Val />

This self-closing element is for a value that will be read as a boolean, meaning 0 is FALSE and non-zero is TRUE. This element is used by the following elements: <Operator>, <BlockCondition>, <TestValue>, <SetTemplateValue>, <SetTemplateAction>, <Action />, <OnlyIf>. It is important to note that the <Val /> element should only ever have ONE of the following attributes (with the exception of SimVarName, which should always be accompanied by the Units attribute):

 

Attribute Description Type Required
Value Constant value.

Float

No
SimVarName Simulation Variable name, as defined here. Must be defined with units. String
Units Units name, as defined here. Must be defined with SimVarName. String
Code Allows for more complex evaluation. String
ReadVar Read the value previously stored in the checklist-specific variable with this name (see the Variable Notes section at the bottom of this page). String
ATCState Name of an ATC State. Used for comparison with an ATCParam State. String
ATCParam Get the current ATC State or the last ATC message ID. Used for comparison with an <ATCState> value, or a constant integer value.

Enum:

  • State
  • LastMessageId
UseTemplateValue Replace this value by the value defined by the <SetTemplateValue> with the same ID in this checkpoint. String

 

 

<Operator>

This element is used to define an operation that will be evaluated using one or several values as set using the <Val /> sub-element. This element is used by the following elements: <Checkpoint>, <BlockCondition>, <TestValue>, <SetTemplateValue>, <SetTemplateAction>, <Action />, <OnlyIf>. It has the following attributes:

 

Attribute Description Type Required
OpType The type of operator to use.

Enum:

  • EQUAL - Returns true (1) if both values are equal, false (0) otherwise. If a Tolerance is defined, returns true if abs(v1-v2) <= Tolerance, instead.
  • LESS - Returns true (1) if first value is (strictly) less than second value, false (0) otherwise.
  • GREATER - Returns true (1) if first value is (strictly) greater than second value, false (0) otherwise.
  • LESS_OR_EQUAL - Returns true (1) if first value is less than or equal to second value, false (0) otherwise.
  • GREATER_OR_EQUAL - Returns true (1) if first value is greater than or equal to second value, false (0) otherwise.
  • BETWEEN - Returns true (1) if first value is greater than or equal to second value and less than or equal to third value, false (0) otherwise.
  • NOT - Returns true (1) is value is false (0), and returns false (0) otherwise.
  • AND - Returns true (1) if both values are true (non-zero), false (0) otherwise.
  • OR - Returns true (1) if at least one of the two values is true (non-zero), false (0) otherwise.
  • PLUS - Returns the sum of the two values.
  • MINUS - Returns the first value minus the second value.
  • MULTIPLY - Returns the product of the two values.
  • DIVIDE - Returns the first value divided by the second value.
Yes
Tolerance Numerical tolerance only used for the Equal OpType. The comparison will then be "Is the difference between the values less than or equal to tolerance?". Float No

 

NOTE: All OpTypes require two <Val /> definitions, except Between - which requires 3 - and Not - which requires only 1.

 

 

<Once>

This is a container element for a simple Boolean value, either True or False., and can be used in <Sequence> and <Test> elements. For example:

<Once>True</Once>
<!-- OR -->
<Once>False</Once>

If, during its evaluation, a test or sequence with a <Once> is validated to True - including its possible duration - then it will remain validated until "Reset", and will never be evaluated again. This means actions within this test or sequence will not be executed later either.

 

 

<Duration />

This self-closing element sets the duration during which the test Value needs to be True for this test to be validated. The element can be used in <Sequence> and <Test> elements, and if a <Test> or <Sequence> is validated but has a non-zero <Duration />, it will not be considered validated until the Duration criteria has also been validated.

 

The element has the following attributes:

 

Attribute Description Type Required
Value Number of seconds. Float Yes
Cumulative Determines if the duration is accumulated on times where the test is Validated even if interrupted by some non-valid time (TRUE, 1), or if the Duration timer is reset is the test becomes non-validated (FALSE, 0). Bool

 

 

<Instrument />

This self-closing sub-element provides a reference to an instrument associated with a test, and the instrument can be highlighted in-game. This element can be used in the <Checkpoint>, <Sequence> and <Test> elements, can have an <OnlyIf> sub-element, and has the following attribute:

 

Attribute Description Type Required
Id The <PartID> of an instrument, as defined in the <Component> element of the [model].xml of the corresponding aircraft. Float Yes

 

Instruments for an aircraft are defined in an *.xml file describing the interior of the 3D model. In this file, <Behaviors> are defined and use Components associated with parts of the model that can have a PartID defined. This PartID can then be used as a reference in a <Checkpoint> to highlight said instrument. A Component with a PartID should also have a CameraTitle and a Node to be able to properly highlight the instrument, and to change the camera to be able to see the instrument more easily. See the section about Model Behaviors for more details.

 

 

<ForceCamera />

This self-closing sub-element is used to specify a camera to be used when highlighting instruments instead of using the regular instruments camera. This is mostly useful when multiple instruments that are far apart need to be highlighted. It's generally considered good practice to put <ForceCamera /> in a checklist file, rather than in a library. Note that this element may also have the child element <OnlyIf>.

 

This element is a sub-element of <Checkpoint> and has the following attribute:

 

Attribute Description Type Required
Name Name of the camera to be used in this checkpoint, regardless of instruments camera, when highlighting instruments. The name of the camera correspond to the "Title" as defined in the

[CAMERADEFINITION.N] parts of the cameras.cfg file.
String Yes

 

 

<OnlyIf>

This element sets a condition that will ensure that the parent <Instrument /> or <ForceCamera /> element will trigger only if the condition is met. The condition is set using the <Operator> or <Val /> sub-elements, for example:

<ForceCamera name="PFD">
    <OnlyIf>
        <Operator OpType="NOT">
            <Val SimVarName="CIRCUIT SWITCH ON:24" Units="Boolean"/>
        </Operator>
    </OnlyIf>
</ForceCamera>

Note that the condition is only checked when - during the frame - the camera/highlight is triggered (e.g. when a user clicks click the "eye" button on the checklist), so it will not do things like blinking highlights if the condition in <OnlyIf> changes over time.

 

 

<SetTemplateValue>

This sub-element defines a value that can then be used inside the checkpoint's other elements. It is mostly used to add parameters to a library checkpoint that can be overridden in a checklist checkpoint. The element is used within the <Checkpoint> element and can contain <Operator> and <Val /> elements. It has the following attributes:

 

Attribute Description Type Required
Id ID of the template value defined here, to be referenced by UseTemplateValue.

When used in a checklist checkpoint referencing (with ReferenceId) a library checkpoint, this ID must correspond to one of the template value IDs defined in the library checkpoint
String Yes
Value Defines a constant value. If defined, this SetTemplateValue's elements will be ignored. Float No

 

Note that this element can also be used as a self-closing element with no sub-elements when a value attribute is given.

 

 

<Action />

This is a self-closing element for the actions that are to be executed during evaluation of the <Sequence>, <Test>, or <Checkpoint> parent element, depending on various conditions. The element has the following attributes:

 

Attribute Description Type Required
Copilot Sets whether this action is executed only in Copilot mode (TRUE, 1) or not (FALSE, 0). Bool Yes
Condition The condition under which to execute the action.

Enum:

  • TestValueTrue - Only if the evaluation of testValue is currently True. If Used in a <Sequence>, uses the value of all sub-tests as a TestValue.
  • TestValueFalse - Only if the evaluation of testValue is currently False. If Used in a <Sequence>, uses the value of all sub-tests as a TestValue.
  • Init - Only when the checkpoint start is being evaluated for the first time since a Reset.
  • End - Only when the checkpoint is completely validated.
  • Any - If defined in an action that is an element of <Test> or <Sequence>, executed every time the testValue is evaluated. If defined in an action that is an element of <Checkpoint>, executed at Init and End of said checkpoint
Yes
Once Sets whether this action is executed only once (TRUE, 1), or not (FALSE, 0). Bool Yes
FlowEvent FlowEvent action. String No
EventID

The event ID action (as listed here: Event IDs).

String No
EventParam The parameter for the EventID (ignored if no EventID is defined). Some EventIDs require a parameter, but not all of them. This is detailed in the Event IDs page. Float No
SpecialAction Any special action that needs to be performed.

Enum:

  • ForceValidate - Force the Validation of this test, ignoring possible duration or testValue not valid. Mainly used for Copilot mode, to ignore an unimportant test that cannot be completed by copilot.
  • WaitForUserToDoIt - Waits until the test is validated. Mainly used for Copilot mode, to force the copilot to wait even if no Copilot action is defined (otherwise the default Copilot behavior is to force validate this test).
  • WaitUntilTestValueValidated - Waits until the test is validated. Mainly used for Copilot mode, to force the copilot to wait even if no Copilot action is defined (otherwise the default Copilot behavior is to force validate this test).
  • WaitForDuration - Once this action triggers (depending on condition), current test cannot be validated (regardless of duration or testValue) until some time has passed. Time (in seconds) must be specified in the value attribute of this action.
No
StoreVar Store a value in a checklist-specific variable with this name (see the Variable Notes section at the bottom of this page). String No
Value Constant value. Used either with storeVar or with the specialAction WaitForDuration. Float No
Code This attribute permits you to add in some RPN code that will be performed when the action executes. String No
UseTemplateAction Replace this action by the action with the same ID that has been defined by <SetTemplateAction>. Other attributes and elements will be ignored. String No

 

NOTE: WaitForUserToDoIt and WaitUntilTestValueValidated work the same way (currently), but it is recommended to use the right one for clarity, because they have a different meaning. WaitForUserToDoIt means the user should manually do some action, and the copilot will not (or cannot) do it, and will not skip it either. WaitUntilTestValueValidated means the only required action is waiting; the user and copilot do not have any action to perform, and this should not be skipped either.

To make sure everything behaves as expected (and for organizational purposes), it is highly recommended to have only one of the following attributes per <Action />:

  • UseTemplateAction
  • FlowEvent
  • EventID
  • SpecialAction
  • StoreVar

This is never limiting, since multiple actions can always be defined in the same element parent.

 

 

<SetTemplateAction>

This sub-element defines an action that can then be used inside the checkpoint's other elements. In general it is mostly used to add parameters to a library checkpoint that can be overridden in a checklist checkpoint. This sub-element can be used in <Checkpoint> elements, and can contain <Operator> and <Val /> elements. It has the following attributes:

 

Attribute Description Type Required
Id The ID of the template action defined here, to be referenced by UseTemplateAction.

When used in a checklist <Checkpoint> referencing (with ReferenceId) a library checkpoint, this ID must correspond to one of the template action IDs defined in the library checkpoint
String Yes
Copilot Sets whether this action is executed only in Copilot mode (TRUE, 1) or not (FALSE, 0). Bool Yes
Condition The condition under which to execute the action.

Enum:

  • IfTestValueTrue - Only if the evaluation of testValue is currently True. If Used in a <Sequence>, uses the value of all sub-tests as a TestValue.
  • IfTestValueFalse - Only if the evaluation of testValue is currently False. If Used in a <Sequence>, uses the value of all sub-tests as a TestValue.
  • Init - Only when the checkpoint start is being evaluated for the first time since a Reset.
  • End - Only when the checkpoint is completely validated.
  • Any - If defined in an action that is an element of <Test> or <Sequence>, executed every time the testValue is evaluated. If defined in an action that is an element of <Checkpoint>, executed at Init and End of said checkpoint
Yes
Once Sets whether this action is executed only once (TRUE, 1), or not (FALSE, 0). Bool Yes
FlowEvent FlowEvent action. String No
EventID

The event ID action (as listed here: Event IDs).

String No
EventParam The parameter for the EventID (ignored if no EventID is defined). Some EventIDs require a parameter, but not all of them. This is detailed in the Event IDs page. Float No
SpecialAction Any special action that needs to be performed.

Enum:

  • ForceValidate - Force the Validation of this test, ignoring possible duration or testValue not valid. Mainly used for Copilot mode, to ignore an unimportant test that cannot be completed by copilot.
  • WaitForUserToDoIt - Waits until the test is validated. Mainly used for Copilot mode, to force the copilot to wait even if no Copilot action is defined (otherwise the default Copilot behavior is to force validate this test).
  • WaitUntilTestValueValidated - Waits until the test is validated. Mainly used for Copilot mode, to force the copilot to wait even if no Copilot action is defined (otherwise the default Copilot behavior is to force validate this test).
  • WaitForDuration - Once this action triggers (depending on condition), current test cannot be validated (regardless of duration or testValue) until some time has passed. Time (in seconds) must be specified in the value attribute of this action.
No
StoreVar Store a value in a checklist-specific variable with this name (see the Variable Notes section at the bottom of this page). String No
Value Constant value. Used either with storeVar or with the specialAction WaitForDuration. Float No
Code This attribute permits you to add in some RPN code that will be performed when the action executes. String No
UseTemplateAction Replace this action by the action with the same ID that has been defined by <SetTemplateAction>. Other attributes and elements will be ignored. String No

 

Similar to the <Action /> element, it is recommended to have only one of the following attributes:

  • FlowEvent
  • EventID
  • SpecialAction
  • StoreVar

 

 

<Feedback>

This self-closing sub-element is used to set the text to be displayed in the interface while evaluating the checkpoint in non-Manual mode. This text will be displayed when the checkpoint is being evaluated in Automatic or Copilot mode. It is a sub-element of <Checkpoint> and has the following attributes:

 

Attribute Description Type Required
Name A translation key to the feedback text. See Localization for more details. String Yes
DurationTimer If set to TRUE (1), it will display the remaining total duration time in real-time, as seconds, in the text in place of a %f. Bool No
SimVarName If defined, will display the value of the corresponding simvar in the text in place of a %f. String Yes
Units Units of the simVar. Must be defined if SimVarName is defined. Float Yes

 

A <Feedback /> element can contain at most one of the following (sets of) attributes:

  • DurationTimer
  • SimVarName and Units

When either is defined, if the translated text contains %f, it will be replaced by the corresponding value, but only the first time the symbols appear in the text (so only use %f once in any given message). You can also use %.0f to display 0 digits after the decimal, and similarly %.1f for 1 digit after the decimal, %.2f for two digits, etc...

 

 

<Clue />

This self-closing sub-element of the <Checkpoint> element is for the text to be displayed in the interface while a checkpoint is selected. This text will be displayed when the checkpoint is clicked in Manual mode, or in non-started Automatic mode. In started Automatic mode, it will also display for the currently evaluated checkpoint if it does not have a <Feedback> text.

 

It can take the following attribute:

 

Attribute Description Type Required
Name A translation key to the clue text. See Localization for more details. String Yes

 

 

Variable Notes

The attributes StoreVar and ReadVar can be used to create variables that are specific to the checklist and let the checklist use them. These variables are destroyed whenever a checklist page is "Reset" (either by pressing the "Reset Page" button in the simulator UI, or by restarting the mission). The names you give for these variables can be any string, and all stored values are numbers. Should you require a boolean (True/False) value, this should be represented by 0 for FALSEand 1 for TRUE. Note, however, that any non-zero number will evaluate to TRUE when used as a boolean.

 

ReadVar can be used in a <Val /> element to retrieve a previously stored variable. If the requested variable has never been stored, it will return 0 instead.

 

StoreVar can be used in an <Action /> or a <SetTemplateAction> element to store a value in a variable. The corresponding action must contain one of the following:

  • a <Val /> element
  • an <Operator> element
  • a Value attribute, containing a constant number

If more than one of the above elements are defined in the action, behavior is undefined. If none are defined, 0 will be stored by default (erasing any previous value stored in this variable).