Users Guide to FlightGear panel configuration Version 0.5, November 8 2000 Author: John Check This document is an attempt to describe the configuration of FlightGear flight simulator's aircraft panel display via XML. The information was culled from the fgfs-devel@flightgear.org mailing list and my experiences making alternate panels. I'd like to say thanks to all the developers who make FGFS happen. Corrections and additions are encouraged. Some History: Older versions of FGFS had a hard coded display of instruments. This was a less than ideal state of affairs due to FGFS ability to use different aircraft models. Being primarily developed on UNIX type systems, a modular approach is taken towards the aircraft modeling. To date, most alternatives to the default Cessna 172 aircraft are the product of research institutions interested in the flight characteristics and not cosmetics. The result of this was that one could fly the X-15 or a Boeing 747 but be limited to C172 instrumentation. A rewrite of the panel display code was done around v0.7.5 by developer David Megginson allowing for configuration of the panel via XML to address this limitation. Using Custom Panels: The default panel location is $FG_ROOT/Aircraft/c172/Panels/Default. $FG_ROOT is the place on your filesystem where you installed FG data files. Alternate panels can be specified on the command line or set as the default in the $HOME/.fgfsrc or $FG_ROOT/preferences.xml using a property specification. The command line format is as follows: --prop:/sim/panel/path=Aircraft/c172/Panels/Default The path description shown is relative to $FG_ROOT. An absolute path may also be used for locations outside $FG_ROOT. I would recommend copying Panels/Default to Panels/Custom as a starting point for experimentation. When editing a panel configuration, pressing Shift +F3 will reload the panel. If your changes don't seem to be taking effect, check the console output. It will report the success or failure of the panel reload*. Editing textures requires restarting FGFS so the new textures can be loaded. Panel Architecture: All of the panel configuration files are XML-encoded* property lists. The root element of each file is always named . Tags are always found in pairs, with the closing tag having a slash prefixing the tag name, i.e . The top level panel configuration file is composed of a , a texture and zero or more . Instruments are used by including a <"unique_name">, a to the instruments configuration file, and placement coordinates, and optional and size specifications. Comments are bracketed with . Example Top Level Panel Config Example Panel Aircraft/c172/Panels/Textures/panel-bg.rgb Aircraft/c172/Instruments/clock.xml 110 320 72 72 The default location for instrument files is $FG_ROOT/Aircraft/c172/Instruments/. Alternate locations may be specified in the panel configuration, paths must be absolute to use files outside $FG_ROOT. About Instrument Placement: For the sake of simplicity the FGFS window is always considered to be 1024x768 so all x/y values for instrument placement should fall within these bounds. Being an OpenGL program, 0,0 represents the lower left hand corner of the screen. It is possible to place items to overlap the 3D viewport. Instrument Architecture: Instruments are defined in separate configuration files. An instrument consists of a preferred width and height, one or more stacked layers, and zero or more actions. A layer** can be a , or be of text or switch. A text layer may be static, as in a label, or generated (if it needs to be dynamic, as in an LED display), or a combination of both. A switch layer is composed of two or more nested layers and will display one of the nested layers based on a boolean property. For a simple example of a switch see $FG_ROOT/Aircraft/Custom/Instruments/brake.xml. Textures used in a switch context *must* have width and height specified to be visible. Each layer may contain zero or more transformations. A transformation is a rotation, an x-shift, or a y-shift. Transformations can be static or they can be based on properties. Static rotations are useful for flipping textures horizontally or vertically. Transformations based on properties are useful for driving instrument needles. I.E. rotate the number of degrees equal to the airspeed. X and y shifts are relative to the center of the instrument. Each specified transformation type takes an An action is a hotspot on an instrument where something will happen when the user clicks the left or center mouse button. Actions are always tied to properties: they can toggle a boolean property, adjust the value of a numeric property, or swap the values of two properties. About Transformations and Needle Placement: When describing placement of instrument needles, an transformation offset must be applied to shift the needle's fulcrum or else the needle will rotate around it's middle. The offset will be of x-shift or y-shift depending on the orientation of the needle section in the cropped texture. Offsets applied to shift the needle from the center of the instrument face must be applied *before* the transformation that describes the needle movement. About Textures: The texture files used to create the panel instruments are maximum 256x256 pixels, red/green/blue/alpha format. When calling a section of a texture file the 0,0 lower left convention is used. There is a pair of x /y coordinates defining which section of the texture to use. * If there are *any* XML parsing errors, the panel will fail to load, so it's worth downloading a parser like Expat (http://www.jclark.com/xml/) for checking your XML. FlightGear will print the location of errors, but the messages are a little cryptic right now. ** NOTE: There is one built-in layer -- for the mag compass ribbon -- and all other layers are defined in the XML files. In the future, there may also be built-in layers for special things like a weather-radar display or a GPS (though the GPS could be handled with text properties).