Checklist XML Properties

The <checklist_filename>.xml file goes in a Checklist folder and should be formatted as follows:

<?xml version="1.0" encoding="UTF-8"?>
<SimBase.Document Type="Checklist" version="1,0">
    <Checklist.Checklist>
        
        <Step ChecklistStepId="<ID>">
            <Page SubjectTT="<PAGE_TITLE>">
                
            </Page>
        </Step>
        
    </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.

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

• Checklist Examples

You can find a information on how checklists work, how they should be designed, and also a tutorial on creating a simple checklist, from the following links:

• Checklist Best Practices
• Checklist Flow
• Creating A Checklist

Finally, there are additional XML elements and attributes that are common to all SimObject XML files which can be used in the checklist XML. These are all related to the modular SimObject Merge Process, and can be ignored if the SimObject is not modular. You can find these elements and attributes here:

• Modular SimObject XML Properties

Checkpoint Libraries#

Checklist data can be separated into several files, in *.xml format. The files are located in a /Checklist folder, inside the aircraft common folder, or a folder associated with an attachment or preset.

 
As similar checkpoints can be found in various aircraft checklists, there is a way to reference shared checkpoint definitions using a checkpoint library XML file. These files can be created to define any number of checkpoints as long as each of these checkpoints have a unique ID attribute, which can be called from regular checklist files. Once a checkpoint library has been created, an aircraft checklist file can include the file by specifying it’s path. Then, checkpoints can be defined by simply supplying a Reference ID, containing the ID of a checkpoint from the previously created library.

If you are creating a checkpoint library then it should have the following formatting:

<?xml version="1.0" encoding="UTF-8"?>
<SimBase.Document Type="CheckpointLibrary" version="1,0">
    <Checklist.CheckpointLibrary>
        
    </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.

It is worth noting that there is a default checkpoint library called Asobo_DefaultCheckpointLibrary.xml included as part of the simulation SDK which you can access in your own projects.

<Checklist.Checklist>#

This element is a container element for all the checklist details. This element can contain the following sub-elements:

1. <IncludeCheckpointLibrary />
2. <IncludeChecklist />
3. <Step>

This element has the following attribute:

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

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

<IncludeChecklist />#

This sub-element can be added to a <Checklist.Checklist> to point the checklist to another checklist in the package to be “merged” with the one being defined. This is a self-closing element that takes one attribute:

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

The pages that are included in the steps below will appear in the Preflight section in the EFB display:

1. PREFLIGHT_GATE
2. PREFLIGHT_PUSHBACK
3. PREFLIGHT_TAXI_OUT

The pages that are included in the steps below will appear in the Inflight section in the EFB display:

1. FLIGHT_RUNWAY
2. FLIGHT_TAKEOFF
3. FLIGHT_CLIMB
4. FLIGHT_CRUISE
5. FLIGHT_DESCENT
6. LANDING_APPROACH
7. LANDING_APPROACH_VFR
8. LANDING_APPROACH_IFR
9. LANDING_FINAL
10. LANDING_TOUCHDOWN

The pages that are included in the steps below will appear in the Postflight section in the EFB display:

1. LANDING_GROUNDROLL
2. LANDING_TAXI_IN
3. LANDING_GATE

<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 2024 EFB with a title. It is basically used to group one or several checkpoints in a single page of the checklist. The element can contain the following sub-elements:

1. <Checkpoint>
2. <Block>

This element has the following attribute:

<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 the following sub-elements:

1. <Block> - note that in the context of the default Aircraft Application in the EFB, only one block can be nested inside another block, but the code supports the nesting of multiple blocks up to any depth. However this will require a custom EFB application to be visible.
2. <BlockCondition>
3. <Checkpoint>

This element has the following attribute:

<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 the following sub-elements:

1. <Val />
2. <Operator>

<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. <Clue />
3. <Instrument />
4. <ForceCamera />
5. <Sequence>
6. <Test>
7. <Action />
8. <SetTemplateValue>
9. <SetTemplateAction>
10. <Feedback>

The <Checkpoint> element has the following attributes:

<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. It can take the following attribute:

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

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

<CheckpointDesc />#

This self-closing element is the text description of the checkpoint which will be displayed in the Microsoft Flight Simulator 2024 EFB. 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:

1. <Sequence>
2. <Test>
3. <Once>
4. <Duration />
5. <Instrument />
6. <Action />

The element has the following attribute:

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

1. <TestValue>
2. <Action />
3. <Once>
4. <Duration />
5. <Instrument />

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

1. <Operator>
2. <BlockCondition>
3. <TestValue>
4. <SetTemplateValue>
5. <SetTemplateAction>
6. <Action />
7. <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:

1. <Checkpoint>
2. <BlockCondition>
3. <TestValue>
4. <SetTemplateValue>
5. <SetTemplateAction>
6. <Action />
7. <OnlyIf>

It has the following attributes:

<Once>#

This is a container element for a simple Boolean value, either True or False, and can be used in the following elements:

1. <Sequence>
2. <Test>

For example:

<Once>True</Once>

<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

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

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:

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:

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:

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…

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 FALSE and 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).