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 loadxml - load XML file into property tree
81 filename: the path & filename of the file to load
82 targetnode: the target node within the property tree where to store the XML
85 savexml - save property tree node to XML file
86 filename: the path & filename for the file to be saved
87 sourcenode: the source node within the property tree where the XML file's
88 structure is assembled from.
90 panel-load - (re)load the 2D instrument panel
91 path: the path of the XML panel file, relative to $FG_ROOT (defaults
92 to the value of /sim/panel/path if specified, or
93 "Panels/Default/default.xml" as a last resort.
95 panel-mouse-click - pass a mouse click to the instrument panel
96 button: the number of the mouse button (0-based)
97 is-down: true if the button is down, false if it is up
98 x-pos: the x position of the mouse click
99 y-pos: the y position of the mouse click
101 preferences-load - (re)load preferences
102 path: the file name to load preferences from, relative to $FG_ROOT.
103 Defaults to "preferences.xml".
105 view-cycle - cycle to the next viewpoint
107 screen-capture - capture the screen to a file
109 tile-cache-reload - reload the scenery tile cache
111 lighting-update - update FlightGear's lighting
113 property-toggle - swap a property value between true and false
114 property: the name of the property to toggle
116 property-assign - assign a value to a property
117 property[0]: the name of the property that will get the new value.
118 value: the new value for the property; or
119 property[1]: the name of the property holding the new value.
121 property-adjust - adjust the value of a property
122 property: the name of the property to increment or decrement
123 step: the amount of the increment or decrement (defaults to 0)
124 offset: input offset distance (used for the mouse; multiplied by
126 factor: factor for multiplying offset distance (used for the mouse;
128 min: the minimum allowed value (default: no minimum)
129 max: the maximum allowed value (default: no maximum)
130 mask: 'integer' to apply only to the left of the decimal point;
131 'decimal' to apply only to the right of the decimal point; 'all'
132 to apply to the full value (defaults to 'all')
133 wrap: true if the value should be wrapped when it passes min or max;
134 both min and max must be specified (defaults to false)
136 property-multiply - multiply the value of a property
137 property: the name of the property to multiply
138 factor: the amount by which to multiply (defaults to 1.0)
139 min: the minimum allowed value (default: no minimum)
140 max: the maximum allowed value (default: no maximum)
141 mask: 'integer' to apply only to the left of the decimal point;
142 'decimal' to apply only to the right of the decimal point; 'all'
143 to apply to the full value (defaults to 'all')
144 wrap: true if the value should be wrapped when it passes min or max;
145 both min and max must be specified (defaults to false)
147 property-swap - swap the values of two properties
148 property[0]: the name of the first property
149 property[1]: the name of the second property
151 property-scale - set the value of a property based on an axis
152 property: the name of the property to set
153 setting: the current input setting (usually a joystick axis from -1
155 offset: the offset to shift by, before applying the factor (defaults
157 factor: the factor to multiply by (use negative to reverse; defaults
160 property-cycle - cycle a property through a set of values
161 property: the name of the property to cycle
162 value[*]: all of the allowed values
164 dialog-show - show an XML-configured dialog box
165 dialog-name - the name of the dialog to show
167 dialog-close - close the active dialog box
169 dialog-update - copy values from FlightGear to the active dialog box
170 object-name: the name of the GUI object to update (defaults to all
173 dialog-apply - copy values from the active dialog box to FlightGear
174 object-name: the name of the GUI object to apply (defaults to all
177 presets-commit - commit preset values from /sim/presets
180 The following commands are temporary, and will soon disappear or be
181 renamed; do NOT rely on them:
183 old-save-dialog - offer to save a flight
185 old-load-dialog - offer to load a flight
187 old-reinit-dialog - offer to reinit FlightGear
189 old-hires-snapshot-dialog - save a hires screen shot
191 old-snapshot-dialog - save a screenshot
193 old-print-dialog - print the screen (Windows only)
195 old-pilot-offset-dialog - set pilot offsets graphically
197 old-hud-alpha-dialog - set the alpha value for the HUD
199 old-properties-dialog - display the property browser
201 old-preset-airport-dialog - set the default airport
203 old-preset-runway-dialog - set the default runway
205 old-preset-offset-distance-dialog - set the default offset distance
207 old-preset-altitude-dialog - set the default altitude
209 old-preset-glidescope-dialog - set the default glidescope
211 old-preset-airspeed-dialog - set the default airspeed
213 old-preset-commit-dialog - commit preset values
215 old-ap-add-waypoint-dialog - add a waypoint to the current route
217 old-ap-pop-waypoint-dialog - remove a waypoint from the current route
219 old-ap-clear-dialog - clear the current route
221 old-ap-adjust-dialog - adjust the autopilot settings
223 old-lat-lon-format-dialog - toggle the lat/lon format in the HUD
225 old-help-dialog - offer online help
228 Adding New Commands in C++
229 --------------------------
232 To add a new command to FlightGear, you first need to create a
233 function that takes a single SGPropertyNode const pointer as an
237 do_something (SGPropertyNode * arg)
242 Next, you need to register it with the command manager:
244 globals->get_commands()->addCommand("something", do_something);
246 Now, the command "something" is available to any mouse, joystick,
247 panel, or keyboard bindings. If the bindings pass any arguments, they
248 will be children of the SGPropertyNode passed in:
251 do_something (const SGPropertyNode * arg)
253 something(arg->getStringValue("foo"), arg->getDoubleValue("bar"));
256 That's pretty-much it. Apologies in advance for not making things any