Cold&Dark Checklists

Change List

A list of changes made to this document.

Version	Date	Revision
1.0	03/07/2017	Initial document.
1.01	02/10/2017	Added small section on XToMDL.

Introduction

The checklist is a feature designed to aid both new and advanced pilots in starting an aircraft from a cold and dark state. The checklist has two components, a 3D model within the plane which is used to open the checklist and then a 2D Scaleform popup which contains the content of the checklist. The checklist allows the user to work their way through the startup procedure for an aircraft without having to refer to tools or resources outside of the simulator causing a break in immersion. It also contains a variety of aids for novice pilots to locate and modify the various controls, buttons and levers in the aircraft.

3D Model

All aircraft require a 3D Model of the checklist within the aircraft. The 3D model has three states controlled by two simvars as detailed below.

Simvar	Description	Type
CHECKLIST_STATE	The state of the 3D checklist model in the plane. 0 is the initial state (usually in front of the pilot), 1 is the secondary state (usually in the map pocket or similar).	Number
CHECKLIST_VISIBLE	If the 3D checklist is visible in the cockpit. The 2D panel is visible when the 3D checklist is not. 0 when the 3D checklist is not visible, 1 when it is.	Bool

State	Description	CHECKLIST_STATE	CHECKLIST_VISIBLE	2d panel visible?
In front of pilot	3D checklist is visible in front of the pilot and the 2D checklist is not visible.	0	1	No
In pocket	3D checklist is visible in the map pocket (or other storage location) and the 2D checklist is not visible.	1	1	No
Not visible	The 3D checklist is not visible and the 2D checklist is visible.	Any	0	Yes

2D Panel

The 2D panel appears on the lower left of the screen when the 3D checklist model is clicked. It has a background design which is possible to customize per plane and its content is customized with JSON files. The button in the upper right of the checklist closes it and returns the 3D model of the checklist back to its secondary state (usually the map pocket). There's a list with all of the checklist steps specified in the JSON file which will get ticked off as the pilot completes those steps in the checklist. The checklist has two modes which are explained below: basic and advanced. There is no additional development required to support both modes in an aircraft, but they are worth being aware of. The button on the sticky notes is used to swap between basic and advanced modes. The two arrow buttons are used to change pages.

Basic Mode

Basic mode is designed for newer or inexperienced pilots and has additional aids aimed to gently introduce the concept of starting the aircraft and avoid confusion. When in basic mode you always have one checklist step selected and the camera is always locked to prevent moving the camera around and getting lost. When you select an item in the checklist the camera will move to a camera where that item is on screen and the item will begin to pulse with a light blue glow to aid with finding the control. You can then either interact with the control as normal or click the button on the right hand side of the step to automatically complete that step. While in basic mode the checklist must be followed in order, each step must be completed one after the other and you must click on the next step to advance to it. This is designed to streamline the experience for pilots learning the aircraft and newer simmers so that they have no chance of getting confused by steps being completed out of order or losing the control on the screen.

Advanced Mode

The advanced mode can be toggled using the sticky notes button on the bottom of the checklist. Advanced mode is designed to provide an experience more appropriate for an experienced simmer or pilot, where the checklist is used merely as a guide or reminder as it would be in a real aircraft. When in advanced mode the checklist shows the current state of the aircraft, so if there is for example a step for fuel pump on and one for fuel pump off only one of those will ever be ticked. The camera is unlocked and reset to the main cockpit camera when in advanced mode and the user is free to move or change cameras as they wish. If the pilot gets stuck on a checklist step or can't find a control then clicking that checklist step will apply the pulsing effect to the control for that step and the auto complete button becomes functional. Checklist steps can be completed in any order in advanced mode as it simply shows the current state of the aircraft, it's up to the pilot to determine if they have completed the checklist successfully.

JSON Files

The checklist gets its data and customization from JSON files stored in SimObjects/Airplanes/PlaneName/checklists. These JSON files specify what test is displayed to the user for each checklist step, which camera is used, which control is highlighted, which control is affected when auto complete is pressed and which variables are checked to determine if the step is complete. Currently one JSON file titled "Checklist.json" is supported. See SimObjects/Airplanes/Piper_PA34/checklists/Checklist.json for an example file. If you have not encountered JSON files before they are relatively simple to figure out from inspecting the files, however w3schools has a good, but mostly Javascript focused, JSON tutorial which may be of use here if there are any queries about syntax.

