Livery XML Properties

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 should be used within an aircraft livery setup, please see here:

Merge Process For Liveries

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

Livery XML Examples

<ModelInfo>

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

<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:
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:
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:
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:
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.
Text: This XML is defining some text. See here for an example: Adaptive Text Example.
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.

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):

Example Of Dynamic Text Rendering

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"/>
</Labels>
```

This element has the following attributes:

Attribute	Description	Type	Required
`key`	This is the key that governs what value the label should have. There are only specific keys that can be used, as outlined in the table below.	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 that not all keys require values.	String/Float	Yes

For example:

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

Label Key Values

The table below shows the relationship between the <Label> keys and their corresponding choice of values, based on the library <Type>. The actual label keys and their values will very much depend on the setup of the Dynamic Library LBL Files that have been created for the asset, since you can create anything you want when you generate the *.lbl file.

IMPORTANT! This is not an exhaustive list, since the various LBL files that use the lables can be modified and have any label that you choose, which in turn can be referenced in this XML element. These are simply the ones that are recognised by the simulation and used by the development team.

Key	Value
Material
`Category`	Material: This is only used when the `<Type>` is also "Material".
`TypeTest`	The value for this key should correspond with the label defined for a material created in the The Material Editor. NOTE: Only used when the Category is "Material".
Texture
`Default`	Any: Sets the dynamic material to be available at all times with no constraints.
`Category`	LargeImages: A large and complex high quality adaptive image used on the entirety of the given vehicle. This is only applicable to ground vehicles. Logo: A large adaptive image that is to be changed according to the activity being flown. In general we recommend that this image is 1024x1024px in size. This is only applicable to ground vehicles, or aircraft. Certificate: Small image, not currently used in the simulation. Plate: Small image that is used to generate adaptive licence plates. This is only applicable to ground vehicles. Poster: Small to medium sized image used to generate adaptive posters for decorating Hangars and Airports. This is only applicable to environmental assets. Sticker: A small adaptive image that isn't linked to any specific activity. This is only applicable to ground vehicles, or aircraft. Strip: A tileable texture pattern. This is only applicable to ground vehicles.
`Format`	1x1 2x1 1x2 1x3 2x3 4x1 5x1 7x1 NOTE: Only used when the Category is "Sticker"
`Colorable`	Yes: The logo image will be coloured based on the `editable_color.N` parameter in the livery.cfg. No: The logo will not be coloured. NOTE: Only used when the Category is "Logo"
`Order`	Background: This will override the draw-order for the material and force the image to be drawn under other dynamic materials. Foreground: This will override the draw-order for the material and force the image to be drawn over other dynamic materials. No: This will use the draw-order defined in the material. NOTE: Only used when the Category is "Logo"
`Alignment`	Left: The image will be aligned to the left of the mesh. Right: The image will be aligned to the right of the mesh. Top: The image will be aligned to the top of the mesh. Bottom: The image will be aligned to the bottom of the mesh. No: No alignment will be performed (the texture will be centered on the mesh) NOTE: Only used when the Category is "Strip" or "LargeImages"
`Pattern`	Yes: This tells the simulation to tile the image across the whole mesh with the referenced material (horizontal and vertical). No: The image will not be tiled. NOTE: Only used when the Category is "Strip".
Text
`Default`	Any: Sets the dynamic material to be available at all times with no constraints.
`Category`	The category for text is user-defined when the `<text>.lbl` is created.
`language_code`	Including this (with NO value) means that the text has been translated and included in a <text>.lbl with the package. The simulation will then parse the LBL file to find the translated text appropriate for the country or region where the aircraft is being flown.

<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:

<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:

ARIAL (regular / bold / bold italic / italic)
ARIAL BLACK (regular)
ARIAL NARROW (regular / bold / bold italic / italic)
MALGUN GOTHIC (regular / bold)
MALGUN GOTHIC SEMILIGHT (regular)
MANGAL (regular)
NSIMSUN (regular)
NIRMALA UI SMILIGHT (regular)
VRINDA (regular)
NOTO SANS KR (regular / bold)
NOTO SANS KR BLACK (regular)
NOTO SANS KR LIGHT (regular)
NOTO SANS KR MEDIUM (regular)
NOTO SANS KR THIN (regular)
NOTO SANS SC (regular / bold)
NOTO SANS SC BLACK (regular)
NOTO SANS SC LIGHT (regular)
NOTO SANS SC MEDIUM (regular)
NOTO SANS SC THIN (regular)
ROBOTO (regular / bold / bold italic / italic)
ROBOTO BLACK (regular / italic)
ROBOTO CONDENSED (regular / bold)
ROBOTO LIGHT (regular / italic)
ROBOTO MEDIUM (regular / bold)
ROBOTO THIN (regular / italic)
ROBOTO MONO (regular / bold / bold italic / italic)
ROBOTO MONO LIGHT (regular / italic)
ROBOTO MONO MEDIUM (regular / italic)
ROBOTO MONO MEDIUM+MEIRYO UI (regular)
ROBOTO MONO THIN (regular / italic)
ROBOTO SLAB (regular / bold)
ROBOTO SLAB LIGHT (regular)
ROBOTO SLAB MEDIUM (regular)
ROBOTO SLAB THIN (regular)
ROBOTOMONO (bold)

<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:

start: Text will be left-justified.
center: Text will be centered.
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

For example:

<TextEditableColor>3</TextEditableColor>

<StrokeEditableColor>

This element is a child of <Line> and

For example:

<StrokeEditableColor>0</TextEditableColor>

<PaletteId>

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>

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>