Add-on Configuration Files

Overview

User Account Control (UAC) restricts access to the Program Files (x86) folder and to program install locations. Ideally, Prepar3D's base installation folder and the files contained in that folder, should never be modified. If additional content is installed in Prepar3D's installation folder, or if files in Prepar3D's installation folder are modified, the additional content/changes could be deleted or corrupted during Prepar3D upgrades and reinstalls.

To facilitate proper integration with add-ons, Prepar3D reads in various configuration files the specifies add-on content locations.

Configuration via Command Line

Although the recommended way of distributing add-on components is by creating an Add-on Package which is automatically discovered, it is possible to manage the installation of each add-on components via command line switch arguments to the installed Prepar3D executable. Developers can use this feature to add, remove, activate, or deactivate components of add-on content.

The command line switch to use is called -Configure and it takes a command line parameter string that contains comma delimited option value pairs in the form of:

Note: Because the comma is being used as a delimiter, the user must use escape the use of a comma (i.e. , instead of , ) if they want to use a comma in one of the options.

The Command Line Examples section provides a variety examples accomplishing configuration tasks using the content configuration command line arguments. The full list of Options should be used as a reference manual as the examples below are not fully comprehensive.

Command Line Options

The full list of options is as follows:

Option	Values	Notes
Category	The following list of keywords, shown below, specify which category that the configuration (e.g. add, remove, activate, deactivate) should apply to. Note: Use the bolded keyword as the category option. Add-on Package - Refers to the portion of the add-ons.cfg file which lists Add-on Packages that have cached or added via command line. Add-on Discovery Path - Refers to the portion of the add-ons.cfg file which lists additional directories to search for add-ons in during the discovery phase of loading add-ons. Autogen - Refers to the autogen.cfg file which is used to search through additional directories to resolve autogen files. DLL - Refers to the dll.xml file which is used to load add-on libraries. EXE - Refers to the exe.xml file which is used to load add-on applications. Effects - Refers to the effects.cfg file which is used to allow Prepar3D to search through additional directories to resolve effects. Fonts - Refers to the fonts.cfg file which is used to allow Prepar3D to search through additional directories to resolve fonts. Gauges - Refers to the gauges.cfg file which is used to allow Prepar3D to search through additional directories to resolve gauges. Sound - Refers to the sound.cfg file which is used to search through additional directories to resolve sound files. Scaleform - Refers to the scaleform.cfg file which is used to allow Prepar3D to search through additional directories to resolve scaleform files. Scenarios - Refers to the scenarios.cfg file which is used to allow Prepar3D to load scenarios in additional directories. Scenery - Refers to the scenery.cfg file. For information on scenery configuration, please see Scenery Configuration File. ShadersHLSL - Refers to the shadersHLSL.cfg file which is used to allow Prepar3D to search through additional directories to resolve shaders and HLSL files. SimObjects - Refers to the simobjects.cfg file which is used to allow Prepar3D to load simobjects from additional directories. Texture - Refers to the texture.cfg file which is used to allow Prepar3D to search through additional directories to resolve textures. Weather - Refers to the weather.cfg file which is used to allow Prepar3D to search through additional directories to resolve weather files.	The following do not have command line support: Terrain - Can specify a different directory to load terrain.cfg file using -SCENERY command line arguments. Cannot configure terrain directory. For information on configuring terrain, please see Terrain Configuration File.
Operation	This option specifies what task the content configuration system should perform. Add This option will add a directory specified by the Path option to the Category option's associated configuration file. If the directory specified by Path already exists, then it is moved to the top. If the directory does not exist, then it is inserted with the highest priority. Remove This option will remove the directory specified by the Path or title specified by the Title option to the Category option's associated configuration file. If the directory specified by Path does not exist, then nothing occurs. Enable or Activate This option will set the active field to true on the entry whose directory is specified by the Path or whose friendly name is specified by Title. Disable or Deactivate This option will set the active field to false on the entry whose directory is specified by the Path or whose friendly name is specified by Title.	These operations only operate upon entries in the Category's configuration file that is specified by the FileLocation. These operations will not apply to entries in other configuration files found at other file locations.
Path	This option is used in combination with the Operation values Add and Remove. This path should refer to a valid directory. Environment variables are allowed to be used in this path as Prepar3D is capable of expanding them at runtime.	Entries can either be modified by Path or Title. If both are specified, only Title will be used.
Title	This option specifies the friendly identifier string for the entry. The Title is what will appear in the UI (e.g. Scenery Library UI).	Entries can either be modified by Path or Title. If both are specified, only Title will be used. NOTE: Title is used in lieu of Name when working with the DLL or EXE configuration files.
FileLocation (Optional)	By default, the specified Operation will be executed upon the default location where that file originally writes out. To support environment preferences, a developer may want to specify where the path Operation will be performed. The following names can be used to explicitly specify the supported file locations: Local - User account specific and system specific. Roaming - User account specific and system independent. ProgramData - User account independent and system specific. NOTE: The priority of the folders is described in the section Configuration Files and Their Priorities.	Scenery does not use this argument and will always be read from Common AppData unless -SCENERY command line switch is specified. DLL and EXE configuration files only support loading from Roaming and ProgramData.
Active (Optional)	By default this value is True if unspecified. If True, then the entry will be loaded by the content system. If this is set to False, a user will either have to enable the entry in the UI or change it via the correct command line arguments.	Currently, only the Scenery can change the Active state of an entry while the system is running. For other components, configure the active state via the appropriate command line arguments. NOTE: Active is used in lieu of Disabled when working with the DLL or EXE configuration files.
Required (Optional)	By default this value is False if unspecified. If set to True, then this indicates that the folder is required and that the entry cannot be removed in the UI.	The required flag determines whether the user can remove the entry from the UI. Entries that are required should not be deleted. If the user does not want to use a required entry, then the entry should be deactivated instead of removed.
Type (Textures Only)	Determines the type of path for the texture entry. Texture entries are either of type: UI, GLOBAL, or WORLD.
Additional Options... (Application and Libraries Only)	All of the properties specified in the Launch.Addon section work as input arguments, with noted exceptions. Both the library add-ons, dll.xml, and application add-ons, exe.xml, share the same format.

