LIVERY XML PROPERTIES

The livery.xml file goes in the model.[tag] folder beside the *.glTF and *.bin files for an aircraft livery and should be formatted as follows:

<?xml version="1.0" encoding="UTF-8"?>
<ModelInfo version="1.0" guid="<!-- GUID HERE -->">
    <LODS>
        <!-- LOD DATA HERE -->
    </LODS>
    <DynamicMaterial>
        <!-- Material Data Here -->
    <DynamicMaterial>
    <DynamicMaterial>
        <!-- Material Data Here -->
    <DynamicMaterial>
    <!-- Further Dynamic Materials As Required -->
</ModelInfo>

 

For an explanation of how this file will be added to the base aircraft files at the time of the modular merge, please see here:

• Merge Process For Liveries

 

For examples of how this file is setup, please see here:

• Livery XML Examples

 

For an explanation of how to set up your liveries so that they work with the adaptive elements that dynamic materials generate, please see here:

• Liveries

 

 

<ModelInfo>

This element is a container element for all the livery LOD details. This element can contain the following:

1. <LODS>

 

This element has the following attributes:

 

Attribute	Description	Type	Required
Version	The version of this ModelInfo definition. Default is "1.0". Currently not important.	Float	No

 

 

<LODS>

This is a container element that has no attributes and contains one or more <LOD /> sub-elements. The LODs given here should correspond to the glTF files of the livery part where the file is located.

 

 

<LOD />

This sub-element of <LODS> is used to describe a single LOD model. It can be self closing, or it can contain one or more <MergeModel> elements. It has the following attributes:

 

Attribute	Description	Type	Required
modelFile	Defines the model file to use (from a relative path) for this LOD.	String	No
minSize	This is the minimum size on screen before this LOD model is considered for display, as a percentage. Note that the value can be greater than 100%. Please see the LOD Selection System page for more information on this property.	Float	Yes

 

 

<MergeModel>

This element is used to define the different animation and/or sub-model glTF files that should be used for the SimObject over the different <LOD /> elements. Paths for this element are relative to the model XML file location. If you are using both sub-models and animations then you would have at least two of these elements, although you can have more as required. You can find an example for this element here: Submodels And Animations. You can also find out more information about sub-model merging here: Submodel Merging.

 

 

<DynamicMaterial>

This is a container element used for defining various properties which will change how a material is rendered dynamically, based on a combination of factors (the location, the career, the applied labels, etc...). This element can contain different sub-elements depending on which of these types of dynamic assets you are targeting, and you can have multiple <DynamicMaterial> container elements in the livery XML file (one for each material of the model to set up).

 

The types of dynamic material available are as follows:

 

• Material: This is used when you wish to swap the "base" material for another one. For dynamic materials you will need to have set up a material.lbl (using The Material Editor) and then use the following elements:
  1. <MatName>
  2. <Type>
  3. <Labels>

 

• Texture: This is for when you wish to assign a texture to a material. For dynamic textures you will need to have a texture.lbl and then use the following elements:
  1. <MatName>
  2. <Type>
  3. <EnforcePlayerCompany> Not Currently Used In The Simulation.
  4. <Labels>

 

• Text: This is when you wish to use a material to render text instead of a texture. For dynamic text you will need a text.lbl and then use the following elements:
  1. <MatName>
  2. <Type>
  3. <TextureSize>
  4. <EnforcePlayerCompany> Not Currently Used In The Simulation.
  5. <TextureSize>
  6. <TextLayer>
  7. <Labels>

 

• Color: This is used when you wish to alter the albedo of a material and not its texture. For dynamic palettes you will need a palette.lbl and the following elements:
  1. <MatName>
  2. <Type>
  3. <PaletteId>
  4. <RandomColors>
  5. <Labels>

 

 

<MatName>

This element is a child of <DynamicMaterial> and is where you give the name of a flightsim material in a model glTF that is to be the target of the dynamic material being defined. For example:

<MatName>TEXT_01</MatName>

 

 

<EnforcePlayerCompany>

This element is a child of <DynamicMaterial> and can be set to either EnforceLogo or EnforceName, depending on whether the material being targeted is being used for an image or for text. This will force the material to display the user selected Logo/Name instead of a dynamic one.

NOTE: This is currently not used by the simulation.

For example:

<EnforcePlayerCompany>EnforceName</EnforcePlayerCompany>

 

 

<Type>

This element is a child of <DynamicMaterial> and is used to set the type of dynamic material being defined. It can be one of the following:

• Texture: This XML is defining a texture (logo/sticker). See here for an example: Adaptive Texture Example. Note that in addition to changing the image of a texture, you may include the material in an editable_color.N definition to colour it dynamically.
• Text: This XML is defining some text. See here for an example: Adaptive Text Example. Note that in addition to changing the image of a texture, you may include the material in an editable_color.N definition to colour it dynamically.
• Material: This XML is defining a material to be used instead of the "base" material. See here for an example: Adaptive Material Example.
• Color: This XML is defining a colour palette to be used. See here for an example: Adaptive Palette Example. Not currently used in the simulation.

 