Checklist Part Name

The checklist part name is the object/part name in 3ds max of the 3d checklist model. This will be used to emphasize the checklist briefly (make it flash for a few seconds) at the start of a cold and dark flight to draw the user's attention to it.

Pages

Each checklist can have a number of pages where each page can have a header/title and a number of checklist entries. A page can have a maximum of 12 checklist entries in it, but can have fewer if required. The pages are specified with an array and there can be as many pages as required, although usually two or three is enough for most GA aircraft.

Heading

Each page has a heading which is displayed in a box above the page. This can be a translation string (@IDS_SOMETHING) if required.

Checklist Entries

Each page has a number of checklist entries which are the steps on the checklist which can be selected, completed and ticked off. There is an array of checklist entries where each checklist entry is an object with the attributes listed below.

Display Name
The display name is the text that will be displayed to the user on the left side of the checklist item, this can also be a translation string (@IDS_SOMETHING). This should be the name or description of the checklist step e.g "Master battery switch" or a translation string which maps to a similar string.

Display Value
The display value is the text that will be displayed to the user on the right side of the checklist item, which again can be a translation string. This should be the value that the step is looking for from the control. e.g "ON" , "BOTH" or "15%". This is purely the text which is shown to the user, this is not tied to any logic. The button the text is within while that step is selected should automatically resize to fit the text.

Camera GUID

The camera GUID specifies which camera should be displayed when this checklist item is selected. This GUID can be found in the camera section of the Aircraft.cfg file for the aircraft and copied from there for whichever camera is wanted. When the checklist item is selected the view will jump to this camera (resetting the camera if the user has moved it).

Part Emphasis
The part emphasis array specifies which parts should be highlighted in the cockpit when this checklist item is selected. This is an array so multiple parts can be listed, however currently only the first part will flash. It is recommended that to achieve multiple parts flashing you either merge the parts into one (if possible) or add some new geometry which will be highlighted. The part names listed here match up directly with the names of objects in 3ds Max which get exported when the model is run through XtoMDL using the /PARTNAMES argument.

Multiple object meshes often share materials. In such cases it is crucial to suffix object names with ‘_chk’, otherwise parts may not be highlighted individually as expected. The object name with suffix should then be referenced in the checklist json.

Order Dependent
The order dependent attribute is an optional attribute which defaults to true. If set to false this will allow the checklist entry when in basic mode to be completed ahead of the steps before it. This is currently primarily used for steps like the engine glow step on the DA42 where it will appear on screen and complete itself without user input, so selecting that item on the list before completing it is not required.

Controls
Controls are the main logic of the checklist, the section that provides functionality. The controls are used to verify if the checklist step is complete and also to set the various simvars and controls needed when you click the auto complete button. Without any controls listed the checklist will simply sit there looking pretty. A control is a section of logic which can either complete something (set a simvar, set a local variable, toggle a key event) or verify something (check that the engines are combusting), or both. There are four types of control, float simvars, bool simvars, keypress events and local variables, details of which are listed below. Each of these behave differently but share some common attributes. The type of control will be automatically interpreted from the values given in the control so there is no need to specify which type of control it is.

