The Lockheed Martin Prepar3D Software Development Kit (SDK) is a core component of the Prepar3D platform.
The SDK can be used to develop new models and content, such as aircraft, instruments, ground vehicles, boats, buildings and other structures. It can be used to create new visuals, such as scenery, terrain, and special effects.
Structured scenarios, such as tutorials and checklists, can be created and made available through the user interface.
Prepar3D is fundamentally data driven; there is no limit to the amount of new data, models, or scenarios that can be added.
This document includes details about the SDK Components, plus Hints and Tips, on installation and other general issues. Information on how to deploy your solution can be found in Solution Deployment.
If you are an add-on developer using this SDK to build add-ons for Prepar3D, please also refer to the Add-on Instructions for Developers.
SDK Components
Following is an overview of the components of the SDK with links to the detailed documentation for each component. Unless the installation directory is changed, the SDK installs to:
%PROGRAMFILES(X86)%\Lockheed Martin\Prepar3D v3 SDK *\
The SDK is divided into the following kits:
Utilities
The main component of this kit is the SimConnect programmer's interface. Many add-ons can be built without any programming; however, when the full flexibility of a programming language is required, this component provides the tools and documentation on how to write and link add-on modules to the simulator.
| Component | Description | Documentation |
|---|---|---|
| Camera Configuration | The camera system is highly customizable and extensible, through the use of configuration settings. Cameras can be added to aircraft and other objects, and the camera view can adjusted from a menu option. Cameras can be defined that track certain objects, or that move on a fixed course, or that move relative to another object (such as the user aircraft). The cameras can also be defined to give the view from different seating areas within the aircraft, such as co-pilot or rear-seat passengers. | Camera Configuration |
| Prepar3D Development Kit | The Prepar3D Development Kit (PDK) API is a service provider for obtaining services to the Prepar3D platform. The PDK functions similarly to SimConnect but is tied into Prepar3D at a lower level allowing better performance and more direct interaction. Unlike SimConnect, there is not a network interface for PDK plug-ins as they must be developed as in-process dlls. Data can be injected into and received from the simulation by interfacing with a user-written .dll. Uses for the PDK include creating custom SimObjects, adding custom textures and post-processes, and modifying cameras. | PDK Overview |
| Learning Management System Services | Prepar3D provides prototype interfaces that a Learning Management System (LMS) client will be able to use for basic functions such as loading specific training scenarios and monitoring scenario performance. This document explains the general expected structure of SCORM 2004-compliant web pages that the Prepar3D LMS Services support, how to structure web pages and batch files to successfully interface to Prepar3D LMS Services, and what information to expect back from the Prepar3D LMS Services. | LMS Services |
| SimConnect SDK |
The SimConnect SDK is the programmer's interface to Prepar3D. Add-on components
can be written in C, C++, or, if the managed API calls are being used, any .NET
language such as C#.net or VB.net. There are many possible uses of this interface,
including writing add-ons to control the weather system, manage AI-controlled aircraft,
and intercept key events and provide a different response than the default coded
into the simulator. There are functions to add items to the menu system, control
cameras, request airport facilities data, and provide custom processing for the
scenario system. All of the Simulation Variables and Event IDs (listed in the Variables
section of this SDK) can be accessed through SimConnect. SimConnect uses a client-server model to enable communications between a client written by a third party and the simulator. Typically, a client first requests that communications be opened up with the server, and then makes a list of requests for certain types of information, or system events, to be passed to the client. The asynchronous nature of client-server programming means that the client then waits for the data to be returned. The last processing a typical client normally does is cleanly terminate communications with the server, and then shut down. Many clients can be running at one time, and a priority system has been defined to determine which client receives the requested information in which order. Clients can also communicate remotely with the server. A range of samples is included in the SDK, so the use of many of the function calls is supported by a working sample. Most of these samples are written in C++, the language of choice for most developers, though a number are written in C# and one in VB.NET. A special section of the documentation describes details on programming using the Managed interface. |
SimConnect |
| Variables | This folder contains two files with large tables of the variables that can be used along with SimConnect, or the XML gauge system. The aerodynamic simulation of an aircraft can be defined or changed through the setting of Simulation Variables, as can an aircraft's position and speed. However, many of the hundreds of variables can only be read, and not set; these are for use in such applications as instrumentation. The table of Event IDs provides the list of key events that can be triggered programmatically. |
Event IDs Simulation Variables |
| SimProp | This includes a tool to compile certain XML files into a binary format, the Simpropcompiler. Compiling missions, gauges, and some autogen files are the primary uses of the tool. A data file compiled in this way reduces the file size, and so also reduces load times. It also helps protect the intellectual property of the data. | Creating XML Gauges |
SimObject SDK
Simulation objects are primarily aircraft (fixed wing, helicopters, and sailplanes) but include all other objects that are manipulated by the simulation, such as airport ground vehicles, ships, some animals, and objects used by the scenario system (including, for example, loads to use with a helicopter hoist system). They all require a similar folder and file structure to be represented in the simulation, and the description of this structure, and the required and optional content of each file, is the main purpose of this SDK component.
| Component | Description | Documentation |
|---|---|---|
| SimObject Container SDK |
The aircraft configuration file specifies one or more versions of the aircraft,
as well as the attributes (name, color, sound, panels, gauges, and so on) for each
aircraft and where to find the files that define those attributes. The configuration
file includes details on the aircraft's systems, such as engines, fuel, avionics,
landing gear, physical dimensions, aerodynamics, and many other details such as
camera view positions and special effects. Configuration files are text files that
are easily viewed and updated. Typically, when creating a new aircraft, a configuration
file of a similar aircraft is used as a starting point, and then the necessary changes
are made to it. Some specific aircraft procedures, notably catapult launches, and helicopter slings and hoists, are described in "Notes on Aircraft Systems." Other simulation objects such as ground vehicles, animals, boats, and so on, also require configuration files, although usually these are much smaller than those for aircraft. These are described in "Simulation Object Configuration Files." The sound configuration file is located in an aircraft's Sound folder, and defines the sounds to use for that aircraft. |
Aircraft Configuration Files Notes on Aircraft Systems Sound Configuration Files Sensor And Render To Texture Configuration SimObject Configuration Files |
| Flight Model SDK | AIR files are used to provide flight dynamics data, in the form of coefficients and data tables that determine the flying qualities of an aircraft. A number of samples are provided that can be used as the basis for new flight models. | Flight Models |
| Panels and Gauges SDK |
In the world of Prepar3D, a gauge is any device that might appear in an aircraft
cockpit, from a simple altimeter or clock to a GPS system, weather radar, or radio
stack. They are all called “gauges,” and they are added to the “panel”—the
visible cockpit panel of any aircraft. Whether the gauge is to appear in the flat,
two-dimensional view of the cockpit panel (albeit with graphics tricks to make it
look more 3-D), or in the 3-D “Virtual Cockpit” view, the development
process is the same. It is important to note that a panel is specific to an aircraft,
but a gauge is not. One gauge can be referenced by any number of aircraft. Panels
can be shared if, for example, two aircraft are so similar (typically different
versions of essentially the same aircraft) that they use a technique known as “aliasing.”
The more normal situation is for each aircraft to have its own panel definition
file, referencing a number of both common and specific gauges. The development of panels and gauges is very much an exercise in good artwork. Except when dealing with the most complex of instruments, creating the artwork probably represents the majority of the time spent in creating panels and gauges. There are many examples of panel artwork shipped with Prepar3D, and the definition of a panel is described in “Panel Configuration Files.” There is only one way to create a panel, but there are several ways to create gauges. Which approach to gauge development you should use depends largely on your C++ programming skills, the complexity of the gauge, and your personal preference. The easiest way to develop a gauge requires no particular skill in C++ programming: use the ACE tool to develop an XML-based gauge. This process is described in full and illustrated by a complete tutorial in “Creating XML Gauges.” In addition to showing you how to create a simple panel, the tutorial shows how to produce a Fuel Pressure gauge, which is the simplest of gauges. The tutorial also shows how to develop a stopwatch, a more complex gauge that stores information every time one of the buttons of the stopwatch is clicked. When you complete the tutorial you will have created both gauges and have them up and running in your version of Prepar3D. Very complex gauges have been developed exclusively using the ACE tool and XML, including the GPS systems shipped with Prepar3D. However, there is also no easy means of debugging XML gauges. If you are developing gauges with a programming language, C++ is really your best option. No samples are provided in any other language, and the programming system does not readily support any of the .NET-based languages. However there are two approaches here that are significantly different. The gauge can be developed in its entirety using C++. This is described in full in “Programming C++ Gauges,” which also includes a full range of samples, including the various pieces of artwork (background, moving needles, etc.). A third method of developing gauges is to use the XML system to handle the appearance and user interaction of the gauge, while using C++ to handle the processing. This method of developing gauges is described along with a sample, called Cabin Comfort, at the end of “Programming C++ Gauges.” The complex callback code that this requires is all present in the sample, so it could readily be used as the basis for a gauge development project. The key here, of course, is information passing from the XML scripts to the C++ code, and back. A fourth method of developing gauges is to create a DirectX® gauge. These gauges are very similar to C++ gauges, except that they allow the developer to make use of the DirectX graphical toolkit in drawing their gauges. One important note: the SimConnect API system, described in the “SimConnect” document, is not integrated with the gauge system. The SimConnect system includes many useful API calls for developing other sorts of applications, but could be integrated with gauges using the Cabin Comfort code. |
Programmable Gauges
Creating XML Gauges Panel Configuration Files GPS Variables Panel and Gauge Artwork Programming C++ Gauges Tooltips HelpIDs Token Variables Event IDs Simulation Variables Token Variables XML Gauge Maps |
| Cabdir SDK | If you create add-ons, particularly gauges, you can use the Cabdir utility (cabdir.exe) to combine all the folders and files in a directory into a single .cab file (similar to a .zip file), simplifying the process of distributing files to end-users. | Creating Cabinet Files |
| Test External Sim SimObject Container | Within the SimConnect ExternalSim Sample, there is a full SimObject container (located at SDK\Utilities\SimConnect SDK\Samples\ExternalSim\ESFO). You can copy this directory into your SimObjects\Misc\ directory to try out the ExternalSim. This SimObject uses a simple UFO (ESFO - Externally Simulated Flying Object) visual model and the flight model is provided by the SimConnect ExternalSim Sample. This sample includes all the basics of a SimObject container using an external sim module. | Sample External Sim Container |
Environment SDK
The environment kit is the largest component of the SDK, covering terrain, scenery, weather, and other features of the simulation that mostly control the graphics used to render the environment the user aircraft is flying in. This kit also includes the all-important Modeling SDK, which describes the tools, processes, and file formats needed to create three-dimensional models for use within the simulator (both environmental and aircraft). It is important to point out the entire Earth is modeled in Prepar3D, including the little-visited regions of the Arctic and Antarctic. To save space, exact scenery is used only in a number of selected areas; a system called Autogen fills in all the other areas based on information such as land classification, population density, region, and so on.
| Component | Description | Documentation |
|---|---|---|
| Autogen SDK |
Autogen is the name given to the process of creating scenery (buildings and vegetation)
for areas of the Earth where exact data (for example, satellite photo-imagery and
specific building models) is not being used. The Earth is divided up into a grid,
with the smallest squares of the grid being roughly 1.2 km in each direction. Each
square has a land classification -- such as "Cool Broadleaf Forest" or "Dry Woody
Scrub" -- that defines the basic type of vegetation for the area. Texture sheets
for each area are annotated with footprints for each building, area of vegetation,
and so on. The exact buildings and vegetation models used are determined by the
simulation and come from a range specified in various XML files. The documentation
includes a tutorial on how to create a new Autogen class and add it to the XML files
so that the new class appears in the simulation. The SDK includes the tools necessary
to annotate, validate, and place new Autogen scenery.
|
Autogen |
| BGL Compiler SDK |
BGL is the term used to describe the data format required by many Prepar3D
systems. The BGL compiler takes as input an XML file specifying what is required,
and produces as output a BGL file that can be read by the simulator (or a list of
errors covering such things as the XML did not parse correctly, or data files are
missing). Two main uses of BGL files is in holding data for scenery objects (buildings,
bridges, fences, etc.) and for airports (including runway data, taxiways, VOR, NDB,
ILS information, towers, and many other specific pieces of information required
to define an airport). It is also possible to use the compiler to delete some specific
elements from an airport, in order, for example, to replace them with new data. One of the simplest uses of the BGL compiler is to place a single building (perhaps a library object -- one that is provided with the simulation, or one created externally) at a specific location. One of the most complex uses of the compiler is to replace an entire airport with new data. Most of the entries in the documentation include sample XML code that shows how to perform each task. The SDK includes the compiler, BGLComp, and the validation tool called BGLScan. |
Compiling BGL |
| Special Effects SDK | Special effects are used to represent graphical particle effects such as fire, smoke, rain, steam, exhaust, and similar short-term and highly animated effects. A special effect is defined as one or more emitters, each emitter producing one or more particles. Both emitters and particles can be moving in a variety of ways, and a particle will reference a texture appropriate for the effect. Typically, these textures include a fair degree of transparency in order to get the loosely defined shapes of effects such as smoke. Special-effect files are text files and can be edited, but it is usually much easier to use the Special Effects tool - -a dialog-based utility that can be installed to run along with the simulation. Special effects are a key component in adding realism to a graphical model. | Creating Special Effects |
| Terrain SDK |
The Prepar3D terrain system uses eight main sources of data: elevation (DEM
data), imagery, land classification, water classification, regions, seasons, vector
data, and population density. These are used to determine how the landscape of the
Earth is rendered. An aircraft can be flying at 45,000 feet and therefore require
a vast area of the Earth to be rendered, or be on a runway or flying low and only
require a very small area to be visible -- and it can range anywhere in between.
Because of this, it is important to understand the concept of levels of detail (LODs).
Levels of detail for terrain provide essential performance advantages over having
a single representation of the terrain. Another important concept is that of vector data. Vector data includes roads, rivers, streams, coastlines, airport boundaries, and other linear data. This linear data is used to add these types of terrain to the ground textures, so ground textures do not hold this kind of information. River and stream data, for example, needs to cut appropriately into the terrain in order to flow correctly downhill to the sea. There are three main tools that come with this SDK. The Resample tool can replace existing source data with new data, or add photo-imagery to specific locations on the Earth. The TmfViewer tool can be used to examine the source data at any one of the levels of detail. The Shp2Vec tool is used to convert shape files (standard files that contain vector data) into vector data that the simulation can read. Several examples of the use of these tools are provided with the SDK. It is recommended that the "Terrain and Scenery" document be read as an overview of the terrain system. The Terrain and Scenery Configuration Files documentation provides specific information on the format of these configuration files, which determine such things as the priority of the various pieces of terrain and scenery information. |
Terrain and Scenery Terrain Configuration File Scenery Configuration File |
| Traffic Toolbox SDK |
This SDK provides the tools and documentation to customize the AI traffic for aircraft
and some boats.
The tools in this SDK determine the routes and frequency of aircraft controlled by the AI (artificial intelligence) component of Prepar3D. These are all the aircraft that are in the simulation but not controlled by a human (the user aircraft in single player mode, or all the players in a multiplayer scenario). The volume of AI traffic is controlled by a slider in the user interface of Prepar3D, and the tools determine the airports that will be used for AI traffic, the types of aircraft, the parking gates available, the cruising flight levels, the acceptable range for the flights, and similar details. One of the key factors the AI system uses to regulate air traffic so that congestion does not occur is the available parking spaces, and their sizes, at the selected airports. This ensures that air traffic does not become so dense that deadlocking situations occur. Some boat traffic is also handled by the AI system, with ship types, ports, and routes. There is no AI pilot for helicopters or sailplanes. |
Traffic Toolbox |
| Living World SDK | Configurable surface traffic includes recreational boats, freeway traffic, and airport ground vehicles. The Traffic Toolbox SDK is used to specify individual aircraft or ships on specific routes. This SDK provides more general settings for the mass of surface traffic that does not require such individual treatment. A region setting is used so that different models can appear in different parts of the world. The range of possible models is specified, and the living world system will randomly select what it needs to meet the traffic density requirements. Living world models include such airport ground vehicles as baggage carts, baggage loaders, pushback tugs, and fuel trucks. Population density settings from the terrain system are used to determine freeway traffic and recreational boat traffic density. | Configuring Surface Vehicle Traffic |
| Weather SDK |
Controlling the simulated weather is not handled by any single component of the
SDK. The weather can be programmatically set through the SimConnect interface or
specified using the scenario creation tools. The Weather SDK currently enables the
visual appearance of two particularly important weather features -- thermals and
ridge lift -- to be changed. It also specifies a range of parameters for thermals
that depend on the underlying land class. Both of these tasks are handled through
the use of xml files. |
Weather Systems |
Modeling SDK
The main component of this kit is the SimConnect programmer's interface. Many add-ons can be built without any programming; however, when the full flexibility of a programming language is required, this component provides the tools and documentation on how to write and link add-on modules to the simulator.
| Component | Description | Documentation |
|---|---|---|
| Modeling SDK |
The Modeling SDK is one of the largest components of the Prepar3D SDK, and
it is the most important component for many developers. All aircraft, boats, ground
vehicles, buildings, bridges, trees, and just about any other structure that appears
in the simulation needs to have a 3-D model created in the correct format. The format
for Prepar3D is specific to the simulation, and great care has to be taken
to ensure all the steps required are completed correctly. This is especially true
for aircraft, with the range of animations, special effects, lighting, and textures
that make up such complex objects. The origination of a 3-D model can be done using the modeling tool 3ds Max® (a product of Autodesk®), or any other modeling tool that supports the Prepar3D formats. There is a steep learning curve in the use of 3-D modeling tools that should not be underestimated if the goal of professional-looking aircraft is to be achieved. Familiarization at least with the main modeling tool is the recommended first step with this SDK. The documents "New Aircraft Procedures" and "Texturing Aircraft Models" include a lot of good advice directly from the artists who created the models in Prepar3D. The core document "Using Modeling Tools" describes the setup and use of a whole range of tools that are useful or required in the creation of models. One of the most important of these tools, XtoMdl, converts the output from the graphics software into the format required by the simulation. Other tools involve animations, wheels, clouds, shading, attach points, file properties, and levels of detail. The documents "Modeling Materials" and "Jetways" are interesting to view as they both use mouse-over effects to display different graphical features, the former showing the effect of changing different material properties (such as ambient light, specular maps, bloom, and fresnel ramps), and the latter showing the bones used to animate a jetway. The documents "Library Objects," "Animation Tags," and "Modeling File Formats" are for reference when specific information on guids, part names , or the file format needs to be located. |
New Aircraft Procedures Texturing Aircraft Models Using Modeling Tools Modeling Materials Jetways Library Objects Animation Tags Modeling File Formats |
Scaleform SDK
The Autodesk® Scaleform® SDK provides access to the Prepar3D interface as well as existing content to get the developer started developing content using Adobe® Flash®.
| Component | Description | Documentation |
|---|---|---|
| Scaleform SDK |
The Scaleform SDK is split up into two parts:
|
Scaleform Overview |
Scenario SDK
The Scenario SDK provides scenario example files that aid developers in learning how to build advanced scenario content.
| Component | Description | Documentation |
|---|---|---|
| Scenario SDK | The Scenario SDK is made up of subdirectories where each directory contains a scenario and all of the required files. | SimDirector |
Hints and Tips
Installation Requirements
Some of the SDK tools require the Prepar3D runtime to be present on the same computer. It is good practice to install the SDK to a computer with the Prepar3D runtime already installed, and then perhaps move files/folders such as SDK Learning Center\SDKLearningCenter.exe to another computer -- so that the documentation can be referenced on one computer while development is being done on another.
Some of the tools supplied with this SDK require Microsoft .NET Framework Version 4.5.1 to be installed first. This can be installed from Microsoft's website located here.
The paths in the documentation and some tools will only be correct if the SDK is installed to the default folder. If the SDK is installed to a non-default folder, be aware that some documented paths may not be correct, and run the tool ConfigSDK.exe (in the SDK folder) to update the paths of a number of the configuration tools to the correct folder. Before running ConfigSDK.exe make sure to run Prepar3D.exe at least once first (as the tool requires certain registry entries to be present), and that the Prepar3D runtime has been installed to the same computer.
Application Data Folders
The instructions in this SDK documentation assume the developer is working with administrator privileges, otherwise security violations can occur when the tools try to create files in protected directories.
Application data is stored in:
%APPDATA%\Lockheed Martin\Prepar3D v3
Both of these folders are hidden system folders and to make them viewable you need to be logged on as an administrator and have set the view properties to show hidden files and folders. In Windows 7 open up Windows Explorer, select Organize/Folder and Search options then select Show Hidden Files and Folders.
Prepar3D Registry Key Information
Prepar3D's registry key information depends on whether or not you are running a x64 bit or x32 bit Windows machine.
Registry information for computers using a 32-bit architecture is here:
>HKEY_LOCAL_MACHINE\SOFTWARE\Lockheed Martin\Prepar3D v3
For computers using a 64-bit architecture the registry key information for the 32-bit Prepar3D application is here:
>HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Lockheed Martin\Prepar3D v3
Development Software
Visual Studio 2013 can be used to develop SimConnect client applications. For more information on Visual Studio including how to download Visual Studio 2013, visit their website here.
Caution: If an add-on is developed using Visual Studio 2005 SP1, it will run on the development computer, but it will only run on other computers if either one of the following redist packages is installed, or the project is compiled with the _USE_RTM_VERSION compiler switch.
For 32-bit operating systems:
http://www.microsoft.com/downloads/en/details.aspx?familyid=A7B7A05E-6DE6-4D3A-A423-37BF0912DB84&displaylang=enFor 64-bit operating systems:
http://www.microsoft.com/downloads/en/details.aspx?familyid=BD512D9E-43C8-4655-81BF-9350143D5867&displaylang=enForums
While most developer questions will be answered in the SDK documentation and samples, there will always be some questions that are not, so SDK developers are encouraged to join and participate in the various forums discussing the development of add-ons for Prepar3D.
Prepar3D forum can be found here.
Generating GUIDs
A number of the SDK components require GUIDs (globally unique identifiers). A tool to generate these is included in Visual Studio. Alternatively, you can download the GUIDGEN tool from:
This will place an icon on the desktop, called GUIDGen. Open this up and double-click GUIDGEN to open up the tool:
|
For most applications, choose option 4. Registry Format as the most appropriate
GUID format. Click New GUID as many times as necessary. It is not a good idea to manually modify existing GUIDs, as the chances of repeating an existing GUID is greatly increased by doing this. |
|
| The SDK for Prepar3D also ships with a GUID Generator tool. To use the GUID Generator run the GUIGenerator.exe file in your SDK directory. Type the amount of GUIDs you wish to generate in the given text box. Then click generate to create that many GUIDs. Click save to save the GUIDs to a file where they can be retrieved at any time. |
Configuration Settings
In Prepar3D.cfg, in the [Graphics] section, the following two settings can affect performance:
SmallPartRejectRadius=N (default is 1) which determines the radius in pixels that an object has to be in order to be rendered. Increasing this size will cull more objects from the rendering pipeline.
MergeDirtyRegionUpdates=1 or 0 (default is 1) which indicates if updates, particularly to glass cockpit panels, should be done locally or to the whole display area. Setting this to 0 on older graphics cards might lead to a small performance improvement with certain panels.
In Prepar3D.cfg, in the [Realism] section, the following settings determine what happens when the user aircraft crashes. Care should be taken in multiplayer scenarios, particularly using the shared-cockpit, that the settings are identical on all computers -- otherwise there will be unpredictable behavior.
CrashDetection True=Detect user aircraft crashes and respond according to the setting of OnCrashAction, False=ignore all crashes by "bouncing" the aircraft back into a safe flying state.
OnCrashAction In single player mode: 0=reset the scenario from the beginning (the default), 1=end the scenario, 2=leave the user aircraft in the crashed position. In multiplayer mode for options 0 and 1 a client will simply be returned to the briefing room, and the host will be left either in the crashed state (for scenarios), or the scenario will be reset (for free flight). Option 2 works the same as for single player mode -- the user aircraft for both host and client will be left in the crashed position.
In Prepar3D.cfg, in the [MAIN] section, the following setting can be used to aid in the content of development.
ContentErrorLogging If this value is set to 1, many errors related to content will be logged to a file %USERPROFILE%\Documents\Prepar3D v3 Files\ContentErrorLog.txt. Examples of errors are duplicate config files or invalid property settings. Normally Prepar3D will silently handle these errors as best as possible, but developers should verify their content is not generating entries in this file.
Solution Deployment
There are a number of features of Prepar3D designed to aid in the deployment of a solution (for example, a tutorial) to an audience under more controlled circumstances than just running the Prepar3D.exe. The Solution Deployment section shows how to change the default installation folder. The Command Line Switches section enables the simulation to be started with a specific scenario and optionally specific scenery, among other options. The Launching the Solution section describes a tool that is provided to make deployment of a solution -- particularly a tutorial -- easy and consistent.
Command Line Switches
Prepar3D.exe can be initiated from a command line with an optional set of switches. Multiple switches can be used, as long as they do not conflict with one another. Where paths are entered, quotes should be used around both the switch and the path (refer to the examples in the table).
| Switch | Description | Examples |
|---|---|---|
| -dev | This switch has been deprecated. | Prepar3D -dev |
| "-flt:path_to_scenario.flt" | Loads the named legacy scenario file. The path can be relative to the root folder containing Prepar3D.exe, or an absolute path. This is the recommended method of loading single-player missions. The -flt switch is optional if the path to the legacy scenario file is the last entry on the command line. | Prepar3D "-flt:Missions\Airline Pilot\Monsoon\Monsoon.flt" |
| "-fxml:path_to_scenario.fxml" | Loads the named scenario file. The path can be relative to the root folder containing Prepar3D.exe, or an absolute path. This is the recommended method of loading single-player missions. The -fxml switch is optional if the path to the scenario file is the last entry on the command line. | Prepar3D "-fxml:scenarios\Test\AIBehaviorMission\AIBehaviorMission.fxml" |
| -mp | The simulator will start in "host a standard scenario session" multiplayer mode, with the Multiplayer Dialog visible. | Prepar3D -mp |
| "-mp:path_to_scenario.flt" | Starts the simulator in "host a multiplayer scenario" mode, using the scenario and object file provided, and with the Multiplayer Dialog visible. Double quotes should be used in case there are any embedded spaces in the path, which can be an absolute path, or a path relative to the folder containing Prepar3D.exe. | Prepar3D "-mp:Missions\Racing\Reno MP race start\Reno MP race start.flt" |
| -mpjoin | Starts the simulator in "join a multiplayer session" mode, with the Multiplayer Dialog visible. | Prepar3D -mpjoin |
| "-mpplayer:LAN Name" | Skips the login screen and uses the player name provided by the command line. |
Prepar3D -mpjoin "-mpplayer:Trainee Pilot One" Prepar3D -mp "-mpplayer:Trainee Pilot One" Prepar3D "-flt:Missions\Airline Pilot\Monsoon\Monsoon.flt" "-mpplayer:Trainee Pilot One" |
| -mpplayer | Skips the login screen and uses the player name provided in the Prepar3D.cfg configuration file (in the [Multiplayer] section with the entry "LANUsername=Player name"). The maximum length of a player's name is 20 characters. If the entry does not exist in the file, the switch is ignored and the regular login screen is displayed. |
Prepar3D -mpjoin -mpplayer Prepar3D -mp -mpplayer Prepar3D "-flt:Missions\Airline Pilot\Monsoon\Monsoon.flt" "-mpplayer |
| "-scenery:path_to_folder" |
This switch enables specific scenery and terrain configuration files to apply to
a specific scenario. The folder specified in the switch should
contain a terrain.cfg file and a scenery.cfg file, and must be a writable folder
(so that the correct scenery index files can be written to it by Prepar3D).
If either of the files is not present in the folder, the folder does not exist or
is not writable, then Prepar3D will revert to using the default terrain and
scenery configuration files. Note that there should be no trailing "\" in the path
(if the example was entered as Prepar3D "-Scenery:C:\Alternate Config Folder\"
it would not be parsed correctly). If this switch is used while the simulation is running, then some unexpected behavior can occur -- the new scenery can be slow to load, and autogen objects can appear to float. One way to correct the floating issue is to select the Scenery Library menu and simply click OK. Changing scenery this way may have some value during development, but should be avoided when deploying a solution. Use this switch without a path to revert to the default scenery folder. |
Prepar3D "-Scenery:C:\Alternate Config Folder" |
| "-cfgdir:path_to_folder\" |
This switch allows overriding the 3 configuration directories with the specified
directory. The 3 directories that get overridden are:
|
Prepar3D.exe -cfgdir:d:\Replacement\Directory\ |
| "-net:path_and_filename.cfg |
This switch allows starting a multiplayer session from the command line. Provided
.CFG file should have a [Multiplayer] section that includes all the things available
in the Prepar3D.cfg file's [Multiplayer] section. See the Sample Network Configuration Files topic for more information. |
Prepar3D.exe -net:d:\MPHost.cfg Prepar3D.exe -net:d:\MPUser2.cfg |
| -runasprofessional | This switch allows systems with Professional Plus licenses to run as an imitated Professional license. This helps in testing content, scenarios, and features that were developed for Professional Plus licenses, but are also desired to be compatible with Professional licenses. This switch is only recommended for testing and should not be used for any other reason. |
Prepar3D.exe -runasprofessional |
| -simdirector | This switch will cause the application to start up in SimDirector. |
Prepar3D.exe -simdirector |
| -simoperator | This switch will cause the application to start up in SimOperator. |
Prepar3D.exe -simoperator |
|
"-configure:
option1=value1, option2=value2, ..., optionN=valueN" |
This switch allows content developers to more easily perform add-on configuration tasks (e.g. adding, removing, enabled, or disabling directories that Prepar3D will look in for content such as effects or simobjects). This switch is aimed at eliminating the need for developers to write scripts to add their content which often overwrite base installation files or access files that the user may not have permission to access. See the Add-on Configuration Files topic for more information including the extensive list of options and their respective values that can be specified. |
Prepar3D.exe "-configure: File=Effects, Operation=Add, Path=C:\Program Files (x86)\My Company\My Effects Product\data" |
| -deletegenerated |
Deletes the contents of the following folders, which is where Prepar3D stores settings and cached data:
|
Prepar3D.exe -deletegenerated |
| -deleteshadercache | Deletes the contents of the shader cache folder located at: %LOCALAPPDATA%\Lockheed Martin\Prepar3D v3\Shaders |
Prepar3D.exe -deleteshadercache |
| -deletedocuments | Deletes the contents of the Prepar3D documents folder, which is where scenarios are stored, located at: %USERPROFILE%\Documents\Prepar3D v3 Files |
Prepar3D.exe -deletedocuments |
Launching the Solution
This section describes the recommended process for deploying and launching a solution. All of the client machines must have the client version of Prepar3D installed. Typically this would be done prior to installing any particular solution. A solution would typically consist of a launcher program, a manifest file for the launcher, and the scenario and object files. A launcher program is designed to make it easier to ensure a consistent and simple set of instructions for a student to start a tutorial. A sample launcher, Prepar3DLauncher.exe, is included with the SDK, along with its source code in order to enable developing it further for specific applications. A Prepar3D solution could be contained entirely within a Visual Studio Setup Project. This project would contain all the necessary files, along with a launcher program and manifest file. Containing a solution this way should provide a reliable method of deployment, particularly for tutorials where simple instructions to potentially a large class of students is important. Alternatively, the launcher can be installed on the client machine, with the data files for it (image, scenario and object files) held remotely on a server. A security exception will be fired if there is an attempt to run the launcher program remotely.
The sample source code and project for the launcher is installed into the SDK\Utilities\SimConnect SDK\Samples\Prepar3DLauncher folder. The XML file included in this folder is the manifest file that is loaded by the launcher. The following section provides the format of this file.
Manifest File Format
The following shows an example manifest file, with one single player and one multiplayer scenario.
<Solution>
<Name>Sample Solution for Prepar3D Launcher</Name>
<Description>This is a sample solution for populating the information in the Lockheed Martin Prepar3D 1.0 Launcher.</Description>
<VersionMajor>1.0</VersionMajor>
<VersionMinor>1.0</VersionMinor>
<Publisher>Lockheed Martin</Publisher>
<Scenario>
<Name>Tutorial: First Takeoff</Name>
<Description>This is a basic training mission (simulator and flight familiarity). Estimated Time to complete: 5 minutes.</Description>
<IsMultiplayer>false&let;/IsMultiplayer>
<Image>%PREPAR3DPATH%\Scenarios\Tutorials\Basics of Flight\imgM_i.bmp</Image>
<FltFile>%PREAPR3DPATH%\Scenarios\Tutorials\Basics of Flight.flt</FltFile>
</Scenario>
<Scenario>
<Name>Tutorial: Basics of Flight</Name>
<Description>This is a basic training mission (aircraft turns). Estimated Time to complete: 10 minutes.</Description>
<IsMultiplayer>false&let;/IsMultiplayer>
<Image>%PREPAR3DPATH%\Missions\Scenarios\Finding Your Way\imgM_i.bmp</Image>
<FltFile>%PREAPR3DPATH%\Missions\Scenarios\Finding Your Way.flt</FltFile>
</Scenario>
</Solution>
</SimBase.Document>
The purpose of the first range of entries (Name, Description, VersionMajor, VersionMinor, Publisher, SupportPHone, SupportEmail, HelpURL) is self-explanatory. Simply enter appropriate information for your own use. The following table describes the entries that can be contained within a Scenario tag.
| XML Tag | Description |
|---|---|
| Name | The name of the scenario (mission, tutorial, etc.), to appear in the UI of the launcher. This is the only required field. |
| Description | Description of the scenario. |
| IsMultiplayer | Set to True for a multiplayer mission, False otherwise. |
| Image | Path to an image to display in the launcher UI. Images must be .bmp files and should be 380 x 232 pixels. |
| FltFile | Path to the flight file for the scenario. A mission file will be referenced from the flight file. |
| Scenery | Path to the folder containing the alternative scenery and terrain configuration files. |