1 FlightGear Commands Mini-HOWTO
5 Last revised: 2003-01-20
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.
60 As of the last revision date, the following commands were available
61 from inside FlightGear; the most commonly-used ones are the commands
62 that operate on property values (FlightGear's internal state):
67 script - execute a PSL script
68 script: the PSL script to execute
70 exit - prompt and quit FlightGear
72 load - load properties from an XML file
73 file: the name of the file to load, relative to the current
74 directory (defaults to "fgfs.sav")
76 save - save properties to an XML file
77 file: the name of the file to save, relative to the current
78 directory (defaults to "fgfs.sav").
80 panel-load - (re)load the 2D instrument panel
81 path: the path of the XML panel file, relative to $FG_ROOT (defaults
82 to the value of /sim/panel/path if specified, or
83 "Panels/Default/default.xml" as a last resort.
85 panel-mouse-click - pass a mouse click to the instrument panel
86 button: the number of the mouse button (0-based)
87 is-down: true if the button is down, false if it is up
88 x-pos: the x position of the mouse click
89 y-pos: the y position of the mouse click
91 preferences-load - (re)load preferences
92 path: the file name to load preferences from, relative to $FG_ROOT.
93 Defaults to "preferences.xml".
95 view-cycle - cycle to the next viewpoint
97 screen-capture - capture the screen to a file
99 tile-cache-reload - reload the scenery tile cache
101 lighting-update - update FlightGear's lighting
103 property-toggle - swap a property value between true and false
104 property: the name of the property to toggle
106 property-assign - assign a value to a property
107 property[0]: the name of the property that will get the new value.
108 value: the new value for the property; or
109 property[1]: the name of the property holding the new value.
111 property-adjust - adjust the value of a property
112 property: the name of the property to increment or decrement
113 step: the amount of the increment or decrement (defaults to 0)
114 offset: input offset distance (used for the mouse; multiplied by
116 factor: factor for multiplying offset distance (used for the mouse;
118 min: the minimum allowed value (default: no minimum)
119 max: the maximum allowed value (default: no maximum)
120 mask: 'integer' to apply only to the left of the decimal point;
121 'decimal' to apply only to the right of the decimal point; 'all'
122 to apply to the full value (defaults to 'all')
123 wrap: true if the value should be wrapped when it passes min or max;
124 both min and max must be specified (defaults to false)
126 property-multiply - multiply the value of a property
127 property: the name of the property to multiply
128 factor: the amount by which to multiply (defaults to 1.0)
129 min: the minimum allowed value (default: no minimum)
130 max: the maximum allowed value (default: no maximum)
131 mask: 'integer' to apply only to the left of the decimal point;
132 'decimal' to apply only to the right of the decimal point; 'all'
133 to apply to the full value (defaults to 'all')
134 wrap: true if the value should be wrapped when it passes min or max;
135 both min and max must be specified (defaults to false)
137 property-swap - swap the values of two properties
138 property[0]: the name of the first property
139 property[1]: the name of the second property
141 property-scale - set the value of a property based on an axis
142 property: the name of the property to set
143 setting: the current input setting (usually a joystick axis from -1
145 offset: the offset to shift by, before applying the factor (defaults
147 factor: the factor to multiply by (use negative to reverse; defaults
150 property-cycle - cycle a property through a set of values
151 property: the name of the property to cycle
152 value[*]: all of the allowed values
154 dialog-show - show an XML-configured dialog box
155 dialog-name - the name of the dialog to show
157 dialog-close - close the active dialog box
159 dialog-update - copy values from FlightGear to the active dialog box
160 object-name: the name of the GUI object to update (defaults to all
163 dialog-apply - copy values from the active dialog box to FlightGear
164 object-name: the name of the GUI object to apply (defaults to all
167 presets-commit - commit preset values from /sim/presets
170 The following commands are temporary, and will soon disappear or be
171 renamed; do NOT rely on them:
173 old-save-dialog - offer to save a flight
175 old-load-dialog - offer to load a flight
177 old-reinit-dialog - offer to reinit FlightGear
179 old-hires-snapshot-dialog - save a hires screen shot
181 old-snapshot-dialog - save a screenshot
183 old-print-dialog - print the screen (Windows only)
185 old-pilot-offset-dialog - set pilot offsets graphically
187 old-hud-alpha-dialog - set the alpha value for the HUD
189 old-properties-dialog - display the property browser
191 old-preset-airport-dialog - set the default airport
193 old-preset-runway-dialog - set the default runway
195 old-preset-offset-distance-dialog - set the default offset distance
197 old-preset-altitude-dialog - set the default altitude
199 old-preset-glidescope-dialog - set the default glidescope
201 old-preset-airspeed-dialog - set the default airspeed
203 old-preset-commit-dialog - commit preset values
205 old-ap-add-waypoint-dialog - add a waypoint to the current route
207 old-ap-pop-waypoint-dialog - remove a waypoint from the current route
209 old-ap-clear-dialog - clear the current route
211 old-ap-adjust-dialog - adjust the autopilot settings
213 old-lat-lon-format-dialog - toggle the lat/lon format in the HUD
215 old-help-dialog - offer online help
218 Adding New Commands in C++
219 --------------------------
222 To add a new command to FlightGear, you first need to create a
223 function that takes a single SGPropertyNode const pointer as an
227 do_something (SGPropertyNode * arg)
232 Next, you need to register it with the command manager:
234 globals->get_commands()->addCommand("something", do_something);
236 Now, the command "something" is available to any mouse, joystick,
237 panel, or keyboard bindings. If the bindings pass any arguments, they
238 will be children of the SGPropertyNode passed in:
241 do_something (const SGPropertyNode * arg)
243 something(arg->getStringValue("foo"), arg->getDoubleValue("bar"));
246 That's pretty-much it. Apologies in advance for not making things any