Introduction
.jpg)
ESP SDK Overview
The Microsoft® ESP™ SDK is the core component of the ESP product. ESP 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, ESP.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 ESP. ESP 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. Finally there is a section on Online Tutorials, each of which contains a sample that can be run in conjunction with ESP. There are also many tutorials included in this documentation.
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\Microsoft ESP\1.0\SDK\. The SDK is divided into four kits:
- Core Utilities Kit
- Environment Kit
- Mission Creation Kit
- SimObject Creation Kit
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.
| SimConnect SDK | The SimConnect SDK is the programmer's interface to ESP. 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 ESP, 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.
| 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 ESP 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 ESP 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 ESP. 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 ESP, 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 ESP 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 ESP 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 ESP 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 ESP. 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.
| 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 ESP. 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 Flight Files |
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.
| 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 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 ESP, 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 ESP, 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 ESP. Very complex gauges have been developed exclusively using the ACE tool and XML, including the GPS systems shipped with ESP. 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.). The 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. 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. |
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 |
Hints and Tips
Installation Requirements
Some of the SDK tools require the ESP runtime to be present on the same computer. It is good practice to install the SDK to a computer with the ESP runtime already installed, and then perhaps move files such as ESPSDK.chm 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 2.0 to be installed first. Install this from: https://www.microsoft.com/downloads/details.aspx?FamilyID=0856EACB-4362-4B0D-8EDD-AAB15C5E04F5&displaylang=en
Installation to a non-default folder
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 ESP.exe at least once first (as the tool requires certain registry entries to be present), and that the ESP runtime has been installed to the same computer.
Application Data Folders
If developing using the Windows Vista 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 ESP running on Windows XP is stored in:
C:\Documents and Settings\<user name>\Application Data\Microsoft\ESP
For Windows Vista, application data is stored in:
C:\Users\<user name>\AppData\Roaming\Microsoft\ESP
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 open up Windows Explorer, select Organize/Folder and Search options then select Show Hidden Files and Folders.
Development Software
Visual C++ 2005 or Visual C++ 2005 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
www.msdn.microsoft.com/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:
For 64-bit operating systems:
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 ESP.
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:
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. |
Configuration Settings
When running ESP 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 ESP.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 ESP.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 ESP. 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 ESP.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.
Solution Deployment
There are a number of features of ESP designed to aid in the deployment of a solution (for example, a tutorial) to an audience under more controlled circumstances than just running the ESP.exe. The Minimum Hardware Configuration section applies to a client machine, developers of solutions for ESP may well appreciate a more powerful and larger computer. The 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 ESP client, the following minimum hardware is recommended:
- Operating System: Windows XP SP2 or Windows Vista.
- Memory: 1 GByte.
- Processor: 2.0 GHz (single core).
- Hard Drive: 20 GB free hard drive space.
- Other: DirectX9 Hardware compatibility, Audio Card with speakers or headphones.
- Video Card: DirectX9 compliant video card or greater, with 128MB video RAM and Shader Model 1.1 or higher.
Setup Options
The default installation directory is specified in the setup.iss file that is used by the setup programs to install ESP.
| [{55B54DBC-B218-49BB-B664-75B1D0FEDB84}-DlgOrder] Dlg0={55B54DBC-B218-49BB-B664-75B1D0FEDB84}-MSOptionsDlg-0 Count=2 Dlg1={55B54DBC-B218-49BB-B664-75B1D0FEDB84}-SdWelcome-0 [{55B54DBC-B218-49BB-B664-75B1D0FEDB84}-MSOptionsDlg-0] SetupDir=C:\Program Files\ESP\Microsoft ESP\1.0 [{55B54DBC-B218-49BB-B664-75B1D0FEDB84}-SdWelcome-0] Result=0 |
Do not make any changes to this information. |
| SetupDir=C:\Program Files\Microsoft ESP\1.0 | The default installation directory, change this if necessary. |
Installation of the ESP runtime is initiated by the program launcher.exe, on DVD disk 1. To install the runtime silently (that is, without any progress bar and without any splash screens) use the following command:
launcher /s
To change the install directory for silent install edit the answer file (setup.iss -- also on DVD disk 1) and change both SetupDir parameters to the new installation folder. The setup.iss file needs to reside in the same directory as setup.exe. For silent install to work all of the files on the three DVDs must be copied to a single folder on a network share, and not on separate DVD disks. To install the runtime quietly -- that is without splash screens but with a progress bar, and with prompts to insert the second and third DVD disks, use the following command:
launcher /z "/Q /I'install directory'"
Note the single quotes around the install directory. Quiet mode can be done either from a share, or from DVD disks.
For the ESP SDK, there is a single option to install the SDK silently:
setup.msi /s
The purpose of providing these options is to enable solution providers to add their own branding to their completed solution.
Command Line Switches
ESP.exe can be initiated from a command line with an optional set of switches. This enables other tools, such as the ESPLauncher, to start ESP.exe with some specific settings. Some of these switches can also be used on a running instance of ESP.exe, so, for example, "dev" mode can be set by typing "esp –dev" into a command window and the simulation will switch into that mode. The command line is reinterpreted each time one is entered, so not entering the -dev switch into a command line while the simulation is running in dev mode, for example, will turn off dev mode. 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).
| -dev | Turns off the Enforce Flight Realism flag, and enables most of the menu items that are disabled when this flag is set. The Enforce Flight Realism flag is set by default to ensure a realistic flight experience by the user. However when developing a component, this enforcement can become a hindrance, so setting dev mode allows low realism settings to enable the development of an add-on. | ESP -dev |
| "-flt:path_to_mission.flt" | Loads the named flight file. The path can be relative to the root folder containing ESP.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. | ESP "-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. | ESP -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 ESP.exe. | ESP "-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. | ESP -mpjoin |
| "-mpplayer:LAN Name" | Skips the login screen and uses the player name provided by the command line. | ESP -mpjoin "-mpplayer:Trainee Pilot One" ESP -mp "-mpplayer:Trainee Pilot One" ESP "-flt:Missions\Airline Pilot\Monsoon\Monsoon.flt" "-mpplayer:Trainee Pilot One" |
| -mpplayer | Skips the login screen and uses the player name provided in the ESP.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. | ESP -mpjoin -mpplayer ESP -mp -mpplayer ESP "-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 ESP). If either of the files is not present in the folder, the folder does not exist or is not writable, then ESP 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 ESP "-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. |
ESP "-Scenery:C:\Alternate Config Folder" |
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 ESP 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, ESPLauncher.exe, is included with the SDK, along with its source code in order to enable developing it further for specific applications. An ESP 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 launcher program is installed along with the SDK into the Microsoft ESP/1.0/ESPLauncher 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. The sample source code and project for the launcher is installed into the SDK\Core Utilities Kit\SimConnect SDK\Samples\ESPLauncher folder.
Manifest File Format
The following table shows an example manifest file, with one single player and one multiplayer scenario.
.jpg) |
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.
| 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. |
Online Tutorials
The following tutorials are available from the MSDN Code Gallery. These tutorials include the necessary documentation, source files and resource files that are required to run a sample with ESP. In addition to these, other tutorials may be available from the Code Gallery.
| Aircraft Checklist | Based on the start-up checklist for the Cessna C172, this sample shows how to implement three variations of an aircraft checklist, categorized as "lead", "practice", and "perform". In the lead scenario, the instructor tells the student what to do at each step. In the practice scenario, the instructor introduces the task and then only gives feedback when a step is executed out of sequence. In the perform scenario, the instructor introduces the task and gives no feedback until the end: completed or failed. At a technical level the sample shows how to integrate a SimConnect application with the XML-based mission system. |
| New Airport | In this tutorial the complete process of adding a new airport to the simulated world of ESP is explained. This includes flattening the ground, excluding autogen (buildings and vegetation) and vector data (roads, streams and similar linear features). It involves adding an airport with runways, taxiways, and instrument landing equipment, and finally integrating the airport with the ATC and AI traffic systems of ESP. |
| Shared C++ Gauges | The shared clock sample shows how to create a gauge in a C++ library that will work in the shared cockpit multiplayer mode. In other words, if one of the two players in the shared cockpit changes the state of a gauge, the other player will see the change without having to do anything. The sample implements a simple clock and stopwatch gauge to demonstrate the techniques involved. The source code is well commented to enable it to be used as the basis for developing shared gauges. |
| Editing Flight Files | Flight files are used to save and restore the state of the ESP simulation. This sample, Dinged Hornet, shows how to place a damaged F-18 anywhere in the world, and begin the simulation from there. The sample uses a previously saved flight file, and a managed code tool, to set the scenario conditions and initiate a call to ESP. |
.jpg)