Configuration Files and Their Priorities

Each of the listed categories have a configuration file associated with them that is created during the initial execution of Prepar3D and can be found in:

Additionally, add-on configuration files can be created in one of the following locations if there is a need to facilitate individual user configurations:

Some configuration files only support a subset of the three configuration file locations and are denoted accordingly. If the base files in %PROGRAMDATA%\Lockheed Martin\Prepar3D v3 are deleted then they will be regenerated upon starting Prepar3D. If you do not want to use an entry that is found within one of the base files, then set their respective active property to false rather than removing them.

The priority for how content based add-on configuration files are initialized is as follows:

• Local: Configuration files found at: %LOCALAPPDATA%\Lockheed Martin\Prepar3D v3
• Roaming: Configuration files found at: %APPDATA%\Lockheed Martin\Prepar3D v3
• ProgramData: Configuration files found at: %PROGRAMDATA%\Lockheed Martin\Prepar3D v3

The priority for how add-on library (DLL) and application (EXE) configuration files differs from content and is initialized as follows:

• ProgramData: Configuration files named dll.xml or exe.xml found at: %PROGRAMDATA%\Lockheed Martin\Prepar3D v3
• Roaming: Configuration files named dll.xml or exe.xml found at: %APPDATA%\Lockheed Martin\Prepar3D v3

If multiple configuration files are found, then the list of paths are merged together when processed according to the above priority.

Command Line Examples

Installation Examples

[Add-on Package] This command will add an entry named My Add-on to the add-ons.cfg to look for the add-on.xml in the file directory: C:\Program Files (x86)\My Company\My add-on. This entry will be added to the ProgramData add-ons.cfg file by default since no FileLocation was specified which will make it available for all users. The entry name is not the name that displays in the Add-on UI but is instead a unique name that the developer may remove the add-on package by during uninstallation.

[Add-on Package] This command will add an entry to the the Roaming (AppData) add-ons.cfg to look for the add-on.xml in the file directory: C:\Program Files (x86)\My Company\My add-on. Because Roaming (AppData) was specified using the FileLocation option, the package is loaded only for the individual user. Since there is no entry name, the package must be uninstalled by its path name.

[Content] This command will add an entry to the default effects.cfg to look for effects in the file directory C:\Program Files (x86)\My Company\My Effects Product\data:

[Content] The following command will add an entry named My Scenery to the scenery configuration to use scenery inside C:\Program Files (x86)\My Company\My Scenery Product\data. The required option dictates that this item cannot be deleted from the Scenery Library UI.

