Add-on Packages

Contents
Related Links

Overview

Add-on Packages are the recommended way of distributing add-ons because the package provides a centralized list of all of the Add-on Components necessary to load the Add-on.

Creating an Add-on Package

After an add-on has been developed, an Add-on Package file should be created to specify which add-on components Prepar3D should load when processing the add-on. This file must be called:

add-on.xml

The file should be placed at the root level directory of the developed add-on. The root level of the add-on is typically the folder of the add-on's Product Name. The Instructions for Developers article outlines this and where to place the add-on.xml file.


Inside this package file is both information about the Add-on Package as well as a list of Add-on Components. Each Add-on Component specifies the category of the component, the path to where its located, and other information.


The format for the add-on.xml is as follows:


SimBase.Document Schema

The properties at the SimBase.Document level describe the add-on package. The base document can contain multiple AddOn.Component property sets which define each piece of add-on content that describe the add-on.

Property Description Default Value Examples
Name
A name that will be used to show the add-on package in the UI. Empty String <SimBase.Document>
 ...
 <AddOn.Name>My Add-on</AddOn.Name>
 ...
</SimBase.Document>
Description
(Optional, Highly Recommended) 		A description of the add-on package which is shown in the UI. Empty String <SimBase.Document>
 ...
 <AddOn.Description>My Add-on</AddOn.Description>
 ...
</SimBase.Document>

AddOn.Component Schema

The AddOn.Component section specifies an individual add-on component that should be added when processing a package.


Property Description Default Value Examples
Category

The following list of keywords, shown below, are categories that the component belongs to.

Note: Use the bolded keyword as the category option.

  • Autogen - Refers to a component that adds an additional autogen directory that Prepar3D can use to resolve autogen files.
  • DLL - Refers to a component that loads an add-on library.
  • EXE - Refers to a component that loads an add-on application.
  • Effects - Refers to a component that adds an additional effects directory that Prepar3D can use to resolve effects.
  • Fonts - Refers to a component that adds an additional fonts directory that Prepar3D can use to resolve fonts.
  • Gauges - Refers to a component that adds an additional gauges directory that Prepar3D can use to resolve gauges.
  • Sound - Refers to a component that adds an additional sound directory that Prepar3D can use to resolve sound files.
  • Scaleform - Refers to a component that adds an additional scaleform directory that Prepar3D can use to resolve scaleform files.
  • Scenarios - Refers to a component that adds an additional scenario directory that the user can choose to load scenarios from.
  • Scenery - Refers to a component that adds an additional scenery area to Prepar3D's world.
  • Scripts - Refers to a component that adds an additional script directory that Prepar3D can use to resolve script files (.lua).
  • ShadersHLSL - Refers to a component that adds an additional shaders and HLSL directory that Prepar3D can use to shader and HLSL files.
  • SimObjects - Refers to a component that adds an additional simobject directory that the user can choose to load simobjects from.
  • Texture - Refers to a component that adds an additional texture directory that Prepar3D can use to resolve textures.
  • Weather - Refers to a component that adds an additional weather directory that Prepar3D can use to resolve weather files.

 Must Specify <AddOn.Component>
 ...
 <Category>Scenery</Category>
 ...
</AddOn.Component>
>
Path
The folder path of the component to be loaded. By default the path is relative to the directory of the add-on.xml file. However, absolute paths are allowed. Must Specify <AddOn.Component>
 ...
 <Path>My Scenery Folder</Path>
 ...
</AddOn.Component>
>
Name
(Optional, required for Scenery Components)

A name for the individual component. For scenery components this is required, however it is highly recommended to have a component name since it will show in the UI. For scenery components, their name is also shown in the Scenery Library.


Note: Since Prepar3D's configuration system does not support components of the same category with the same name, be wary of creating a name that is not unique or it will overwrite the identically named component. However, if the component is not given a name, a name collision cannot occur.

Empty String <AddOn.Component>
 ...
 <Name>My Scenery Region</Name>
 ...
</AddOn.Component>
Type
(Texture Category Only)

The type identifier string determines what kind of path the entry refers to. At this moment, only texture components support this feature. For textures, the type of entries are:


  • UI
  • GLOBAL
  • WORLD

The default value is GLOBAL and should be sufficient for most add-ons. Most systems will at least search GLOBAL directories, however some systems may search both GLOBAL and WORLD directories in a fallback manner. At this time, the UI texture type is only used internally.

GLOBAL <AddOn.Component>
 ...
 <Type>WORLD</Type>
 ...
</AddOn.Component>
Layer
(Scenery Category Only) 		The layer of the scenery area component starting at one, where higher numbered layers take precendence over lower numbered layers. Add-on sceneries typically do not specify a layer and it is assumed that they should be the topmost layer. An integer representing a layer one higher than the top layer <AddOn.Component>
 ...
 <Layer>1</Layer>
 ...
</AddOn.Component>

(A scenery component whose layer is the base scenery layer)
CommandLine
(Optional, EXE and DLL Category Only) 		Specify optional command line arguments to start the add-on application (EXE) or library (DLL) with. Empty String <AddOn.Component>
 ...
 <CommandLine>True</CommandLine>
 ...
