docs-mini/README.tutorial

   1 The tutorial system is a Nasal script that runs tutorials defined by a set
   2 of properties under /sim/tutorial. The tutorials are automatically picked up by
   3 the GUI, and can be found under the Help menu item.
   4
   5 Tutorials are typically tied to specific aircraft and defined in a
   6 separate XML file as follows:
   7
   8 <sim>
   9   <tutorial include="c172-tutorial.xml"></tutorial>
  10 </sim>
  11
  12 Each tutorial is defined by a "tutorial" leaf under /tutorial, and consists of
  13 the following elements.
  14
  15 name        - The name of the tutorial, used in the GUI
  16 description - A plain-text description of the tutorial, displayed in the GUI.
  17 audio-dir   - (Optional) The directory (relative to FG_ROOT) to pick up any
  18               wav files used.
  19 timeofday   - (Optional) .Time of day (morning, noon, evening...). Used to
  20               set the initial tutorial state.
  21 presets     - (Optional) Properties to be set under /sim/presets, followed
  22               by a presets-commit command. Used to set the initial tutorial
  23               state. e.g. airport-id, runway, heading-deg
  24 init        - (Optional) Initial tutorial state properties to set.
  25               Consists of one or more set nodes (see below for details).
  26 step        - A tutorial step (see below for details)
  27 endtext     - Text to display at the end of the tutorial
  28 endtext-voice - .wav filename to play at the end of the tutorial
  29 endtext-tts - Text to send to text-to-speech engine at the end of tutorial
  30
  31
  32 The bulk of the tutorial definition consists of step definitions. These are
  33 discreet stages within the tutorial lasting at least 5 seconds. Typically the
  34 consist of an instruction from the FG instructor, some exit criteria used to
  35 check that the user has performed the step correctly and can move to the next
  36 step, and a series of error conditions to check the user isn't deviating.
  37
  38 Each step consists of the following elements:
  39
  40 instruction        - Text to display to the user when they enter the step, and
  41                      when they have still to fulfill the exit criteria
  42 instruction-tts    - text to send to the text-to-speech (TTS) engine
  43 instruction-voice  - .wav filename to play
  44 set                - (Optional) properties to set when entering the step. May
  45                      be more than one.
  46 error              - Error conditions, consisting of one or more check nodes
  47                      with messages (see below)
  48 exit               - Exit criteria, consisting of one or more check nodes
  49                      without messages.
  50
  51 Set nodes consist of
  52
  53 prop - The property name to set
  54 val  - The value to set.
  55
  56 For example
  57
  58  <set>
  59    <prop>/controls/engines/engine/throttle</prop>
  60    <val>0.5</val>
  61  </set>
  62
  63
  64 Check nodes consist of a property to check, a single operator, and (for error
  65 nodes) a message to display if the check evaluates to true.
  66
  67 prop - The property to check
  68 lt   - the value to check the property is less than
  69 gt   - the value to check the property is greater than
  70 eq   - the value to check the property is equal to.
  71 msg  - (error node only) text message to display
  72 msg-tts - (error node only, optional) message to send to TTS engine
  73 msg-voice - (error node only, optional) .wav filename to play
  74
  75 For example:
  76
  77  <check>
  78    <prop>/controls/engines/engine/throttle</prop>
  79    <lt>0.95</lt>
  80    <msg>Apply full throttle for take-off.</msg>
  81  </check>
  82