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:
|
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:
<CheckpointDesc />
<Sequence>
<Test>
<Action />
<SetTemplateValue>
<SetTemplateAction>
<Instrument />
<ForceCamera />
<Feedback>
<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:
|
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:
|
|
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:
|
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 OpType
s 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:
|
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 EventID s 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:
|
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:
|
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 EventID s 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:
|
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).