</AddOn.Component>
DLLType
(Optional, DLL Category Only) 		The DLLType determines how the add-on library is initially launched. If the DLLType is not set (i.e. Empty String), then the default start, "entry point", and stop, "exit point", functions, described in their respective sections, are used. The list of non-default DLLTypes are:

  • SimConnect
  • PDK

When using these types above, the default DLLStartName and DLLStopName change, unless overridden. Please be aware, the DLLStartName's function parameters for each of the parameters are also different:

  • Default (Empty String): This start function does not have any function arguments.

  • SimConnect: This start function has a single function argument which is a pointer to a constant character array or const char*.

  • PDK: This start function has a single function argument which is a pointer to the Prepar3D PDK interface or P3D::IPdk*.

Empty String <AddOn.Component>
 ...
 <DLLType>SimConnect</DLLType>
 ...
</AddOn.Component>
DLLStartName
(Optional, DLL Category Only) 		It is not necessary to set this field unless the add-on developer wishes to use an overridden DLL start name, "entry point". The DLLStartName that will be used by Prepar3D, if this field is not set, is determined by the DLLType:

  • Default (Empty String): DLLStart

  • SimConnect: SimConnectStart

  • PDK: DLLStart

(See Description)

<AddOn.Component>
 ...
 <DLLStartName>MyEntryFunc</DLLStartName>
 ...
</AddOn.Component>


(A hypothetical function called MyEntryFunc that is the entry point of the add-on)

DLLStopName
(Optional, DLL Category Only) 		It is not necessary to set this field unless the add-on developer wishes to use an overridden DLL stop name, "exit point". The DLLStopName that will be used by Prepar3D, if this field is not set, is determined by the DLLType:

  • Default (Empty String): DLLStop

  • SimConnect: SimConnectStop

  • PDK: DLLStop

(See Description)

<Addon.Component>
 ...
 <DLLStopName>MyExitFunc</DLLStopName>
 ...
</Addon.Component>


(A hypothetical function called MyExitFunc that is the exit point of the add-on)

NewConsole
(Applications and Library Category Only) 		The add-on library (DLL) or application (EXE) will have a new console in contrary to the default behavior of inheriting the parent application's console. False

<Addon.Component>
 ...
 <NewConsole>True</NewConsole>
 ...
</Addon.Component>

Distributing an Add-on Package

Create an Add-on Package that specifies a list of Add-on Components that Prepar3D should load. The recommended and most straightforward way of distribution is to create an add-on whose directory structure aligns with the Add-on Instructions for Developers and whose installation path is Prepar3D's default add-on discovery folder:

%USERPROFILE%\Documents\Prepar3D v4 Add-ons

Other distribution methods include:

When Prepar3D loads, there is a discovery phase where new add-on packages inside each of the discoverable add-on folders are found and cached. Add-on packages can be found and loaded upon startup if they are placed one directory level deep inside an add-on discovery folder. Any add-ons that were cached but could no longer be found are subsequently cleaned up.


For each add-on package being processed, its add-on components, found inside the package, are processed in the order they are read. By default, add-on components processed via packages will take precedence over any add-on components not found in a package (i.e. entries in add-on configuration files).

Add-on Package Example

A full example of an add-on package is shown below:

add-on.xml

<SimBase.Document Type="AddOnXml" version="4,0" id="add-on">
    <AddOn.Name>MyAddOn</AddOn.Name>
    <AddOn.Description>My Add-on developed by My Company.</AddOn.Description>
    <AddOn.Component>
        <Category>SimObjects</Category>
        <Path>Content\SimObjects\Airplanes</Path>
    </AddOn.Component>
    <AddOn.Component>
        <Category>Scenarios</Category>
        <Path>Content\Scenarios</Path>
    </AddOn.Component>
    <AddOn.Component>
        <Category>Scenery</Category>
        <Path>Content\Scenery\Scenery01</Path>
        <Name>Scenery01</Name>
    </AddOn.Component>
    <AddOn.Component>
        <Category>Scenery</Category>
        <Path>Content\Scenery\Scenery02</Path>
        <Name>Scenery02</Name>
    </AddOn.Component>
    <AddOn.Component>
        <Category>DLL</Category>
        <Path>MyFirstDll.dll</Path>
        <DLLType>PDK</DLLType>
    </AddOn.Component>
    <AddOn.Component>
        <Category>DLL</Category>
        <Path>MySecond.dll</Path>
        <DLLStartName>MyStartFunc</DLLStartName>
        <DLLStopName>MyStopFunc</DLLStopName>
    </AddOn.Component>
    <AddOn.Component>
        <Category>Texture</Category>
        <Path>Textures/Global</Path>
        <Type>GLOBAL</Type>
    </AddOn.Component>
</SimBase.Document>

Note: This file above is meant to serve as an instructive example and shows the correct file format the developer should use. However, there are DLL and folder paths referenced above that the developer may not have. Make sure your add-on package file contains only add-on components that have valid file and folder paths.

- top -