Arma 3 Scripting

Arma 3: Multi-Function Display (MFD) config reference

  • Also known as A3 MFD config reference

Topic · Markdown · JSON · original wiki page

Multi-Function Display (MFD) is implementation of HUD (Head-Up Displays) in Arma 3. Display can be fixed on helmet (move with player head) or cockpit (static position).

Technical Basics

HUDs are defined in the MFD class of the source vehicle. The properties of each HUD are separated by a root class (conventionnally named AirplaneHUD in base content), although each new instance will render a new HUD and overlap with the previous. This makes it easier to configure HUDs by modular config (for example, navigation, targeting, etc...). All HUDs are defined through 3 base elements:

Example:

class MFD
{
    class AirplaneHUD
    {
        globalProperty = ...; // global HUD properties
        // bones definitions
        class Bones
        {
            class BoneInstance
            {
                type = ...;            // type of bone
                source = ...;        // source for bone transformation
                properties = ...;    // other bone properties
            };
        };
        // HUD-Elements definitions
        class Draw
        {
            class HUDElemetInstance
            {
                type = ...;            // type of HUD-Element
                source = ...;        // source for display value
                properties = ...;    // other HUD-Elements properties
            };
        };
    };
};

Since ARMA 3 version 1.69 it is also possible to define a MFD class in CfgMagazine. This allows for the creation of dynamic MFD screens with info on the screen corresponding to current loadout applied through dynamic loadout system. See PylonIcon for more details.

Global HUD Properties

These are defined in each AirplaneHUD instance and affect every sub-sequent element. Some properties can be overwritten in each child element if needed (e.g color) :

Example:

class material
{
    ambient[]    = { 10, 10, 10, 1 };
    diffuse[]    = { 10, 10, 10, 1 };
    emissive[]    = { 40, 20, 20, 1 };
};

Bones

A bone defines the position of a graphic element's points. The modification applied by a bone can be changed by a source. Bones have no hierarchy, hierarchical geometry is available by using a Transformation Chain. A bone's type is defined by the type property in bone class (e.g.: type = fixed;).

Note

Since Arma 3 v2.20: Note, Rotational and Linear both inherit from the same base, which adds min/max/sourceScale/sourceIndex.

Btw sourceIndex is missing on linear/rotational, user sources (and others using index) can be set there too. Also 'sourceOffset' is not documented here, its also in that baseclass, look at code below for what it does. And also 'refreshRate' can be present in that base class too, also not documented here. Also refresh rate can be good for performance, because it will not re-calculate the source value if the refresh rate timer hasn't finished yet

2.20 new entry in that base (so both rot and linear) is sourceModulo

The code for the result MFD value is

float finalResult = (sourceValue * sourceScale + sourceOffset);
if (sourceModulo != 0) finalResult = fmod(finalResult, sourceModulo); // This line is new in 2.20
if (finalResult < min) finalResult = 0;
if (finalResult > max) finalResult = 1;
finalResult = (finalResult - min) * (1 / (max - min));

Default values in that base for the config values

sourceScale=1.0
sourceOffset=0.0
refreshRate=0.0
sourceIndex=-1
sourceModulo=0.0

Fixed

Fixed represents a fixed position on HUD plane. It can be use for static HUD-Elements (e.g.: aiming cross). Properties:

Linear

Linear represents a linear transformation depend on float source value. It can be used for some linear indicator (e.g.: fuel bar). Properties:

Rotational

Rotational represents a rotational transformation depend on float source value. It can be used for some rotational indicator (e.g.: analog speedometer). Properties:

Horizon

Horizon represents a transformation for a horizon indicator. Properties:

HorizonToView

HorizonToView (for HMD only) represents a transformation for a horizon indicator. Properties:

Vector

Vector represents a transformation from scene position (depend on source type) to HUD plane. Properties:

ILS

ILS represents transformation for ILS (Instrument landing system). Properties:

Limit

Limit saturates preview vector transformation by box. Properties:

HUD Elements

A HUD Element represents one graphic entity. It defines what and how will be drawn. A HUD Element's type is defined by type property in HUD Element class (e.g.: type = line;).

Line

Lines (or multi-lines - line with more segments) are defined by an array of points.

