Prepar3D® SDK Overview

Introduction

The Lockheed Martin® Prepar3D® SDK is the core component of the Prepar3D® product. Prepar3D® is a set of tools that enables simulation of real-world objects. The primary focus of this first release is aviation, and the primary scenario is training, although other scenarios such as decision support are also envisaged.

The primary tool, Prepar3D.exe, is a flight simulator, and this SDK can be used to create add-on components for it. These components can be new models, such as aircraft, instruments, ground vehicles, boats, buildings and other structures. They can be new visuals, such as new or replacement scenery, terrain, and special effects. New missions -- structured flights such as tutorials and tests of skill and knowledge -- can also be created and made available through the user interface of Prepar3D®. Prepar3D® is fundamentally data driven; there is no limit to the amount of new data, models, or missions that can be added.

This document includes details about the SDK Components, plus Hints and Tips on installation and other general issues, and information on features designed to enable easy deployment in Solution Deployment.

If you are an addon developer using this SDK to build addons for Prepar3D®, please also refer to the Instructions for Addon Developers.


Note: The mouse-over features used in some of the images in the Modeling SDK documents will not function in this MSDN documentation set. Use the .CHM documentation supplied with the product to enable these features.

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: C:\Program Files\Lockheed Martin\Prepar3D\SDK\. The SDK is divided into four kits:


Core Utilities Kit

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

Environment Kit

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
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 products 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
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 mission 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

Mission Creation Kit

A mission is a structured flight with a starting point, a set of tasks to complete, and one or more goals to try to achieve. Missions can be single or multiplayer. Many missions are tutorials, although the system is very flexible and can encompass many different types of activities. This SDK component describes how to build missions and then include them in the Missions menu.


Component
Description
Documentation
Mission Creation SDK Missions include adventures, tutorials, tests of knowledge and skill, challenges, and whatever the creator can dream up. There are many components to a mission, but the two most important are triggers and actions. A trigger will fire when certain conditions are met. For example, when the user aircraft takes off, a simple trigger may fire, leading to a number of actions. One of those actions may be some spoken dialog from an imaginary instructor ("Good job on the takeoff") or other actions such as highlighting certain features that the pilot should head for. The most commonly used triggers are proximity triggers (the user aircraft has entered a specified "box" of airspace) and property triggers (the user aircraft has reached a certain speed, altitude, or any one or more of a range of factors). Other triggers include timer triggers (a certain amount of time has elapsed), landing triggers (the user aircraft has landed), and race-specific triggers. There are many more actions including activating a set of waypoints, incrementing a simple count, failing aircraft components, rewarding goals met, playing sounds, refilling fuel tanks, and again some race-specific actions.

Whereas triggers and actions make up the majority of a mission, other components include AI objects (initiating aircraft controlled by the artificial intelligence component of the simulator), mission specific objects, and scenery objects. For each mission there is also one metadata section, specifying the text and images that should appear in the user interface when a user selects the mission, and other details such as its level of difficulty ("Beginner" to "Expert") and how long it should take to complete.

All missions are stored in XML files, and plenty of examples are provided with the SDK. A tutorial in the documentation goes step by step through the process of creating a very simple mission -- taking off, reaching a certain altitude, and then returning to land at the same airport. This simple mission shows the use of the main triggers -- proximity, property and timer triggers -- and a number of simple actions. Creating missions involves use of a tool supplied with the SDK, the Object Placement Tool, which is powerful but not the easiest or most obvious tool to use, so completing the tutorial before delving any further into creating missions is highly recommended. The tutorial also explains how to install the tool, and how to add the mission so that it shows up in Prepar3D®.  
Although the mission system is fundamentally data driven, there is the option of creating custom actions that initiate SimConnect programming components, thus allowing complex programming support if that is required.

This section also includes a document on flight files. Normally these are used to save off and restore the current state of a session, but they can be edited by external tools or even created entirely by an external application -- in both cases to initiate the simulation at a point determined by the external tool or application.
Mission Creation

SimObject Creation Kit

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

DirectX 9 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\Core Utilities Kit\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

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 LC\LearningCenter.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.0 to be installed first. Install this from: http://www.microsoft.com/downloads/en/details.aspx?FamilyID=0a391abd-25c1-4fc0-919f-b21f31ab88b7&displaylang=en

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

If developing using the Windows Vista or Windows 7 operating system, 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 for Prepar3D® running on Windows XP is stored in:


>C:\Documents and Settings\<user name>\Application Data\Lockheed Martin\Prepar3D

For Windows Vista and Windows 7, application data is stored in:


C:\Users\<user name>\AppData\Roaming\Lockheed Martin\Prepar3D

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. This is done In Windows XP by opening My Computer/Tools menu/Folder Options/View tab and select Show Hidden Files and Folders. In Windows Vista or 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\LockheedMartin\Prepar3D

For computers using a 64-bit architecture the registry key information for the 32 bit Prepar3D application is here:

>HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\LockheedMartin\Prepar3D

