1 FlightGear Commands Mini-HOWTO
5 Last revised: 2007-12-01
8 In FlightGear, a *command* represents an action, while a *property*
9 represents a state. The trigger for a command can be any kind of user
10 input, including the keyboard, mouse, joystick, GUI, instrument panel,
11 or a remote network client.
14 XML Command Binding Markup
15 --------------------------
17 Most of the command-binding in FlightGear is handled through static
18 XML configuration files such as $FG_ROOT/keyboard.xml for the
19 keyboard, $FG_ROOT/mice.xml for the mouse, and
20 $FG_ROOT/gui/menubar.xml for the menubar. In all of these files, you
21 reference a command through a binding. This binding advances the
22 first throttle by 1%, up to a maximum value of 1.0:
25 <command>property-adjust</command>
26 <property>/controls/throttle[0]</property>
27 <step type="double">0.01</step>
31 A command binding always consists of the XML 'binding' element, with
32 one subelement named 'command' containing the command name (such as
33 'property-adjust'). All other subelements are named parameters to the
34 command: in this case, the parameters are 'property', 'step', and
35 'max'. Here is a simpler binding, with no parameters:
38 <command>exit</command>
41 Bindings always appear inside some other kind of markup, depending on
42 the input type. For example, here is the binding from keyboard.xml
43 that links the ESC key to the 'exit' command:
47 <desc>Prompt and quit FlightGear.</desc>
49 <command>exit</command>
53 Usually, more than one binding is allowed for a single input trigger,
54 and bindings are executed in order from first to last. Bindings support
55 conditions (see README.conditions):
63 <property>/devices/status/mice/mouse/button[0]</property>
65 <command>nasal</command>
66 <script>print("mouse button 0 pressed")</script>
70 Keyboard definitions can embed bindings in tags <mod-up> (key released),
71 <mod-shift>, <mod-ctrl>, <mod-alt>, <mod-meta>, <mod-super>, and <mod-hyper>.
72 Nesting is supported. Meta, Super, and Hyper modifier tags are for local
73 use only, and must be supported by the operating system to work.
79 <command>nasal</command>
80 <script>print("q pressed")</script>
85 <command>nasal</command>
86 <script>print("Alt-q pressed")</script>
91 <command>nasal</command>
92 <script>print("Alt-Super-q pressed")</script>
97 <command>nasal</command>
98 <script>print("Alt-Super-Meta-q pressed")</script>
111 As of the last revision date, the following commands were available
112 from inside FlightGear; the most commonly-used ones are the commands
113 that operate on property values (FlightGear's internal state):
118 script - execute a PSL script
119 script: the PSL script to execute
121 exit - prompt and quit FlightGear
123 load - load properties from an XML file
124 file: the name of the file to load, relative to the current
125 directory (defaults to "fgfs.sav")
127 save - save properties to an XML file
128 file: the name of the file to save, relative to the current
129 directory (defaults to "fgfs.sav").
131 loadxml - load XML file into property tree
132 filename: the path & filename of the file to load
133 targetnode: the target node within the property tree where to store the XML
134 file's structure. If targetnode isn't defined, then the data will be stored
135 in a node "data" under the argument branch.
137 savexml - save property tree node to XML file
138 filename: the path & filename for the file to be saved
139 sourcenode: the source node within the property tree where the XML file's
140 structure is assembled from. If sourcenode isn't defined, then savexml will
141 try to save data stored in a node "data" in the argument branch.
143 panel-load - (re)load the 2D instrument panel
144 path: the path of the XML panel file, relative to $FG_ROOT (defaults
145 to the value of /sim/panel/path if specified, or
146 "Panels/Default/default.xml" as a last resort.
148 panel-mouse-click - pass a mouse click to the instrument panel
149 button: the number of the mouse button (0-based)
150 is-down: true if the button is down, false if it is up
151 x-pos: the x position of the mouse click
152 y-pos: the y position of the mouse click
154 preferences-load - (re)load preferences
155 path: the file name to load preferences from, relative to $FG_ROOT.
156 Defaults to "preferences.xml".
158 view-cycle - cycle to the next viewpoint
160 screen-capture - capture the screen to a file
162 tile-cache-reload - reload the scenery tile cache
164 lighting-update - update FlightGear's lighting
166 property-toggle - swap a property value between true and false
167 property: the name of the property to toggle
169 property-assign - assign a value to a property
170 property[0]: the name of the property that will get the new value.
171 value: the new value for the property; or
172 property[1]: the name of the property holding the new value.
174 property-adjust - adjust the value of a property
175 property: the name of the property to increment or decrement
176 step: the amount of the increment or decrement (defaults to 0)
177 offset: input offset distance (used for the mouse; multiplied by
179 factor: factor for multiplying offset distance (used for the mouse;
181 min: the minimum allowed value (default: no minimum)
182 max: the maximum allowed value (default: no maximum)
183 mask: 'integer' to apply only to the left of the decimal point;
184 'decimal' to apply only to the right of the decimal point; 'all'
185 to apply to the full value (defaults to 'all')
186 wrap: true if the value should be wrapped when it passes min or max;
187 both min and max must be specified (defaults to false)
189 property-multiply - multiply the value of a property
190 property: the name of the property to multiply
191 factor: the amount by which to multiply (defaults to 1.0)
192 min: the minimum allowed value (default: no minimum)
193 max: the maximum allowed value (default: no maximum)
194 mask: 'integer' to apply only to the left of the decimal point;
195 'decimal' to apply only to the right of the decimal point; 'all'
196 to apply to the full value (defaults to 'all')
197 wrap: true if the value should be wrapped when it passes min or max;
198 both min and max must be specified (defaults to false)
200 property-swap - swap the values of two properties
201 property[0]: the name of the first property
202 property[1]: the name of the second property
204 property-scale - set the value of a property based on an axis
205 property: the name of the property to set
206 setting: the current input setting (usually a joystick axis from -1
208 offset: the offset to shift by, before applying the factor (defaults
210 factor: the factor to multiply by (use negative to reverse; defaults
212 squared: if true will square the resulting value (same as power=2)
213 power: the resulting value will be taken to the power of this integer
214 value (overrides squared; default=1)
216 property-cycle - cycle a property through a set of values
217 property: the name of the property to cycle
218 value[*]: all of the allowed values
220 dialog-new - create new dialog from the argument branch
222 dialog-show - show an XML-configured dialog box
223 dialog-name - the name of the dialog to show
225 dialog-close - close the active dialog box
227 dialog-update - copy values from FlightGear to the active dialog box
228 object-name: the name of the GUI object to update (defaults to all
231 dialog-apply - copy values from the active dialog box to FlightGear
232 object-name: the name of the GUI object to apply (defaults to all
235 presets-commit - commit preset values from /sim/presets
238 The following commands are temporary, and will soon disappear or be
239 renamed; do NOT rely on them:
241 old-save-dialog - offer to save a flight
243 old-load-dialog - offer to load a flight
245 old-reinit-dialog - offer to reinit FlightGear
247 old-hires-snapshot-dialog - save a hires screen shot
249 old-snapshot-dialog - save a screenshot
251 old-print-dialog - print the screen (Windows only)
253 old-pilot-offset-dialog - set pilot offsets graphically
255 old-hud-alpha-dialog - set the alpha value for the HUD
257 old-properties-dialog - display the property browser
259 old-preset-airport-dialog - set the default airport
261 old-preset-runway-dialog - set the default runway
263 old-preset-offset-distance-dialog - set the default offset distance
265 old-preset-altitude-dialog - set the default altitude
267 old-preset-glidescope-dialog - set the default glidescope
269 old-preset-airspeed-dialog - set the default airspeed
271 old-preset-commit-dialog - commit preset values
273 old-ap-add-waypoint-dialog - add a waypoint to the current route
275 old-ap-pop-waypoint-dialog - remove a waypoint from the current route
277 old-ap-clear-dialog - clear the current route
279 old-ap-adjust-dialog - adjust the autopilot settings
281 old-lat-lon-format-dialog - toggle the lat/lon format in the HUD
283 old-help-dialog - offer online help
286 Adding New Commands in C++
287 --------------------------
290 To add a new command to FlightGear, you first need to create a
291 function that takes a single SGPropertyNode const pointer as an
295 do_something (SGPropertyNode * arg)
300 Next, you need to register it with the command manager:
302 globals->get_commands()->addCommand("something", do_something);
304 Now, the command "something" is available to any mouse, joystick,
305 panel, or keyboard bindings. If the bindings pass any arguments, they
306 will be children of the SGPropertyNode passed in:
309 do_something (const SGPropertyNode * arg)
311 something(arg->getStringValue("foo"), arg->getDoubleValue("bar"));
314 That's pretty-much it. Apologies in advance for not making things any