4,400
edits
Tutorials: Difference between revisions
Jump to navigation
Jump to search
m
Robot: Cosmetic changes
mNo edit summary |
m (Robot: Cosmetic changes) |
||
| Line 18: | Line 18: | ||
</sim> | </sim> | ||
==Structure== | == Structure == | ||
A tutorial has this structure, where some of the elements are described in detail below: | A tutorial has this structure, where some of the elements are described in detail below: | ||
| Line 135: | Line 135: | ||
After the tutorial has finished initialization, it goes through all <steps>. For each it outputs the <message> or <audio>, optionally sets a <marker> and/or a <view>, then it checks all <error>s and, if an <error><condition> is fulfilled, outputs the respective <error><message>. If none of the <error>s occurred, then it checks if the <exit><condition> is true, and if so, it jumps to the next <step>. Otherwise the current <step> is endlessly repeated. Finally, after all <step>s were processed, the <end> group is executed. | After the tutorial has finished initialization, it goes through all <steps>. For each it outputs the <message> or <audio>, optionally sets a <marker> and/or a <view>, then it checks all <error>s and, if an <error><condition> is fulfilled, outputs the respective <error><message>. If none of the <error>s occurred, then it checks if the <exit><condition> is true, and if so, it jumps to the next <step>. Otherwise the current <step> is endlessly repeated. Finally, after all <step>s were processed, the <end> group is executed. | ||
==Elements== | == Elements == | ||
===Nasal=== | === Nasal === | ||
Embedded Nasal is supported on the top level, in <init> in each <step>, in a <step>'s <error> and <exit>, and in <end>. All Nasal runs in a separate namespace __tutorial, so it's possible to define a function in the <init>'s Nasal block, and to use this function in other blocks without prefix. The namespace is preloaded with some functions: | Embedded Nasal is supported on the top level, in <init> in each <step>, in a <step>'s <error> and <exit>, and in <end>. All Nasal runs in a separate namespace __tutorial, so it's possible to define a function in the <init>'s Nasal block, and to use this function in other blocks without prefix. The namespace is preloaded with some functions: | ||
| Line 156: | Line 156: | ||
</nasal> | </nasal> | ||
===Models=== | === Models === | ||
This loads models into the scenery. It can be used to place, for example, a helicopter landing pad at an airport where normally none is, so that the tutorial can train landing. The layout is the following, with <path> being relative to $FG_ROOT: | This loads models into the scenery. It can be used to place, for example, a helicopter landing pad at an airport where normally none is, so that the tutorial can train landing. The layout is the following, with <path> being relative to $FG_ROOT: | ||
| Line 177: | Line 177: | ||
The models are only removed before a new tutorial is loaded. Otherwise they remain in the scenery for the whole FlightGear session. They aren't permanently added. | The models are only removed before a new tutorial is loaded. Otherwise they remain in the scenery for the whole FlightGear session. They aren't permanently added. | ||
===Targets=== | === Targets === | ||
These are simple pairs of longitude/latitude under an arbitrary name (here "hospital" and "helipad"): | These are simple pairs of longitude/latitude under an arbitrary name (here "hospital" and "helipad"): | ||
| Line 232: | Line 232: | ||
that in this number of minutes it will be away twice as far. | that in this number of minutes it will be away twice as far. | ||
===Preset=== | === Preset === | ||
These set the initial simulator state. All properties are optional. The last three entries are to define the position relative to the airport/runway or the longitude/latitude. | These set the initial simulator state. All properties are optional. The last three entries are to define the position relative to the airport/runway or the longitude/latitude. | ||
| Line 251: | Line 251: | ||
</presets> | </presets> | ||
===Set=== | === Set === | ||
<set> groups can be used in <init>, <step>, and <end>. They set a <property> to a given <value> or to the value that a second <property> points to. They can also reset values that were only temporarily changed for the duration of the tutorial. This is desirable for properties that are saved to the aircraft config file or to ~/.fgfs/autosave.xml. | <set> groups can be used in <init>, <step>, and <end>. They set a <property> to a given <value> or to the value that a second <property> points to. They can also reset values that were only temporarily changed for the duration of the tutorial. This is desirable for properties that are saved to the aircraft config file or to ~/.fgfs/autosave.xml. | ||
| Line 264: | Line 264: | ||
</set> | </set> | ||
===View=== | === View === | ||
These groups can be used in <init>, <step>, and <end>. They smoothly move the view to a new view position/direction. All parameters are optional. If, for example, only <field-of-view> is set, then the view will only zoom in -- the direction and position will remain the same. This feature is meant for cockpit tutorials, where the pilot's view is directed to some switch or instrument. | These groups can be used in <init>, <step>, and <end>. They smoothly move the view to a new view position/direction. All parameters are optional. If, for example, only <field-of-view> is set, then the view will only zoom in -- the direction and position will remain the same. This feature is meant for cockpit tutorials, where the pilot's view is directed to some switch or instrument. | ||
| Line 277: | Line 277: | ||
</view> | </view> | ||
===Marker=== | === Marker === | ||
These are supported in <init>, <step>, and <end>. They show a magenta colored circle at given position (relative to aircraft origin) in given size. See the last section for how to conveniently find the proper coordinates. | These are supported in <init>, <step>, and <end>. They show a magenta colored circle at given position (relative to aircraft origin) in given size. See the last section for how to conveniently find the proper coordinates. | ||
| Line 300: | Line 300: | ||
</PropertyList> | </PropertyList> | ||
====Finding marker coordinates==== | ==== Finding marker coordinates ==== | ||
If an aircraft tutorial wants to use the marker, then the aircraft animation file needs to include the marker model (see above). If this is done, then one can use the "marker-adjust" dialog to find the respective <marker> coordinates. Just type this into the "Help->Nasal Console" dialog: | If an aircraft tutorial wants to use the marker, then the aircraft animation file needs to include the marker model (see above). If this is done, then one can use the "marker-adjust" dialog to find the respective <marker> coordinates. Just type this into the "Help->Nasal Console" dialog: | ||
| Line 329: | Line 329: | ||
This just needs to be copied to the tutorial XML file. | This just needs to be copied to the tutorial XML file. | ||
===Message/audio=== | === Message/audio === | ||
Groups <step> and <end> can have one or more <message> entries, and one or more <audio> entries. If more are used of a kind, then the tutorial chooses one at random. If <audio> are available, then the contents are interpreted as file name of a *.wav sample, which is appended to the <audio-dir> path defined at the <tutorial> top level (default: "") and played by the tutorial system. Otherwise the <message> is handed over to the voice system, and synthesized to speech by the Festival speech synthesizer (if installed). In either case the chosen <message> is displayed on top of the screen. Neither <message> nor <audio> are mandatory. | Groups <step> and <end> can have one or more <message> entries, and one or more <audio> entries. If more are used of a kind, then the tutorial chooses one at random. If <audio> are available, then the contents are interpreted as file name of a *.wav sample, which is appended to the <audio-dir> path defined at the <tutorial> top level (default: "") and played by the tutorial system. Otherwise the <message> is handed over to the voice system, and synthesized to speech by the Festival speech synthesizer (if installed). In either case the chosen <message> is displayed on top of the screen. Neither <message> nor <audio> are mandatory. | ||
Because one and the same <message> string can be displayed *and* be synthesized, which can be problematic in some cases, there is a way to specify parts for either display *or* voice synthesizer: | Because one and the same <message> string can be displayed *and* be synthesized, which can be problematic in some cases, there is a way to specify parts for either display *or* voice synthesizer: "{<display part>|<voice part}". Example: | ||
<message>Press the {No1|number one} button!</message> | <message>Press the {No1|number one} button!</message> | ||
Here, "No1" would be displayed on the screen, but "number one" would be sent to the speech synthesis system. This can also be used to add invisible but audible exclamation marks: | Here, "No1" would be displayed on the screen, but "number one" would be sent to the speech synthesis system. This can also be used to add invisible but audible exclamation marks: "Press the button{|!}" | ||
===Condition=== | === Condition === | ||
These are explained in detail in $FG_ROOT/Docs/README.conditions. Here's just one example: | These are explained in detail in $FG_ROOT/Docs/README.conditions. Here's just one example: | ||