Development Software

Visual Studio 2010 or Visual Studio 2010 Express Edition can be used to develop SimConnect client applications. For more information on the Express Edition, check out the following websites:

www.microsoft.com/vstudio/express

blogs.msdn.com/b/coding4fun/

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=en

For 64-bit operating systems:

http://www.microsoft.com/downloads/en/details.aspx?familyid=BD512D9E-43C8-4655-81BF-9350143D5867&displaylang=en

Forums

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: http://www.prepar3d.com/forum-5/

Generating GUIDs

A number of the SDK components require GUIDs (globally unique identifiers). A tool to generate these is included with both Visual Studio and Visual Studio Express. Alternatively, you can download the GUIDGEN tool from:

http://www.microsoft.com/downloads/details.aspx?familyid=94551f58-484f-4a8c-bb39-adb270833afc&displaylang=en

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

When running Prepar3D® with multiple monitors, there can be synchronization issues with the screens. There are two settings that can be added to the display.cfg file to help correct this (although setting them to TRUE can lead to some artifacts, such as tearing):

ForceVSync (default is FALSE) which, when set to TRUE, prevents the rendering on one monitor waiting for the rendering of another to finish, in Window mode.

ForceFullScreenVSync (default is TRUE) which, when set to TRUE, prevents the rendering on one monitor waiting for the rendering of another to finish, in FullScreen mode.

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 [Display] section, the following setting is new to the SP2 release:

ShadowMappingQuality (set to 0=off, 1=Low, 2=High, 3=Auto - the default is "Auto"). The "Low" setting for the shadow mapping refers to the shadow mapping filter present in the RTM version of Prepar3D®. The "High" setting refers to a newer, higher-quality shadow mapping filter. By default, the higher-quality filter is applied if the Graphics slider in the Settings dialog is set to High or Ultra High. Use this configuration setting to override the default behavior.

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 flight from the beginning (the default), 1=end the flight, 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 missions), or the flight 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 C:\Users\<user name>\Documents\Prepar3D 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 Minimum Hardware Configuration section applies to a client machine, developers of solutions for Prepar3D® may well appreciate a more powerful and larger computer. The SDK Setup Options show how to change the default installation folder. The Command Line Switches section enables the simulation to be started with a specific mission 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.


Minimum Hardware Configuration

In order to run an Prepar3D® client, the following minimum hardware is recommended:


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
-devThis switch has been deprecated.Prepar3D -dev
"-flt:path_to_mission.flt"Loads the named flight 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 flight file is the last entry on the command line. Prepar3D "-flt:Missions\Airline Pilot\Monsoon\Monsoon.flt"
-mp The simulator will start in "host a free flight session" multiplayer mode, with the Multiplayer Dialog visible. Prepar3D -mp
"-mp:path_to_mission.flt"Starts the simulator in "host a multiplayer mission" mode, using the mission flight 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 pace start\Reno MP pace 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 run (mission or free flight). 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 config dirs with the specified directory. The 3 directories that get overriden are:
  • c:\Users\YOURALIAS\AppData\Roaming\Lockheed Martin\Prepar3d\
  • c:\Users\YOURALIAS\AppData\Local\Lockheed Martin\Prepar3d\
  • c:\ProgramData\Lockheed Martin\Prepar3d\
All files that would be written or read from those 3 directories will now be redirected to the provided directory. This includes the Prepar3d.cfg and SimConnect.xml files.
Prepar3d.exe -cfgdir:d:\Replacement\Directory\
"-net:path_and_filename.cfg This switch allows starting a multiplayer or multi-channel session from the command line. This is the only way to start a multi-channel session. 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 and Multi-Channel Configuration Files topic for more information.
Prepar3d.exe -net:d:\IGConfig\MPHost.cfg
Prepar3d.exe -net:d:\IGConfig\MPUser2.cfg
Prepar3d.exe -net:d:\IGConfig\IGMaster.cfg
Prepar3d.exe -net:d:\IGConfig\IGSlave3.cfg
"-ig:path_and_filename.xml" This switch allows overriding the default SimIG.XML file with the file specified.

See the Sample Network and Multi-Channel Configuration Files topic for more information.
Prepar3d.exe -ig:d:\IGConfig\SimIG_2x2AutoGrid.xml -net:d:\IGConfig\IGMaster.cfg

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 flight and mission 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, flight and mission 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\Core Utilities Kit\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 table shows an example manifest file, with one single player and one multiplayer scenario.

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
NameThe name of the scenario (mission, tutorial, etc.), to appear in the UI of the launcher. This is the only required field.
DescriptionDescription of the scenario.
IsMultiplayerSet to True for a multiplayer mission, False otherwise.
ImagePath to an image to display in the launcher UI. Images must be .bmp files and should be 380 x 232 pixels.
FltFilePath to the flight file for the scenario. A mission file will be referenced from the flight file.
SceneryPath to the folder containing the alternative scenery and terrain configuration files.


Copyright 2011 Lockheed Martin