[Content] This command will resolve the path defined by environment variable %MY_SCENARIO_PRODUCT% to the default scenarios.cfg file. The environment variable %MY_SCENARIO_PRODUCT% will be resolved, if it is defined, when Prepar3D uses the path. For example, the environment variable could be defined to be C:\Program Files (x86)\My Company\My Scenario Product\data by the product's installer.

[Library] The following command will add a library (DLL) add-on named My Library to the default DLL.xml file located in ProgramData. The add-on will load from C:\Program Files (x86)\My Company\My Library Product\My Library.dll. The command is:

[Library] The following command will add a library (DLL) add-on named My Library to the Roaming (AppData) DLL.xml file. The add-on would load from the path, whose environment variables would be expanded, %MY_LIBRARY_PRODUCT%\My Library.dll, but it has been disabled. The command is:

[Library] The following command will add a library (DLL) add-on named My Manual Library to the default DLL.xml file located in ProgramData. The add-on will load from C:\Program Files (x86)\My Company\My Library Product\My Manual Library.dll and need user permission to run each time. The command is:

[Library] The following command will add a library (DLL) add-on named My SimConnect Library to the default DLL.xml file located in ProgramData. The add-on will load from C:\Program Files (x86)\My Company\My Library Product\My Simconnect Library.dll and its entry point and exit point functions will be configured by the SimConnect DLLType. The command is:

[Library] The following command will add a library (DLL) add-on named My PDK Library to the default DLL.xml file located in ProgramData. The add-on will load from C:\Program Files (x86)\My Company\My Library Product\My PDK Library.dll. Its entry point and exit point functions have been overridden by custom DLLStartName and DLLStopName and it will be called with a function argument, the PDK Interface, because its DLLType is set to PDK. The command is:

[Application] The following command will add an application (EXE) add-on named My SimConnect Application to the default EXE.xml file located in ProgramData. The add-on will load from C:\Program Files (x86)\My Company\My Application Product\My Simconnect Application.exe and will run with command line arguments, for hypothetical verbose output, as well as show up in a new console window. The command is:

Uninstallation Examples

Uninstalling an entry is done through the Remove operation. Entries can be removed either by Path or Title. If both are specified, then Title takes precedence.

[Add-on Package] This command will remove the add-on package titled My Add-on from the respective add-ons.cfg file, if it exists. In the case where the FileLocation is not specified, the entry will be removed from the ProgramData add-ons.cfg file.

Note: If the add-on package was installed to a directory that automatically discovers add-on packages (e.g. Prepar3D v3 Add-ons), then it can simply be deleted to be uninstalled.

[Add-on Package] This command will remove the add-on package C:\Program Files (x86)\My Company\My add-on from the respective add-ons.cfg file, if it exists. Since the FileLocation is specified, the entry will be removed from the Roaming (AppData) add-ons.cfg file.

[Content] The following command will remove the content directory with the path C:\Program Files (x86)\My Company\My SimObject Product from the simobjects.cfg file, if it exists. This will modify the simobjects.cfg file located in Local (AppData).

[Content] This command will remove all entries in the default scenery configuration file that have the title My Scenery.

[Content] This command will remove all entries in the default scenery configuration file that have the path C:\Program Files (x86)\My Company\My Scenery Product\My Scenery.

[Library] The following command will remove a library (DLL) add-on by its name, My Library, from the default DLL.xml file located in ProgramData. The command is:

[Application] The following command will remove an application (EXE) add-on by its path, whose environment variables would be expanded, %MY_LIBRARY_PRODUCT%\My Application.exe, from the Roaming (AppData) EXE.xml file. The command is:

Modfication Examples

Currently, the only type of modifications that are allowed are activating and deactivating existing entries. Activation and deactivation of entries is done by specifying either the Path or Title. All instances of add-ons found by this criteria will be activated or deactivated. Because entries can be added with Active set to True, this type of management only makes sense if you're disabling or enabling other entries.

[Content] This command will activate the entry whose title is named My Scenarios in the scenario configuration file.

[Content] This command will deactivate the entry whose path is specified by C:\Program Files (x86)\My Company\My Scenario Product in the scenario configuration file.

NOTE: All of the options and values are case insensitive and the leading and trailing spaces are trimmed.

[Library] The following command will activate a library (DLL) add-on by its name, My Library, from the default DLL.xml file located in ProgramData. The command is:

[Application] The following command will deactivate an application (EXE) add-on by its path, C:\Program Files (x86)\My Company\My Application.exe, from the Roaming (AppData) EXE.xml file. The command is: