-
Notifications
You must be signed in to change notification settings - Fork 8
Checklist development documentation
When the X-Plane loads a plane, Xchecklist looks to the airplane's directory and tries to load the acf specific checklist first (acfName_clist.txt), and if not found, the generic clist.txt is loaded.
The checklist file contains series of checklists for the given aircraft.
Each checklist starts with the sw_checklist statement. This statement specifies the title of the checklist, and optionally the name, under which it appears in the XChecklist's menu (when the optional part is missing, the menu item is not created). This way the "entry points" of multi-page checklists are accessible via menu, without cluttering the menu with the interim pages.
sw_checklist:Checklist name
sw_checklist:Checklist name:Menu name
The checklist itself can contain several types of statements:
- sw_item - normal checklist item - spoken by copilot, checkable both manually and automatically
- sw_iteminfo - checklist item, checkable only by fulfilling the condition
- sw_itemvoid - noncheckable checklist item; ignored by copilot
- sw_remark - remarks spoken by copilot (no condition, non-checkable)
- sw_show - when no checklist is displayed and a condition is fulfilled, the checklist pops up
- sw_continue - designates which checklist should come next, when the current one finishes
- sw_rcolsize - specifies the size of the "right column" of the checklist
This is the most used checklist item. There are several forms of this item:
sw_item:Item text
sw_item:Item text|Checked text
This form displays a checkbox with the "Item text" caption; if the text contains a colon character,
the text following it is displayed on the right side, otherwise the text "CHECK" is used.
The checkbox must be checked by the pilot.
sw_item:Item text:dataref expression
This form allows the "copilot" check the item for you based on the dataref expression
Dataref expressions allows the "copilot" to check the checklist item or pop up a checklist based on the conditions/pilot actions. The expression can range for simple dataref value equality test to fairly complex expressions.
test/dataref:1
test/dataref:=1
true when the dataref "test/dataref" equals to 1
test/dataref:!1
true when the dataref "test/dataref" is not equal to 1
test/dataref:<1
true when the dataref "test/dataref" is lower than 1
test/dataref:>1
true when the dataref "test/dataref" is greater than 1
test/dataref:<=1
true when the dataref "test/dataref" is lower than or equal to 1
test/dataref:>=1
true when the dataref "test/dataref" is greater than or equal to 1
test/dataref:+>1
true when the dataref "test/dataref" grows more than 1 after the item is activated
test/dataref:-<1
true when the dataref "test/dataref" shrinks more than 1 after the item is activated
test/dataref:><1
true when the dataref "test/dataref" changes by more than 1 after the item is activated
test/dataref:10|20
true when the "test/dataref" is in the interval of 10 to 20.
test/dataref:10:20
true when the "test/dataref" changes from lower than 10 to higher than 20. If the dataref's
value is not lower than 10 when the check is activated, it has to get below 10 first.
The right side of the dataref expression can be a simple number, or it can involve arithmetic, datarefs and several functions.
test/dataref:((1+2)*3)**4
Valid operations are addition, subtraction, multiplication, division and power (**). Also
parentheses can be used to enforce different priority.
test/dataref:{test/other_dataref}+1
Expression can contain datarefs too
test/dataref:(float)1
Datarefs typa can be explicitly stated in case the dataref exists in more than one variant.
Available types are int, float and double
test/dataref:round({test/other_dataref})
Expressions can call one of several functions (round, step, closer_than)
round(value)
rounds the value to the nearest integer
step(value)
equals to 1 when value >= 0, 0 otherwise
closer_than(value1, value2, epsilon)
returns 1.0 when value1 and value2 differ by less than epsilon, 0.0 otherwise
Should you need more, please contact the developers.
Several dataref expressions can be combined using boolean operations.
(expression1)&&(expression2)
true when both expressions are true
(expression1)||(expression2)
true when either one(or both) of the expressions are true
All of the above can be combined together to form very elaborate constructions. With that said, try to avoid the "when the tool I have is a hammer, then every problem looks like a nail" problem. Sometimes it might be good to consider to use some other methods (lua helper plugin computing those expressions and publishing the results in datarefs) to keep the complexity in reasonable limits. It will help with the overall readability and maintainability of the checklist.
This item behaves mostly like the sw_item, with one distinction - user can't check it manually. That means that it has to have the dataref expression specified.
sw_iteminfo:Item label|Check label:test/dataref:1
This item is useful for adding delimiters, welcome messages and other parts of checklist, that are just displayed. Also they aren't read by the speech synthesizer.
sw_itemvoid:Item label|Check label
This item is somewhat similar to the sw_itemvoid, with the only distinction that it is read by the speech synthesizer. It can be used for example to compliment the pilot...
sw_remark:You did nicely!
This item doesn't show up on the checklist, but allows a checklist to pop up when a specified condition if fulfilled. The sw_show conditions aren't checked when another checklist is being displayed (so it doesn't interrupt it).
Disclaimer: The following paragraphs are just a view of one of the authors, so think about it and feel free to ignore it if you see fit...
sw_show seem like a very convenient feature, which allows construction of very clever checklists. It might for example pop up after take off checklist when you reach certain altitude, or pop up a relevant checklist when a fire alarm sounds, ... Unfortunately there seems to be a downside to this kind of automation - in my view the pilot should know when a certain checklist is due and he should open it by himself - that way his memory is exercised and I think it also adds to the realism of the simulation (checklists don't pop up automatically in real plane either)... Also inflight emergencies might be a good example of this view - the pilot should be able to identify the source of the problem, while if the correct emergency checklist pops up by itself, it is a sort of giveaway...
On the other hand, some people might argue that when a checklist pops up automatically, it reminds the pilot _to perform it, so when in the real plane, he/she will remember to perform the checklist. _
So feel free to use sw_show, just think whether it will really help pilots learning...
This is another item that doesn't show on the checklist, but it allows creation of "seamless" multi-page checklists. If this statement is specified for a given checklist, then when the said checklist is finished, the checklist specified by the sw_continue is opened up automatically. When no label is specified, next checklist is used, otherwise a checklist with a given label (first field of sw_checklist) is displayed.
sw_continue
sw_continue:Checklist name
Since 1.26b7 there is a possibility to attach a dataref condition to the sw_continue and several sw_continue statements can be attached to a checklist. This allows you to create a conditional "detours" in the checklist flow - for example when some equipment is used optionally, you can add a checklist page that reflects its usage.
The sw_continue statement conditions are analyzed from the top to the bottom and the first one whose condition is true (or without a condition) is followed. Since the conditions are checked only at the moment the checklist is finished, dataref conditions analyzing dataref evolution in time ("+>", "-<", "><", ...) can't be used, as they always evaluate false when checked for the first time.
sw_continue:Start with GPU:sim/cockpit/electrical/gpu_on:1
sw_continue:Start without GPU
Checklist window width is determined automatically from the length of items displayed. Item sw_rcolsize explicitly specifies width of the right side field, which helps to keep checklist from changing width when different pages are displayed.
sw_rcolsize : 150
Use checker to quickly check the checklist for syntax errors - the check is done pretty much instantly and saves a lot of time compared to reloading the checklist in the X-Plane and looking at the Log.txt to look for errors.
Use sw_checklist's second field (Menu name) for main checklist block starting points to provide the pilot with possibility to select a checklist he needs without big flipping back and forth.
Some people asked for possibility to switch back and forth between checklists while remembering the state in which the checklist was left. So far these requests were turned down, because of the following reason: it is a belief of at least one of the authors that a checklist should be performed in one go, without interruptions. If the process is interrupted, the checklist should be started again, to avoid possibility of resuming at a wrong point skipping some crucial steps/steps... That said, if you know of a valid reason to resume a checklist please bring the point up and we can discuss it...