For example:

<Type>Text</Type>

 

 

<TextureSize />

This self-closing element is a child of <DynamicMaterial> and is only used when the <Type> is set to Text. This sets the texture resolution for the text to be displayed on the mesh with the linked material. In general this should mimic approximately the aspect ratio of the mesh itself (so if the mesh is square then the width/height will be the same, but if it's a rectangle then the width will be greater than the height). The values used here will affect the quality of the text rendering and in general you should keep this as low as possible. For example, the text below was rendered with a texture size of (1024, 160):

 

This element has the following attributes:

 

Attribute	Description	Type	Required
Width	The width of the texture (in pixels).	Integer	Yes
Height	The height of the texture (in pixels).	Integer	Yes

 

For example:

<TextureSize Width="1792" Height="128" />

 

 

<Labels>

This element is a child of <DynamicMaterial> and is used to setup the various labels that will be used to specify under which circumstances the dynamic material being defined will be used as well as which image or text should be used (when appropriate). This element has no parameters and requires one or more <Label> element.

 

For example:

<Labels>
    <Label Key="Category" Value="Logo"/>
    <Label Key="Activity" Value="TOR"/>
    <Label Key="language_code"/>
</Labels>

 

 

<Label />

This self-closing element is a child of <Labels> and is used to define a single label which will be used as part of the decision tree to find the appropriate dynamic element to be applied. The idea is to create a selection of labels that will identify a single adaptive element to be used at any given time based on the circumstances or location of the flight. Since you can define any labels you want when you create the Dynamic Library LBL Files there is no definitive list of labels to be used, however some dynamic material types do benefit from specific labels:

 

• When <Type> is Text: If you have a label with the key "Category" and a value of either "CompanyName", "Slogan", or "CommodityName", then you can also add a label with the "language_code" key (with no value). This will then search through the <text>.lbl file to find the appropriate translated text, which requires that each translation in the library file has a "language_code" label key with the value of the code for the language being translated. The languages that are checked for come from the ISO 639 specification (two letter codes), and some may have an additional modifier from ISO 15924 to identify variants (see "Labels" for more details). You may apply additional labels to narrow down the results to a particular translated phrase, for example here we are using an additional label to say which activity is being performed to find a more contextual text translation:

  <Labels>
      <Label Key="Category" Value="Logo"/>
      <Label Key="Activity" Value="TOR"/>
      <Label Key="language_code"/>
  </Label

 

This element has the following attributes:

 

Attribute	Description	Type	Required
key	This is the key that governs what value the label should have. Certain keys require no values and a value be inferred based on the Mission data or the Adaptive data. Please see Geographic Keys / Values for more information.	String	Yes
value	This is the value of the label, based on the specific key that has been given. This value must be appropriate for the key given, as outlined in the table below. Note: Not all keys require values. If a key is given but no value, then the value may be extrapolated by the engine from inside the Mission data or the Adaptive Data. If the value is set to "ANY", then the simulation understands that the value of the given key does not matter. However, it will still search for an asset with a label with the same key.	String/Float	Yes

 

For example:

<label key="Activity" value="TOR" />

 

 

<TextLayer>

This element is a child of <DynamicMaterial> and is only used when the <Type> is set to Text. It requires a single <Line> sub-element to define a single line of text to be displayed. It has no attributes.

 

For example:

<TextLayer>
    <Line>
        <Content>SOUTH CALIFORNIA FIRE SERVICE</Content>
        <FontFamily>Made-outer-sans-alt</FontFamily>
        <MacStyle Bold="false" Italic="false" Underline="false"/>
        <FontSize Value="128" Unit="px"/>
        <Color>#ffffff</Color>
        <Alignement>center</Alignement>
        <LetterSpacing Value="10" Unit="px"/>
    </Line>
</TextLayer>

 

 

<Line>

This element is a child of <TextLayer> and acts as a container for all the sub-elements required to generate a line of text on the meshes with the material being defined.

NOTE: Currently adaptive text is limited to only one line of text, so you can only have one <Line> element in the dynamic material.

It can have the following sub-elements:

1. <Content>
2. <FontFamily>
3. <MacStyle />
4. <FontSize />
5. <Color>
6. <Alignment>
7. <LetterSpacing />
8. <StrokeColor>
9. <StrokeWidth />
10. <TextEditableColor>
11. <StrokeEditableColor>

 

 

<Content>

This element is a child of <Line> and defines the text to be used as the contents of the texture that will be created. For example:

<Content>Euphoria Travels</Content>

 

 

<FontFamily>

This element is a child of <Line> and defines the font family to use for rendering the text to the texture. For example:

<FontFamily>Arial Black</FontFamily>

The following is a complete list of the fonts that you can use:

 

 

<MacStyle />

This self-closing element is a child of <Line> and is used to define the style of the font. Note that currently you can only deifne a single line element per dynamic livery definition.

 

The style is given using the following attributes:

 

Attribute	Description	Type	Required
Bold	Set to "True" for the text to use bold. If the text does not support a bold style, or you do not wish to use bold text, set to "False".	Boolean	Yes
Italic	Set to "True" for the text to use italics. If the text does not support an italics style, or you do not wish to use italicised text, set to "False".	Boolean	Yes
Underline	Set to "True" for the text to be underlined. If you do not wish to use underlined text, set to "False".	Boolean	Yes

 

For example:

<MacStyle Bold="true" Italic="true" Underline="false"/>

 

 

<FontSize />

This self-closing element is a child of <Line> and is used to define the size - in pixels - of the font. The value given here is orientative and may be ignored depending on the area that the text takes up. If the supplied pixel size - combined with any stroke width - would mean that the text goes outside the texture borders, then the font size will be scaled down until the whole text message - including the outer stroke - fits the texture.

 

The font size is defined using the following attributes:

 

Attribute	Description	Type	Required
Value	The size value to be used for the font, in pixels. Note that you can use "AUTO" here to have the simulation set the size based on the "best fit" of the text on the texture.	Integer	Yes
Unit	This should always be set to "px".	String	Yes

 

For example:

<FontSize Value="AUTO" Unit="px"/>

 

 

<Color>

This element is a child of <Line> and defines the colour to use for the text as a hexadecimal value. The value should not include alpha, so only RGB. Note that in general you will want this to be dark grey/black or very light grey/white, since the final colour of the text will be the colour given here, merged with the editable_color.N that is using the dynamic material (as defined in the livery.cfg file).

 

For example:

<Color>#cccccc</Color>

 

 

<Alignement>

This element is a child of <Line> and sets how the text will be aligned within the mesh the texture is being applied to. This can be either:

1. start: Text will be left-justified.
2. center: Text will be centered.
3. end: Text will be right-justified.

 

For example:

<Alignement>center</Alignement>

 

 

<LetterSpacing />

This element is a child of <Line> and is used to set the spacing between the letters of the content text. This is a self-closing element and has the following parameters:

 

Attribute	Description	Type	Required
Value	The size value (in pixels) to be used for spacing the letters in the content text.	Integer	Yes
Unit	This should always be set to "px".	String	Yes

 

For example:

<LetterSpacing Value="10" Unit="px"/>

 

 

<StrokeColor>

This element is a child of <Line> and sets the colour to use for the text stroke (outline) as a hexadecimal value. The value should not include alpha, so only RGB. Note that in general you will want this to be dark grey/black or very light grey/white, since the final colour of the stroke will be the colour given here, merged with the editiable colour that is using the dynamic material (as defined in the livery.cfg file).

 

For example:

<StrokeColor>#222222</StrokeColor>

 

 

<StrokeWidth />

This element is a child of <Line> and sets the width of the stroke around the content text. This is a self-closing element and has the following parameters:

 

Attribute	Description	Type	Required
Value	The size value (in pixels) to be used for the stroke around the content text.	Integer	Yes
Unit	This should always be set to "px".	String	Yes

 

For example:

<StrokeWidth Value="5" Unit="px"/>

 

 

<TextEditableColor>

This element is a child of <Line> and sets the editable colour to use for the text. The value given here is an index value that references an editable_color.N from the livery.cfg. This is the colour that will be used for the text instead of the given instead of the initial colour it has been assigned.

 

For example:

<TextEditableColor>3</TextEditableColor>

 

 

<StrokeEditableColor>

This element is a child of <Line> and the editable colour to use for the stroke around the text. The value given here is an index value that references an editable_color.N from the livery.cfg. This is the colour that will be used for the text instead of the initial colour it has been assigned.

 

For example:

<StrokeEditableColor>0</TextEditableColor>

 

 

<PaletteId>

IMPORTANT! This is currently not used by the simulation.

This element is a child of <DynamicMaterial> and is only used when the <Type> is set to Color. It has no attributes, and is simply used to assign an ID value to the palette - as defined in a <palette>.lbl file - that is retrieved based on the associated <Label> keys. For example:

<PaletteId>1</PaletteId>

 

 

<RandomColors>

IMPORTANT! This is currently not used by the simulation.This element is a child of <DynamicMaterial> and is only used when the <Type> is set to Color. It has no attributes, and is used to select a colour from a list of random colours added into the element as children using the sub-element. For example:

<RandomColors>
    <color>#278d12</color>
    <color>#1f8557</color>
    <color>#e7468e</color>
    <color>#ea713a</color>
    <color>#a6eb72</color>
</RandomColors>

 

 

<Color>

This element is a child of <RandomColors> and is used to define a single colour from which the random colour algorithm will pick. Colours are given as RGB hexadecimal values.