One points array can define one or more lines. Lines must be split by a separator. A separator is an empty array {}. See example below.

points[] = {
    // one-segment line
    { bone, { 0, 0 }, 1 },
    { bone, { 1, 1 }, 1 },
    {}, // line separator
    // rectangle: 4-segments multi-line
    { bone, { 0, 0 }, 1 },
    { bone, { 1, 0 }, 1 },
    { bone, { 1, 1 }, 1 },
    { bone, { 0, 1 }, 1 },
    { bone, { 0, 0 }, 1 }
};

Text

Draws the value defined as the source in text. Properties:

Polygon

Draws a polygon. Accepts 3 or 4 points only. Properties:

Warning

The drawing of pictures is quite heavy for the game engine. It is recommended to keep the number of textures to around 10-15. Above that value expect a performance impact.

class PolygonTest
{
    color[] = { 0.082, 0.408, 0.039 }; // use to define color
    class Polygon
    {
        type    = "polygon";
        texture = "a3\Data_f\Images\Mod_Base_logo_ca.paa"; // only alpha channel will be used for drawing
        points[] =
        {
            // space where texture should be drawn
            {
                { { 0, 0.1 }, 1 },
                { { 1, 0.1 }, 1 },
                { { 1, 1 }, 1 },
                { { 0, 1 }, 1 }
            }
        };
    };
};

PylonIcon

Draws the MFD definition of a pylon , defined in that pylon's contents' mfdElements definition. Properties:

class CfgMagazines
{
    //... some config ...//

    // magazines definition
    class magazine_Missile_AGM_KH25_x1 : VehicleMagazine
    {
        //... some config ...//

        // mfdElements - class where
        class mfdElements
        {
            class Plane_Fighter_02 // unique name that you can later reference in plane MFD
            {
                class Bones {};    // bones are supported
                class Draw
                {
                    class BackgroundGroup
                    {
                        color[] = { 0.0, 0.0, 0.0 };
                        // black background
                        class Background
                        {
                            type = polygon;
                            points[] =
                            {
                                {
                                    { { __EVAL(-0.015 + 0.15), __EVAL(-0.10 + 0.075) }, 1 },
                                    { { __EVAL(+0.015 + 0.15), __EVAL(-0.10 + 0.075) }, 1 },
                                    { { __EVAL(+0.015 + 0.15), __EVAL(+0.10 + 0.075) }, 1 },
                                    { { __EVAL(-0.015 + 0.15), __EVAL(+0.10 + 0.075) }, 1 }
                                };
                            };
                        };
                    };
                    class Default
                    {
                        condition    = "PylonAmmoRelative>0+PylonSelected";
                        color[]        = {0.94,0.83,0};
                        alpha        = 0.22;
                        class Shape
                        {
                            type        = line;
                            width        = 4.0;
                            points[]    =
                            {
                                // some shape
                            };
                        };
                        HUD_TEXT_STATIC(0.00 + 0.15, 0.00 + 0.01, 0.020, 0.025, center, "I", PylonText1)
                        HUD_TEXT_STATIC(0.00 + 0.15, 0.02 + 0.01, 0.020, 0.025, center, "R", PylonText2)
                    };
                    class Selected : Default
                    {
                        condition    = "(PylonSelected + PylonAmmoRelative) / 2";
                        alpha        = 1;
                        color[]        = { 0, 0.12, 0 };

                        class Shape : Shape {};
                        class PylonText1 : PylonText1 {};
                        class PylonText2 : PylonText2 {};
                    };
                    class Empty : Selected
                    {
                        condition    = "PylonAmmoRelative <= 0";
                        color[]        = { 1.0, 0.0, 0.0, 1.0 };
                        class Shape : Shape {};
                        class PylonText1 : PylonText1 {};
                        class PylonText2 : PylonText2 {};
                    };
                };
            };
            class Plane_Fighter_03 // unique name that you can later reference in plane MFD
            {
                //... some config ...//
            };
            // etc.
        };
    };
};

class CfgVehicles
{
    class Plane_Fighter_02_base_F
    {
        // ...
        class MFD
        {
            class AirplaneMFD
            {
                globalProperty = ...; // global HUD properties

