Generic Instruments

Generic instruments are a version 9 aircraft feature: basically they are instruments on the 2-d panel that are configured based on custom parameters, artwork and datarefs.

Unlike regular instruments, each generic instrument:
 * Can be driven off of any dataref available, including plugin datarefs.
 * Can use any PNG file for its image.
 * Can have any of its parameters independently modified.

Generic instruments are designed to give you more flexibility in creating 2-d panels.

Note: the generic instrument system is getting a major enhancement with X-Plane 920; features specific to 920 are marked [920]; features that are replaced with something newer are marked [legacy].

All legacy features are transparently mapped to 920 features when an aircraft is loaded.

Adding Generic Instruments to a panel
The generic instruments live in the "Generic" folder in the main instrument list in PlaneMaker. There are only 12 generic instruments; each type represents a different "mechanism" (e.g. needle vs. handle).

When a generic instrument is dragged onto the panel, it will attempt to preview its animation.

Properties Common to All Generic Instruments
All of the generic instruments have some common properties:

PNG file
All generic instruments reference a PNG image file. While there are default image files that will be used if the PNG file is blank, you should not use the default images. If you are going to use generic instruments, always provide your own artwork!

(The generic instruments are provided only to be place-holders so that you can see the new instrument in the editor in Plane-Maker before you pick your own instruments. These defaults may change in the future, breaking your panel.  Use your own images, which will not change!!  The purpose of generic instruments is customization, not easy creation; if you do not want to make your own artwork, you should use the hundreds of premade instruments!!)

Image files must be contained within the "generic" subfolder of the "cockpit" folder of your aircraft! You can build sub-folders within the generic folder. The cockpit folder goes in the aircraft folder - ie F:\X-Plane 9\Aircraft\Helicopters\SH-60B\cockpit\generic

Click on the PNG button to pick new artwork. The layering convertions (-1, -2, etc.) apply to generic instruments; how the layers are used depends on the instrument type.

Changing the PNG file will change the real-time preview.

Note: if you are using a 3-d cockpit panel (see 3D_Panel) then the cockpit_3d/generic folder will be used as an image source first.

Dataref/Command
All generic instruments are driven by a main dataref, which defines where the input values come from that move the instrument. There is one exception: the trigger generic instrument uses a command rather than a dataref.

In all cases, the instrument has some mechanism to scale the value of the dataref for display.