Type
All checklist entries have a type. This is just a string which can either be "BOTH", "COMPLETE" or "VERIFY" (all caps).
Verify controls will be checked to see if the step is complete and if all of the verify controls are as they should be the checklist item will flag as complete. So for example it will check that the simvar/s (or simvar and local var etc) specified are set to the value listed and if so flag the step as complete.
Complete controls will be triggered when the auto complete button is pressed and are used to set simvars, or toggle key events. These will not be triggered if the auto complete button is pressed while the step is already complete (so you don't need to worry about it un-toggling a switch when using a toggle event for example).
Both controls will be evaluated as both a complete and a verify control.

Float Simvar

A float simvar has the following attributes:
id where the ID is the name of the simvar (and index if applicable) in the format you would use it in gauge code.

value where value is the value (as a float) that the simvar will be either checked against (for verify) or set to (for complete).

accuracy is how much (in exact units not percentage) the simvar can be off of the value and still count as complete. E.g a value of 250 with a accuracy of 20 will count as complete between 230 and 270. Accuracy will default to 0 if not specified.

Float simvars are used for every simvar that isn't a bool, regardless of if it is specified in percent, radians, feet per second etc. Everything passed through here will be evaluated with the unit of "number".

Bool Simvar

Bool simvars are used for simvars that are specific boolean in type and have the following attributes:

id where the ID is the name of the simvar (and index if applicable) in the format you would use it in gauge code.
value where value is the value (as a bool) that the simvar will be either checked against (for verify) or set to (for complete).

Local Variable
Local variable controls are used to set and check variables which have been set in gauge or modeldef code using the L: prefix. If the variable has not yet been created or referenced in a bit of gauge code somewhere it will just be ignored. A local variable control has the following attributes:

name where the name is the name of the local variable as used in the gauge code. This is case sensitive.
value where value is the value (as a float) that the local variable will be either checked against (for verify) or set to (for complete).
accuracy is how much (in exact units not percentage) the local variable can be off of the value and still count as complete. E.g a value of 250 with a accuracy of 20 will count as complete between 230 and 270. Accuracy will default to 0 if not specified.

Key Event
Key event controls are a special case in that they can only be used to complete not to verify. A keyevent has one attribute which is id which is the name of the key event in the event IDs documentation but without the KEY_ prefix.

Alternate Value Syntax

Alternatively, for both the Float Simvar and Local Variable control types it is possible to specify a simvar to use instead of a value. If a simvar is specified when evaluated the value of the simvar will be used in place of a constant value. This is useful for example for setting mixture to the correct value for starting the engine based on current altitude and air density by using the "IDEAL START MIXTURE POSITION" simvar.

Visual Customization

Customizing the visuals of the checklist can be achieved using the ChecklistBG.png image in Aircraft_Name/checklists. Any image placed here will be applied as the background image for the checklist for that aircraft. It is recommended that these images try to be consistent with those shipped with the default aircraft but with different text, colours or logos applied. However where applicable to the aircraft, for example with historic aircraft it may be preferred to change the style. These images should be 400x460 pixels however different sized images will be automatically scaled, with varying results depending on the aspect ratio of the image. Changing the shape of the checklist can be done using transparency in the ChecklistBG.png image.

XToMDL
In order to compile the aircraft .X file into .MDL binary format with a working checklist, XToMDL must know to include the checklist JSON files. This is done by adding the flag /PARTNAMES as an argument when invoking XToMDL via the command-line.

This is usually unnecessary for aircraft exteriors and may actually cause in-game errors if the JSON files reference parts absent from such models.

FAQ

Why does my aircraft not start in cold and dark mode/with the checklist?

When starting cold and dark the sim will now correctly set the status of items like magnetos and mixture to off, cut etc. This may cause issues if the aircraft is assuming these are on. Try checking that the magnetos are getting set to on when the starter is triggered (both within the aircraft and the checklist controls) for aircraft which don't have actual magneto switches you can switch, e.g the default DA40.

Why do I get asserts about my local variable not existing?

Local variables are created when they are first used by a gauge or model. You can get around this by referencing it when you initialize the aircraft or gauge so that it gets created then. Otherwise the checklist won't be able to use it until it has been referenced by a gauge or model.

I have a checklist step which completes itself but in basic mode it's impossible to complete if the user doesn't click on the step quick enough as it will have already happened!

If you set orderDependent to be false on that checklist step that should enable the step to be completed without clicking on the step in basic mode.

How do you tell if the flight is cold and dark for the purposes of initializing avionics and local variables etc?
For initializing parts of the aircraft correctly that are not managed by the engine (custom variables etc) it is recommended that you have an initialization sequence which runs just once when the aircraft is created, which will check the state of the engine (if it is combusting or not) and determine from that if things should be initialized for cold and dark or "normal" flight. An example of this would be the battery switch in the default PA18 which has three states managed by a custom variable while the engine only supports two.

What are the @ symbols on text strings in the checklist?

The @ symbols on text strings (usually @IDS_SOMETHING) specify that the string is a Flight Sim World translated string so will be replaced with a localized version of the string at run time in the language the sim is running in. This will be explained in more detail in its own page in future.