                // bones definitions
                class Bones
                {
                    class Center
                    {
                        type    = fixed;
                        pos[]    = {0.52, 0.29};
                    };
                };
                class Draw
                {
                    //...
                    //...

                    condition = on;
                    class Pylon1
                    {
                        type    = "pylonicon";
                        pos[]    = { Center, { __EVAL(+0.4), 0.00 }, 1 };
                        pylon    = 1;
                        name    = "Plane_Fighter_02";    // if mfdElements exist with "Plane_Fighter_02" class,
                                                        // in config of magazine that is mounted on 1st pylonmagazine mounted on 1st pylon,
                                                        // then draw MFD which is defined here
                    };
                    class Pylon2 : Pylon1
                    {
                        pos[]    = { Center, { __EVAL(-0.4), 0.00 }, 1 };
                        pylon    = 2;
                    };
                    class Pylon3 : Pylon1
                    {
                        pos[]    = { Center, { __EVAL(+0.35), 0.47 }, 1 };
                        pylon    = 3;
                    };
                    class Pylon4 : Pylon1
                    {
                        pos[]    = { Center, { __EVAL(-0.35), 0.47}, 1 };
                        pylon    = 4;
                    };
                    class Pylon5 : Pylon1
                    {
                        pos[]    = { Center, { __EVAL(+0.18), 0.47 }, 1 };
                        pylon    = 5;
                    };
                    class Pylon6 : Pylon1
                    {
                        pos[]    = { Center, { __EVAL(-0.18), 0.47 }, 1 };
                        pylon    = 6;
                    };
                };
            };
        };
    };
};

Scale

Draws a horizontal or vertical bar indicator. A scale HUD-Element can't use bones for transformation. Properties:

Radar

Draws geometry around entities. Properties:

RadarToView

Uses the same parameters as Radar, but for a HMD.

Turret

It is uused on a Blackfoot's gunner aim box. Properties:

TurretToView

Uses the same parameters as Turret, but for a HMD. Properties:

Group

Allows for the creation of a HUD-Elements hierarchy. It can change attributes for its child elements. Group elements don't have graphics. Properties:

Sources

A source represents a value which can modify position of some types of bones (e.g.: angle of analog speedometer pointer) or value of some HUD elements (e.g.: altitude as text, heading bar direction, etc.). Currently there are 3 types of sources: Float, 3D Vector and String.

Source types are defined by the source property in a bone or HUD Element class (e.g.: source = speed;) and some may take in additional parameters as other attributes.

Float

Float sources represent a numeric value. They are is used by Linear and Rotational bones and Scale HUD-Elements.

Available values:

3D Vector

These sources represent a 3D vector value. It is used by Vector bone only.

String

These sources represent numeric values (extended float values) that are converted into a string. It is used by Text HUD Element only.

Scene To HUD Transformation

Transformation of 3D vector from scene to 2D vector on HUD plane is implemented by two 2D vectors:

Example:

class Velocity
{
    type    = vector;
    source    = velocity;
    pos0[]    = { 0.5, 0.5 }; // center of HUD for source vector
    pos10[]    = { 0.2, 0.2 }; // 20% offset for 10 degrees vector
};

Point Definition

Each point can be transformed by more bones (bones chain). A point is defined as a chain of Triplets. A triplet defines one transformation step for a point:

Triplet components:

To construct a valid triplet, there must at least one of the bone names or triplets, and the weight definition. If unnecessary, either the bone name or the offset can be omitted - just not both.

Example triplets:

points[] =
{
    { boneName, { offsetX, offsetY }, weight }, // full definition
    { { offsetX, offsetY }, weight }, // without bone
    { boneName, weight }, // without offset
    { boneName, { [boneName transform only coordinates in this group], 0, 0 }, weight }, // the same as previous one
    { 1 } // ERROR: weight only
};

Transformation Chain

Each point can be transformed by 1 or more triplet. A transformation chain is defined as an array of triplets. The transformation order is from left to right.

Example (without offsets to simplify):

points[] =
{
    { bone, 1 }, // 1 transformation
    { bone1, 1, bone2, 1 }, // 2 transformations
    { bone1, 1, bone2, 1, bone3, 1 } // 3 transformations
    // etc...
};