You should try to use the datarefs in sim/cockpit2/ for generic instruments, since these datarefs are designed for in-cockpit use. Generally:
 * sim/cockpit2 are in-cockpit INDICATIONS - they will show the wrong values when there is a systems failure. For example, the airspeed in sim/cockpit2 will go to zero as the pitot tube ices up.
 * sim/flightmodel2 are the real physics-simulation values - they are correct always, and thus are good for modeling the external plane. For example, the AoA in sim/flightmodel2 will always show the real AoA no matter what electrical and vacuum systems fail - this would be appropriate for the AoA sensor mechanism on the outside of the plane.
 * both sim/cockpit2 and sim/flightmodel2 work correctly for any plane (the user's or multi-player)...that is, the sim/flightmodel2 datarefs will show the values for the AI/multiplayer planes when read from an object attached to an ACF loaded as an AI/multiplayer plane.
 * The older sim/cockpit and sim/flightmodel datarefs are not carefully divided into cockpit (with failures) vs. physics (no failures), and always show the user's plane, even when your OBJ is attached to another plane. So it is best to use sim/cockpit2 for generic instruments and sim/flightmodel2/ everywhere else.

Note: a lot of systems are currently missing; X-Plane 9.1 will ad a lot more sim/cockpit2/ datarefs.

If you pick a dataref that is an array, an "index" field will appear in the instrument editor. This is how, for example, you pick which engine an N1 instrument listens to. (The N1 dataref is an array, with one item in the array for each element.) You do not type [0] into the dataref name in PlaneMaker.

Electrical Power [Legacy]
If this is checked, the instrument will only appear/function if one of the electrical system busses has power. In X-Plane 920 instruments with this checked are mapped to glass lighting mode and "any" for the electrical bus.

Avionics Power [Legacy]
If this is checked, the instrument will only appear/function if the avionics bus has power. In X-Plane 920 instruments with this checked are mapped to glass lighting mode and "any+avionics" for the electrical bus.

Visibility Filters
The three "needs" fields let you apply optional rules to hide the instrument. You specify a dataref and a value - if any of the rules is utilized in the editor but the rule is not true (e.g. the rule is sim/hud_power needs to be 1, but sim/hud_power is not 1) then the generic instrument will disappear.

This system has a few potential uses:


 * You can use the needs == rule to tie the visibility of your instrument to a plugin-created dataref.
 * You can hide instruments depending on things like the EFIS or EICAS mode switches.
 * You can hide instruments in certain flight conditions.

Clipping [920]
In X-Plane 920, any instrument can have "clipping" enabled, which limits drawing of an intrument's overlays to within the bounds of the instrument background. See Generic Instrument Tips for uses.

Skewing [920]
In X-Plane 920, any generic instrument can be "skewed" - that is, you can drag the corners of the instrument to change its shape to a trapezoid or quadrilateral. The distortion applied to the instrument will be perspective-correct, and is meant to align moving parts on overhead panels.

Skewing does interact with overlays/moving parts and clipping. Skewing does not affect burned-in backgrounds or hot-spots. Skewing is not recommended for instruments that can be dragged.

Lighting Mode [920]
In X-Plane 920 generic instruments can have one of four lighting modes, which affect how instrument overlays are drawn. (The background is simply burned in.)


 * Mechanical: the instrument is lit by the flood and spot lights. The instrument is always drawn (albeit very dark if it is night and there is no power.)
 * Back-Lit: the instrument's regular texture is lit by the flood and spots. The _LIT texture is added to it, regulated by the lighting knob if there is power.
 * Glass: the instrument is lit by the appropriate instrument-lighting knob. The instrument disappears if there is no power.
 * Glass (Translucent): [New to 930] same as glass, but when the instrument is dimmed, it fades to transparency, not to black. See Generic Instrument Tips for more info.

For glass and mechanical instruments, at night with power the _LIT overlay texture is swapped in for the regular overlay texture. For back-lit instruments, the _LIT texture is added to the daytime texture.

In X-Plane 930, non-generic instruments can have one of two lighting modes, which affect how instrument "overlays" are drawn:
 * Replacement: the LIT texture is used instead of the regular texture at night. This is the default and matches legacy behavior.
 * Additive: the LIT texture is added to the regular texture. This is the same as "back-lit" for generic instruments.

Note: swapping of the _LIT overlay to replace the regular texture (glass, mechanical) is a legacy behavior and is not recommended if your panel uses the new spot lighting system. See 2D Panel Lighting.

Lighting Knob [920]
Glass and back-lit generic instruments listen to one of the instrument brightness knobs to specify their lighting. This property specifies which knob. You can use a knob of -1 to have a lit instrument that is always on.

See 2D Panel Lighting.

Power Source [920]
This defines what power source the instrument draws from. A power failure will cut off instrument lighting, but will not necessarily fail the instrument itself. (For examlpe, a vacuum-driven dataref should not be affected by an electrical failure. The choices are:
 * None - the instrument does not require power.
 * Left Bus - the instrument gets power from the left bus.
 * Right Bus - the instrument gets power from the right bus.
 * Any - the instrument can get power from either the left or right bus.
 * Avionics Master Switch + Left Bus - the instrument gets power from the left bus, but only when the avionics master switch is on.
 * Avionics Master Switch + Right Bus - the instrument gets power from the right bus, but only when the avionics master switch is on.
 * Avionics Master Switch + Any - the instrument gets power from either bus, but only when the avionics master switch is on.

Bus Selectors [940]
X-Plane 940 replaces power source with specific bus selectors - for each bus defined in the airplane, a check-box lets you attach power to the instrument; the instrument will power if any selected bus is powered. An additional avionics check box will require the avionics master to be on to receive power.

These check-boxes are automatically forward converted from 920/30 with left bus = 1 and right bus = 2.

Note: if you have an illegal bus setting (e.g. you check bus 3 only, then turn the number of buses down to 2, then save the plane) X-Plane will attempt to reassign your instrument to a valid bus to provide power. But this is generally not recommended.

Instruments that have no buses selected act self-powered, e.g. they bypass the power requirement.

Tool Tip
You can optionally specify a help tip for each instrument. If the tool tip is not empty, it will be shown when the user picks "Show Instrument Descriptions." If the instrument is not generic and you do not provide a help tip, the default tiop will be used.

Comment
The comment field on instruments is meant for your use as an author while working - it is not shown to users; it is just a scratch pad.

Properties for Non-Generic Instruments
Non-generic instruments still have a few editable properties:


 * Name
 * Help Tip
 * Comment
 * Lighting rheostat number
 * Lighting Mode (limited to "additive" and "replacement" lighting).

The lighting rheostat is only used if the non-generic instrument has glass elements; Plane-Maker does not hide this field for non-glass non-generic instruments.

Properties for Groups [930 and newer]
Starting with X-Plane 930, groups have the "visibility filter" properties - a group can be made to hide. When a group hides, all sub-groups inside the group and all instruments inside the group are also hidden.

Key Frames [920]
Starting with X-Plane 920, the ad-hoc methods of specifying generic instrument output is specified with a unified key frame table. The key frame table defines a series of mappings from input to output values, with a "power curve" (1.0 = linear) to further alter behavior.
 * All instruments must have at least two key frames. The maximum number of key frames is ten.
 * Values outside the key frame are extrapolated. (See Generic Instrument Tips.)
 * Key frame tables can be in ascending or descending order.

A range of key frame input values cannot implicitly define a value more than once unless the generic instrument type is "rotary". (So for example, input values of 0, 75, 50, 100 is illegal for the input of "N1 percent" because the value 55 can be found by interpolating between 0..75 and between 75..50 and between 50..100!)

A range of key frame output values cannot implicitly define a value more than once if the generic instrument "writes" its dataref (e.g. handles, rheostats) unless it is a "rotary".

[940]: X-Plane 940 lets you set the key frames to wrap at the bottom or top of their range. When this happens, dataref values outside the range will wrap around. Note that wrap-around key frames may not work well for reverse-key framing (e.g. setting a value via dragging).

Specific Generic Instruments
A general note on proportions: in many cases, the scaling of the instruments work by proprotions, e.g. at this dataref value, show the needle at this angle.

In a few cases, where a straight numeric result must be computed, an offset and multiplier are provided for the dataref. The ratio is multiplied by the dataref before the offset is added.

Annunciators (gen_annun)
The annunciator is actually a special-case instrument in that it doesn't use a dataref at all. Basically if the conditions are met, the upper image in the png file is used, otherwise the lower ones are used. (It is designed this way so you can create logic like "fuel flow too low" or "engine temp too high" or "gear is down".)

Tip: you can also simulate annunciators using the rotary instrument - see Generic Instrument Tips.

Handles (gen_handle)
Handles are used for draggable controls like engines. Key frames map from the input dataref to vertical pixel offsets (from the center of the instrument).
 * Click radius defines how wide the hot spot for clicking is.
 * If "detents" is enabled, the handle will be a bit sticky at the exact values specified in the key frame table. This lets you make a handle that tends to stay in certain positions, like a flap handle on airliners.

LEDs (gen_LED)
The LED dataref provides an LED-style numeric display of a dataref. The key frame table converts from the dataref to the numbers displayed.
 * Digits and Decimals controls the formatting of numeric input. Note that the PNG file must be fixed at 6 digits even if "digits" is less than 6.
 * XP930: you can specify the width of the "period" digit in pixels - specify 0 to keep the period the same as all other digits.
 * XP930: you can specify the number of rows in the texture. The default of 0 will use the old six-row layout.

BUG in x-plane 921: if you specify mechanical lighting on gen_LED, the digits will not appear in a 3-d cockpit that uses ATTR_cockpit_region. This will be fixed in 930. However, most gen_LEDS should be using glass-style lighting anyway!!

Needles (gen_needle)
The needle provides a steam-gauge-style instrument and are also capable of creating heading bugs. The key frame table maps from the input value to degrees.
 * Offset moves the needle away from the center by a certain number of pixels. This can be used to place a heading bug at the rim of the instrument or to position the needle on only one side of the instrument (without using transparency).
 * If "is-draggable" is enabled, the user can drag the needle to change the dataref value. Use this for mechanical heading bugs.
 * If is-draggable is enabled, then "click-radius" defines the hot-spot size. The hot spot is centered around the needle, with the offset taken into account.
 * [XP940] X-Plane 940 introduces an X and Y rotation offset that let you rotate the needle around a location other than the center of the instrument.

Pies (gen_pie)
The pie instrument creates a digital pie-style instrument, like you might see in an EICAS. The key frame table maps from dataref inputs to degrees. The lowest key frame defines the start point of the pie. Note that the properties for turning yellow and red are defined in dataref units, not degrees.
 * If the pie dataref goes below the "low yellow" value the pie turns yellow.
 * If the pie dataref goes below the "low red" value the pie turns red.
 * If the pie dataref goes above the "high yellow" value the pie turns yellow.
 * If the pie dataref goes above the "high red" value the pie turns red.
 * The radius defines the pie size in pixels.
 * (New to 930:) an offset, to make the pie into a "ring" arc instead of a "pie" arc.

So for example, for N1 you might do this: Low red: 0 Low yellow: 0 High Yellow: 0.9 High Red: 1.0

Thus for an N1 (from 0 to 1.0) the low-end red/yellow zones are not used.

BUG: in XP901 the pie instrument's brightness follows the flood light, not the instrument brightness.

Pointers (gen_pointer) [920]
A pointer moves its overlay image either left-right or up-down. The key frame table maps from the dataref to an offset in pixels from the center of the instrument.
 * If the orientation is vertical, the pointer moves up-down with the dataref, otherwise it moves left-right.
 * The offset parameter is a fixed offset in the direction that is perpendicular to the way the pointer moves.
 * If "draggable" is true, the user can drag the pointer (like a bug) to set the dataref.
 * If draggable is true, the "click radius" defines the hot spot size.

Radio Frequences (gen_radiofreq)
The radio frequency rheostat increments or decrements a radio frequency dataref. The key frame table should be set to "linear" (e.g. mapping 0->0 and 1->1).
 * The radio type defines the type of frequency that will be controlled and the editing mode. The rheostat will set the correct values (in hz) for the type of radio (E.g. wrapping around from 110 to 118.0 for a NAV radio).
 * For transponders and 1-ring ADFs, the "digits" field defines which one digit the rheostat will edit.
 * Click radius defines the hot-spot size.
 * The hot spot can be offset horizontally or vertically.

When you pick COM1 or NAV1, the rheostat automatically has an inner and outer ring. When you pick ADF 3-Ring (new in 920) the rheostat automatically has 3 rings.

Rheostats (gen_rheostat)
The rheostat turns a dataref up and down, and optionally shows a rotating overlay. The key frame table maps from the dataref to degrees (to rotate the overlay).

The rheostat's range is limited by the low and high key frames in the key frame table.
 * Click step defines how much the rheostat changes when the mouse is clicked once. This is in the output units, not dataref units.
 * Hold step defines how much the rheostat changes when the mouse is held down for one second. This is in the output units, not dataref units.
 * Click radius defines the size of the hot spot.
 * The "wraps" option will cause the underlying dataref to go to its lowest value once it goes past its highest value (and vice versa). For example, a heading bug rheostat would use this to make the bug "wrap" from 360 back to 0 degrees.
 * Hole radius defines a hole in the hot spot where you cannot click.
 * The hot spot can be offset horizontally or vertically.
 * Custom cursor lets you provide a custom cursor choice.

A note on units: if you do not use an overlay, you can set the key frame table to map linearly (e.g. 0->0, 1->1). In this case the click step and hold step would be in dataref units. But if you use an overlay, you'll want to use degrees as the output of the key frame table - thus the click step is how many degrees to turn the knob per click.

One-way rheostats (gen_rheostat_one_way)
The one-way rheostat is like the normal rheostat except that the control can only be incremented. The one-way rheostat cannot have an overlay.
 * Click step defines how much the rheostat changes when the mouse is clicked once. This is in the output units, not dataref units.
 * Hold step defines how much the rheostat changes when the mouse is held down for one second. This is in the output units, not dataref units.
 * Click radius defines the size of the hot spot.
 * Hole radius defines a hole in the hot spot where you cannot click.
 * The hot spot can be offset horizontally or vertically.
 * Custom cursor lets you provide a custom cursor choice.

Generally you would utilize "one-way rheostats" in pairs...that is, two separate instruments, one which increments and one which decrements a given dataref.

Rolling Counters (gen_rolling)
The rolling counter shows a dataref's value numerically - the key frame table maps from the dataref to the numbers displayed.
 * In 920 the digits parameter determines how many digits the rolling tape is split into. In 902 this was ignored and six digits were always used.

Rotary knobs (gen_rotary)
A rotary knob increases or decreases an integral dataref from 0 through a number of sections. The key frame table maps from the dataref to the animation phase you want to show. Phases larger than the number of digits wrap around to the beginning; phases smaller than zero cause the rotary knob to disappear. All clicks work in one output unit of the key frame table.

Positions defines the number of drawing phases in the rotary. Note that for rotaries that do not wrap, the clamped values are based on the key frame table, not the digits.

Rotary Type defines the way the mouse interacts with the rotary switch. The types are:
 * Rotary: hot spots surround the rotary to provide X-Plane's standard clickable-rotary interface. Each click change the value by one with clamping.
 * Left-Right: clicks to the right side of the rotary increase the value, clicks to the left side decrease, with clicks clamped to the extent of the key frame table.
 * Up-Down: clicks to the top of the rotary increase the value, clicks to the bottom decrease, with clicks clamped to the extent of the key frame table.
 * Push-Button: each click increases the value by one, wrapping around when the maximum is reached.
 * Momentary: clicking down sets the maximum key frame value, releasing sets the minimum key frame value.
 * No-Click: clicking does nothing. Use this type of rotary as a display.
 * Rheostat: holding down the mouse moves the rotary continuously like a rheostat. When this is selected, you must pick click and hold increment values.
 * Radio Button [New to 930]: holding down the mouse sets the highest key frame value, releasing does nothing. This is useful for creating a series of rotaries where a click to each one sets a dataref to a certain absolute value.)

The rotary is the only generic instrument that reads and writes its dataref and can handle a key frame table with gaps.

You can also customize:
 * The custom cursor property, which lets you override the default cursor.
 * The radius of the hot spot.
 * The radius of a hole inside the hot spot that does not react to the mouse.
 * The hot spot can be offset horizontally or vertically.

See Generic Instrument Tips for more tips on the rotary.

Tapes (gen_tape)
The tape display shows a linear tape graphic - the key frame table maps from the dataref to a pixel offset from the instrument center. The tape starts at the position specified by the lowest key frame.

Text (gen_text) [920]
The text display shows a "byte array" (or "data") dataref as a human readable text string. The key frame table is ignored. This only works for byte-array type datarefs! use the LED instrument for numeric datarefs.
 * The X and Y offsets are pixel offsets to position text drawing relative to the instrument.

Note: as of 921 there are almost no datarefs built into X-plane that are compatible with the text instrument - this will change in future versions of X-Plane; in the meantime plugins can use this instrument type to make text displays.

Triggers (gen_trigger)
The trigger instrument makes a clickable region that invokes a command. Instead of a dataref, a sim command is specified. The key frame table is ignored. The generic trigger has a two-state bitmap, toggling between the two images as it is pressed.
 * The click radius defines the size of the hot spot.
 * The custom cursor property lets you override the default cursor.
 * The hot spot can be offset horizontally or vertically.

Put the two position images of the switch in one .png side by side - same size for each. Call the file something like switch-1.png. It may look ugly in the planemaker, but it shows up nicely in X-Plane itself. Click on the switch in X-Plane and it will toggle the two images.