SimObject API References

2
Contents
Related Links

Getting Started

Types.h

Includes common data types found throughout the ISimObject SDK.

PSaveLoadCallback() – Function pointer for state save/load (.FXML files). This pointer is passed to each ISimulation when it's time for save/load Section names will automatically be constructed as: [SectionName.Instance.SimObjectID] allowing for multiple instances of a system (e.g. multi-engines) Constructed section names are limited to a maximum of 128 characters. SIM_DATA_TYPE allows saving either numeric or string data.

typedef HRESULT (STDMETHODCALLTYPE *PSaveLoadCallback)(__in LPCTSTR pszSection, __in unsigned int uInstance, __in LPCTSTR pszKeyword, __inout void* pvVal, __in const SAVED_DATA_TYPE eDataType);

The property type enum used in the property string->ID lookup. See IBaseObject.

typedef enum
{
    PROPERTY_TYPE_EVENT,
    PROPERTY_TYPE_EVENT_WITH_SUBSTRING_INPUT,
    PROPERTY_TYPE_EVENT_VECTOR,
    PROPERTY_TYPE_EVENT_STRING,
    PROPERTY_TYPE_DOUBLE,
    PROPERTY_TYPE_DOUBLE_WITH_SUBSTRING_INPUT,
    PROPERTY_TYPE_STRING,
    PROPERTY_TYPE_VECTOR,
    NUM_PROPERTY_TYPES,
} PROPERTY_TYPE;

Enum definition for data types used when saving / loading. See ISimulation and PSaveLoadCallback.

typedef enum
{
    SAVED_DATA_TYPE_DOUBLE,
    SAVED_DATA_TYPE_STRING,
    NUM_SAVED_DATA_TYPES
} SAVED_DATA_TYPE;

Enum definition for the various modes in which an Artificially Intelligent (AI) object can be.

typedef enum
{
    UNITMODE_SLEEP,
    UNITMODE_ZOMBIE,
    UNITMODE_WAYPOINT,
    UNITMODE_TAKEOFF,
    UNITMODE_LANDING,
    UNITMODE_TAXI,
    UNITMODE_WORKING,
    UNITMODE_WAITING,
} UNITMODE_TYPE;

A BasicWaypoint is generally used to define a point along a path. It is used primarily by the AI system.

class BasicWaypoint
{
public:
    DXYZ vLonAltLat; //Lat/Lon (Radians), Alt (Feet)
    double dHeading; //Radians
};

Versioning Code

Compiled with the PDk and ISimObject interfaces will be expected to function in subsequent versions of the SDK. To do so, each interface name is appended with the version number, and is derived from the preceding version. The preceding versions will be maintained intact in the Legacy subfolder. It is recommended that all new code utilizes the latest version when defining your objects and each QueryInterface supports all versions. Internal to Prepar3D, the earliest version possible will be used.

ISimObjectManager

The ISimObjectManager is an application level manager that handles registration of simobject implementation classes and their associated properties. The ISimObjectManager is created on app startup and destroyed on shutdown.

RegisterSimulationCategory

Registers an ISimObject implementation at load time with: unique ID, friendly category name (e.g. "airplane"), and factory function pointer.

STDMETHOD (RegisterSimulationCategory) (__in GUID guidCategory, __in LPCTSTR pszCategoryName, __in __notnull PSimCreateFunc pcbCreateFunction)                PURE;

i.e. associates the category guid and the creation function.

"pszCategoryName" is a high-level categorization used primarily for UI (e.g. "airplane")

RegisterSimulationProperty or Event

Property "simvar" and "event" registrations. For a specific SimObject implementation (guid), associates: property string name, units, and callback pointer (defined above). There are 8 registration types: a "trigger/event property" and a "get property" for doubles, vectors, strings, and doubles that take a secondary string input at runtime. See Types.h for the callback definitions.

// "double"
STDMETHOD (RegisterProperty) (__in GUID guidCategory, __in LPCTSTR pszPropertyName, __in LPCTSTR pszPropertyBaseUnits, __in __notnull PPropertyCallback pcbProperty)                 PURE;
 
// "vector" (DXYZ)
STDMETHOD (RegisterProperty) (__in GUID guidCategory, __in LPCTSTR pszPropertyName, __in LPCTSTR pszPropertyBaseUnits, __in __notnull PPropertyVectorCallback pcbProperty)           PURE;
 
// "string"
STDMETHOD (RegisterProperty) (__in GUID guidCategory, __in LPCTSTR pszPropertyName, __in __notnull PPropertyStringCallback pcbProperty)                                              PURE;
 
// "double" (with secondary substring input)
STDMETHOD (RegisterProperty) (__in GUID guidCategory, __in LPCTSTR pszPropertyName, __in LPCTSTR pszPropertyBaseUnits, __in __notnull PPropertyCallbackWithSubString pcbProperty)    PURE;
 
// "event"
STDMETHOD (RegisterProperty) (__in GUID guidCategory, __in LPCTSTR pszPropertyName, __in LPCTSTR pszPropertyBaseUnits, __in __notnull PEventCallback pcbEvent, __in EVENTTYPE eType) PURE;
 
// "event vector"
STDMETHOD (RegisterProperty) (__in GUID guidCategory, __in LPCTSTR pszPropertyName, __in LPCTSTR pszPropertyBaseUnits, __in __notnull PEventVectorCallback)                          PURE;
 
// "event string"
STDMETHOD (RegisterProperty) (__in GUID guidCategory, __in LPCTSTR pszPropertyName, __in __notnull PEventStringCallback)                                                             PURE;
 
// "event" double (with secondary substring input)
STDMETHOD (RegisterProperty) (__in GUID guidCategory, __in LPCTSTR pszPropertyName, __in LPCTSTR pszPropertyBaseUnits, __in __notnull PEventCallbackWithSubString pcbEvent)          PURE;

Property Examples

This SDK enables a SimObject solution developer to create custom "properties" for their SimObject implementations. These are similar in nature to the legacy Simulation Variables found here. For more information on how to register your properites please refer to SimObject API Getting Started. Properties can be strings, events/triggers, doubles and vectors.

Strings

//String property callback
typedef HRESULT (STDMETHODCALLTYPE *PPropertyStringCallback)(__in const ISimObject& Sim, __out char* szProperty, __in UINT uStringLength, __in int iIndex); //Returns string

Events/Triggers

//Sample PEventCallback function
/*static*/ STDMETHODIMP MySimObject::MyJoyStickEvent(__in ISimObject& Sim, __in double dProperty, __in int iIndex)
{
    static_cast(Sim).m_dMyJoyStickEvent = dProperty;
    return S_OK;
}

Double

//Sample PPropertyCallback function
/*static*/ STDMETHODIMP MySimObject::GetMyDoubleProperty(__in const ISimObject& Sim, __out double& dProperty, __in int iIndex)
{
    dProperty = static_cast(Sim).m_dMyDoublePropertyValue;
    return S_OK;

}

Vector

//Sample PPropertyVectorCallback function
/*static*/ STDMETHODIMP MySimObject::GetMyVectorProperty(__in const ISimObject& Sim, __out DXYZ& vProperty, __in int iIndex)
{
    vProperty = static_cast(Sim).m_vMyVectorPropertyValue;
    return S_OK;


}

Realism Settings

These are global settings configured in the Prepar3D.cfg and the Realism UI.

STDMETHOD_(float, GetRealismSetting)()            const PURE;     //Percent
STDMETHOD_(BOOL,  IsCrashDetectionOn)()           const PURE;
STDMETHOD_(BOOL,  IsCollisionBetweenObjectsOn)()  const PURE;
STDMETHOD_(float, GetCrashToleranceScalar)()      const PURE;     //Percent

GetRealismSetting() – The user-selected general realism scalar, where 0.0 is "easy" and 1.0 is "real". This can be used to scale your implementation as appropriate.

IsCrashDetectionOn() – The user-selected flag that dictates whether to process a crash or not.

IsCollisionBetweenObjectsOn() – The user-selected flag forw whether to detect crashes between simobjects or not.

GetCrashToleranceScalar() – The user-selected scalar for determining crash tolerance.

World Constants

World Constants are constant values describing the Earth atmosphere and geometry.

NOTE: While this is accessed through IBaseObject, these values will be constant for all SimObjects, and a single static copy could be shared across multiple instances.

STDMETHOD (GetWorldConstants)(__out WorldConstants&) const PURE;

Data Structure definition.

class WorldConstants
{
    public:

        //Atmosphere
        float m_fSpecificGasConstant;            //aka R
        float m_fSpecificHeatRatio;              //aka Gamma (Cp/Cv for air (specific heat ratio)
        float m_fStandardSeaLevelDensity;        //slugs/ft^3
        float m_fStandardSeaLevelTemperature;    //Rankine
        float m_fStandardSeaLevelPressure;       //Lbs/SqFt

        //Gravity
        float m_fGravitySeaLevel;                //ft/s^2

        //Radii
        double m_dPolarRadius;                   //Feet
        double m_dEquatorialRadius;              //Feet
};

GetObject

Gets another IBaseObject ref for a given id.

STDMETHOD (GetObject)(__in UINT idObject, __out IBaseObject** ppObject);    const PURE;

GetUserObject

Gets an IBaseObject ref for the current user object.

Note: If the user object is the Viewer and there is a previous user object, this will return the previous user object. Otherwise, it will return the Viewer.

STDMETHOD (GetUserObject)(__out IBaseObject** ppObject);    const PURE;

GetUnitCode

Decodes a string units to its integer ID. This can be useful to get at initialization as it is less performance to query properties using the string version. e.g. "feet per second" to ID.

STDMETHOD (GetUnitCode)(in LPCTSTR pszPropertyUnits, __out int& iUnitCode);    const PURE;

GetObjectInRadius

Returns a list of object IDs for a given radius.

nObjects: IN: the max number of elements requested. This must be no smaller than the size of the array pointed to by rgObjectIDs

nObjects: OUT: the actual number of objects found

rgObjectIDs: address of array in which object IDs are returned.

NOTE: It is the caller's responsibility to allocate the array's required memory.

STDMETHOD (GetObjectsInRadius)(__in const DXYZ& vLonAltLat, __in float fRadiusFeet, __inout UINT& nObjects, __out UINT* rgObjectIDs) const PURE;

IBaseObject

The IBaseObject is an interface to the Prepar3D-side SimObject that your ISimObject is attached to. One of its primary purposes is to serve as a proxy to your simulation for representing position within the Prepar3D world. It also serves as the manager for data being passed from your SimObject implementation, such as animation and gauge states. Additional functionality is listed below:

Registering Simulations Properties

The following functions add the ability to query on the IBaseObject for registered properties (enabling SimObject API -> SimObject API queries). There are three types of properties to query for: doubles, vectors, and strings.

The general argument list has two inputs (property id and units id) and then the output. The two inputs can be specified either with their string version (less performance) or their integer ID. Units do not apply to strings. The string-to-id is also new in GetUnitCode() above and GetPropertyCodeAndIndex().

GetPropertyCodeAndIndex

GetPropertyCodeAndIndex converts a string property (e.g. "EngineRpm:1") to their integer IDs.

STDMETHOD (GetPropertyCodeAndIndex)(__in PROPERTY_TYPE eType, __in LPCTSTR pszPropertyName, __out int& iPropertyCode, __out int& iIndex) const PURE;

GetProperty

Each property type (double, vector, string, and double with secondary input) has three GetProperty implementations depending on whether the caller has the actual int property code and unit type or their string versions, with the exception of string properties which have no method with a unit type specified.

Note: For better performance reasons, it is advised to use the int codes as much as possible during runtime. The codes are guaranteed to be consistent for the duration of the Prepar3D application instance.

//Get Property - Doubles
STDMETHOD (GetProperty)(__in int     iPropertyCode,   __in int      iUnitCode,   __out double& dProperty, __in int index = 0) const PURE;   //Doubles
STDMETHOD (GetProperty)(__in LPCTSTR pszPropertyName, __in int      iUnitCode,   __out double& dProperty, __in int index = 0) const PURE;   //Doubles
STDMETHOD (GetProperty)(__in LPCTSTR pszPropertyName, __in LPCTSTR  pszUnitCode, __out double& dProperty, __in int index = 0) const PURE;   //Doubles
 
//Get Property - Vectors
STDMETHOD (GetProperty)(__in int     iPropertyCode,   __in int      iUnitCode,   __out DXYZ&   dProperty, __in int index = 0) const PURE;   //Vectors
STDMETHOD (GetProperty)(__in LPCTSTR pszPropertyName, __in int      iUnitCode,   __out DXYZ&   dProperty, __in int index = 0) const PURE;   //Vectors
STDMETHOD (GetProperty)(__in LPCTSTR pszPropertyName, __in LPCTSTR  pszUnitCode, __out DXYZ&   dProperty, __in int index = 0) const PURE;   //Vectors
 
//Get Property - Strings
STDMETHOD (GetProperty)(__in int     iPropertyCode,   __out LPTSTR pszProperty, __in UINT uLength,       __in int index = 0) const PURE;   //Strings
STDMETHOD (GetProperty)(__in LPCTSTR pszPropertyName, __out LPTSTR pszProperty, __in UINT uLength,       __in int index = 0) const PURE;   //Strings
 
//Get Property - Doubles (with secondary substring input)
STDMETHOD (GetProperty)(__in int     iPropertyCode,   __in LPCTSTR pszSecondarySubstring, __in int      iUnitCode,   __out double& dProperty, __in int index = 0) const PURE;   //Doubles
STDMETHOD (GetProperty)(__in LPCTSTR pszPropertyName, __in LPCTSTR pszSecondarySubstring, __in int      iUnitCode,   __out double& dProperty, __in int index = 0) const PURE;   //Doubles
STDMETHOD (GetProperty)(__in LPCTSTR pszPropertyName, __in LPCTSTR pszSecondarySubstring, __in LPCTSTR  pszUnitCode, __out double& dProperty, __in int index = 0) const PURE;   //Doubles

Registering Simulations Callbacks

RegisterSimulation registers an ISimulation callback for real-time updates (discussed in Creating Behaviors.)

STDMETHOD (RegisterSimulation)(
        __in __notnull ISimulation* pSimulation, Address of simulation system
        float fRateHz) PURE; Specified iteration rate

Object Mode Monitoring

GetMode() - Returns bitwise flags for the current modes of the SimObject.

STDMETHOD_(int, GetMode)() const PURE;

Possible flags are defined in ISimObject.h:

#define SIMOBJECT_MODE_PAUSE            0x00000001
#define SIMOBJECT_MODE_SLEW             0x00000002
#define SIMOBJECT_MODE_DISABLED         0x00000004
#define SIMOBJECT_MODE_CRASH            0x00000008
#define SIMOBJECT_MODE_FREEZE_POSITION  0x00000010
#define SIMOBJECT_MODE_FREEZE_ATTITUDE  0x00000020
#define SIMOBJECT_MODE_FREEZE_ALTITUDE  0x00000040
#define SIMOBJECT_MODE_FREEZE_LATLON    0x00000080
#define SIMOBJECT_MODE_SIMDIRECTOR      0x00000100

SetCrashMode() - Should be called when it is desired to put Prepar3D into "crash" mode. By default, the application will go through it's crash cycle and reset. It is the developer's responsibility to program the behavior of the object when crash in crash mode.

Note: It is important that an object continues to call SetCrashMode() while in a crashed state, as this is what advances the crash mode sequence which results in resetting the object.

STDMETHOD (SetCrashMode)(double dDeltaT) PURE;

Connecting to the Sim.cfg

GetTitle returns the unique string that indentifies this object.

STDMETHOD (GetTitle) (__out LPTSTR pszCfgTitle,__in unsigned int uLength) const PURE;

GetCfgDir returns a fully qualified path to the object's content path. This is generally the folder where the sim.cfg (or aircraft.cfg) lives.

STDMETHOD (GetCfgDir) (__out char* pszCfgDir, __in unsigned int uPathLength) const PURE;

GetCfgFilePath returns a fully qualified path to the sim.cfg file.

STDMETHOD (GetCfgFilePath) (__out char* pszCfgFile, __in unsigned int uPathLength) const PURE;

GetCfgSectionName returns the relevant section name in the sim.cfg. e.g. [fltsim.1].

STDMETHOD (GetCfgSectionName)(__out char* pszCfgFile, __in unsigned int uLength) const PURE;

Position Updating

GetPosition gets the current world relative position and velocity from the Prepar3D-side SimObject. This will provide the valid state upon initialization, as well as when another system such as a UI element or slew changes the position.

STDMETHOD (GetPosition)(
        __out DXYZ& vLonAltLat, Longitude, altitude, latitude (radians)
        __out DXYZ& vPHB, Pitch, heading, bank (radians)
        __out DXYZ& vLonAltLatVel, Longitude, altitude, latitude velocity (feet / second)
        __out DXYZ& vPHBVel) const PURE; Pitch, heading, bank velocity (radians / second)

SetPosition sets the current world relative position and velocity to the Prepar3D-side SimObject.

STDMETHOD (SetPosition)(
__inconst DXYZ& vLonAltLat, Longitude, altitude,latitude (radians)
__inconst DXYZ& vPHB, Pitch, heading, bank (radians)
__inconst DXYZ& vLonAltLatVel, Longitude, altitude, latitude velocity (feet / second)
__inconst DXYZ& vPHBVel) PURE; Pitch, heading, bank velocity (radians / second)
__in BOOL bIsOnGround) PURE; Flag indicating if the object is on the ground. This is important during terrain updates.
__in double dDeltaT The time between object updates used to track how much time has accumulated between camera frames

World / Environment Updating

GetSurfaceInformation provides current surface information for the requested offset from the model center. See the ISimObject.h for the definition of the SurfaceInfo data structure. A return value of E_FAIL means that Prepar3D's terrain system failed to process the request properly. This could happen if it is not initialized fully.

STDMETHOD (GetSurfaceInformation)(
__out SurfaceInfo& SurfaceInfo, Reference to local SurfaceInfo data structure
__in const FXYZ* pvOffsetFeet) PURE; The offset from model enter. A value of NULL will use the model's center

GetSurfaceElevation provides current surface elevation (above Mean Sea Level) for the requested offset from the model center. This will be more efficient than GetSurfaceInformation when only the elevation is needed. A return value of E_FAIL means that Prepar3D's terrain system failed to process the request properly. This could happen if it is not initialized fully.

STDMETHOD (GetSurfaceElevation)(
__out float& fElevationFeet, Reference to the elevation variable (Feet)
__in const FXYZ* pvOffsetFeet) PURE; The offset from model enter. A value of NULL will use the model's center

GetWeatherInformation provides current weather information for the object's current position. See the ISimObject.h for the definition of the WeatherInfo data structure. A return value of E_FAIL means that Prepar3D's weather system failed to process the request properly. This could happen if it is not initialized fully.

STDMETHOD (GetWeatherInformation)(
__out WeatherInfo& WeatherInfo) PURE; Reference to local WeatherInfo data structure

GetMagneticVariation returns the object's current magnetic variation in radians. A positive is value is "east".

STDMETHOD_(float, GetMagneticVariation)() const PURE;

Effect Triggering

VisualEffectOn is used to turn visual effect on. The out parameter allows you to hold a reference to a visual effect to subsequently turn off. See Creating Special Effects.

STDMETHOD(VisualEffectOn) (
__in __notnull char* pszEffectName, File name for requested visual effect
__in const FXYZ* pvOffsetFeet, The offset from model center. A value of NULL will use the model's center
__out void** ppEffect) PURE; Reference pointer for turning the visual effect off with VisualEffectOff()

VisualEffectOff turns off a visual effect.

STDMETHOD(VisualEffectOff)(
__in __notnull void* pEffect) PURE; Reference pointer obtained in out parameter of VisualEffectOn()

TriggerSound triggers a sound configured in the object's sound.cfg.

STDMETHOD (TriggerSound)(
__in __notnull char* pszName, Sound reference name from Sound.cfg (see Sound Configuration Files)
BOOL bOn) PURE; Turns sound on or off

TriggerContactSound triggers a sound specifically for a ground contact point.

STDMETHOD (TriggerContactSound)(
__in __notnull char* pszName, Sound reference name from Sound.cfg (see Sound Configuration Files)
__in const FXYZ* pvOffset, The offset from model center. A value of NULL will use the model's center
float fImpactSpeed) PURE; Speed used by sound system to scale sound

Proffered Services

A proffered service is a simulation subsystem implemented within Prepar3D, but made available to SimObjects implemented with this SDK. The code and its associated data are maintained by the Prepar3D code. Your implementation simply needs to invoke the use of it. The service is identified by a reference GUID.

Note that any available services will be documented separate from this SDK.

LoadServiceConstantData invokes the loading of the relevant constant data. This should be called from your SimObject's LoadConstantData();

STDMETHOD (LoadServiceConstantData)(__in REFGUID guidService)                PURE;

UnLoadServiceConstantData causes Prepar3D to unload the relevant constant data. This should be called from your SimObject's UnLoadConstantData();

STDMETHOD(UnLoadServiceConstantData)(__in REFGUID guidService)                PURE;

CreateServiceInstance invokes the instantiation of the service, based on the loaded constant data. This should be called from your SimObject's LoadDynamicData();

STDMETHOD(CreateServiceInstance) (__in REFGUID guidService)                PURE;

DestroyServiceInstancecauses Prepar3D to destroy the instance of the service. This should be called from your SimObject's Deinit();

STDMETHOD(DestroyServiceInstance) (__in REFGUID guidService)                PURE;

UpdateServiceInstance is the real-time update of the service. Your SimObject is responsible for calling it with an accurate delta time.

STDMETHOD(UpdateServiceInstance) (__in REFGUID guidService,double dDeltaT)        PURE;

Miscellaneous

IsUser returns if the object is the user or not.

STDMETHOD_(BOOL, IsUser)() const PURE;

GetID() is the ID of the object. NOTE: "0" is an invalid ID

STDMETHOD_(UINT, GetId)()        const PURE;

GetMissionId() is the guid ID of the object defined in a mission file. NOTE: If the object is not spawned by a mission, the return will be E_FAIL and the ID will be GUID_NULL.

STDMETHOD_(GetMissionId)(GUID& guid)        const PURE;

DecrementHealthPoints(), GetHealthPoints(), and SetHealthPoints() allow for the application of damage points and to retrieve the current health of the object respectively. Positive points passed in will be decremented from current health points, to a limit of zero.

STDMETHOD (DecrementHealthPoints)(__in float fDamagePoints)       PURE;
STDMETHOD_(float, GetHealthPoints)()                        const PURE;
STDMETHOD_(void, SetHealthPoints)(float fHealthPoints)            PURE;

Destroy() is the command to destroy self. This will not be immediate, so it can be called from within itself. It will be destroyed as soon as the current simulation finishes.

STDMETHOD (Destroy)()        PURE;

Group Association ID can be used to set/get IDs for Friend/Foe or other types of groupings.

Note: Group association is arbitrary. It could be used for things like alliances or squadrons. Default is 0, which signifies a neutral grouping.

STDMETHOD_(UINT, GetObjectGroupAssociationId)() const PURE;
STDMETHOD_(void, SetObjectGroupAssociationId)(UINT uAssociationId)       PURE;

CheckCollision() will check if this object colliding with building or other SimObject. The eCollision should be checked for a positive collision, and ppUnkHitObject for whether it involved an (IUnknown) object.

Note: A return of S_OK does not mean there is a collision, only that the query operation encountered no errors

STDMETHOD (CheckCollision)(float fRadiusFeet, __out COLLISIONTYPE& eCollision,__out IUnknown** ppUnkHitObject)        const PURE;

Collision Enum is the result used in the collision detection queries, CheckCollision(). For collision services refer to ICollisionService.

typedef enum
{
    COLLISIONTYPE_NONE,
    COLLISIONTYPE_SIMOBJECT,
    COLLISIONTYPE_BUILDING,
    COLLISIONTYPE_TERRAIN,
    COLLISIONTYPE_OTHER,
}COLLISIONTYPE;

ISimulation

Interface to individual simulation subsystems.

Update() is called by Prepar3D at the iteration rate specified when this ISimulation interface is registered using RegisterSimulation() in the IBaseObject interface.

STDMETHOD (Update)(double dDeltaT) PURE;

SaveLoadState() is called when either saving or loading a Prepar3D scenario, aka "flight". The function pointer allows your code to save and load "name – value" pairs in the Prepar3D .fxml file. See the definition for PSaveLoadCallback and the supported data type enum SAVED_DATA_TYPE.

STDMETHOD (SaveLoadState)(__in __notnull PSaveLoadCallback pfnCallback, __in const BOOL bSave) PURE;

ISimObject

Interface from which object implementations must derive.

LoadConstantData() and UnloadConstantData() are where your object class should load and unload data from the disk. The return data is cached for subsequent instances of this same object.

STDMETHOD (LoadConstantData)(__inout void** ppConstantData) PURE; STDMETHOD (UnloadConstantData)(__inout void** ppConstantData) PURE;

LoadDynamicData() is called on each object instance. This would be an appropriate place to create the object's runtime subsystems.

STDMETHOD (LoadDynamicData)() PURE;

Init() is an appropriate place to initialize data and establish references between subsystems.

DeInit() can be used to release inter-system references prior to the object being destroyed.

STDMETHOD (Init)()                                              PURE;
STDMETHOD (DeInit)()                                            PURE;

OnModeChange() will be called whenever Prepar3D has detected a mode has changed (See Object Mode Monitoring).

STDMETHOD_(void, OnModeChange)(int bfNewModes)                  PURE;

OnPositionInit() will be called whenever Prepar3D has changed the position of this object outside of its own simulation implementation. Examples of this would be positioning from the User Interface, Slew Mode, or terrain resolution changing.

STDMETHOD_(void, OnPositionInit)()                              PURE;

OnSpeedInit() will be called whenever Prepar3D has changed the speed of this object outside of its own simulation implementation. This would occur normally if positioning from the User Interface.

STDMETHOD_(void, OnSpeedInit)(float fSpeed)                     PURE;

SupportsLabels() defines if the SimObject will or will not support labels to be displayed.

STDMETHOD_(BOOL, SupportsLabels)()                        const PURE;

SetSupportsLabels() requests this SimObject to support labels. Return S_OK if the new setting is accepted. If not, return an error code, such as E_FAIL. This value should maintain by this class and returned when requested by SupportsLabel(). You may choose for your class to not support labels. This setting will not override settings in the Traffic Settings.

STDMETHOD(SetSupportsLabels)(BOOL bOn)                         PURE;

ISimObjectAI

The ISimObjectAI interface is an interface on the AI "pilot" implementation for a simobject. A custom AI can be implemented on simobjects created using the ISimObject SDK. The interface may be accessed by systems such as the Traffic Manager or ATC.

UpdateSimulationFrame() – To be called from the simulation loop to keep the low level AI controllers in sync with the simulation.

STDMETHOD (UpdateSimulationFrame)(__in double dDeltaT)          PURE;

GetPilotMode() – Returns the current mode of the AI. See UNITMODE enums in Types.h.

STDMETHOD_(UNITMODE, GetPilotMode)() const                      PURE;

SetPilotMode() – Sets the current mode of the AI. See UNITMODE enums in Types.h.

STDMETHOD_(void, SetPilotMode)(UNITMODE eMode, BOOL bOn = TRUE) PURE;

Deactivate() – Disables the AI control.

STDMETHOD_(void, Deactivate)()                                  PURE;

Activate() – Enables the AI control.

STDMETHOD_(void, Activate)()                                    PURE;

SetWaypoint() – Sets the next waypoint for the AI to track to. See BasicWaypoint definition in Types.h.

STDMETHOD (SetWaypoint)(__in BasicWaypoint)                     PURE;

SetDesiredHeading() – Sets the heading to be maintained. (radians)

STDMETHOD (SetDesiredHeading)(double dTrueHeading)              PURE;

SetDesiredPitch() – Sets the pitch angle to be maintained. (radians)

STDMETHOD (SetDesiredPitch)(double dPitch)                      PURE;

SetDesiredSpeed() – Sets the desired speed to be maintained. (Indicated airspeed for aircraft) (Feet per second)

STDMETHOD (SetDesiredSpeed)(double dSpeed)                      PURE;

SetDesiredAltitude() – Sets the altitude to be maintained. (feet)

STDMETHOD (SetDesiredAltitude)(double dAltitudeMSL)             PURE;

IAircraftAIService

The IAircraftAIService should be implemented on any aircraft intended to be controlled by Prepar3D's internal AI Pilot.

DECLARE_INTERFACE_ (IAircraftAIServiceV01, IAIService)
{
    STDMETHOD_(float,  GetIndicatedAirspeed)()              const PURE;  //FPS
    STDMETHOD_(float,  GetTrueAirspeed)()                   const PURE;  //FPS
    STDMETHOD_(float,  GetCruiseSpeedTrue)()                const PURE;  //FPS
    STDMETHOD_(float,  GetMaxIndicatedAirspeed)()           const PURE;  //FPS
    STDMETHOD_(float,  GetMach)()                           const PURE;
    STDMETHOD_(float,  GetMaxMach)()                        const PURE;
    STDMETHOD_(float,  GetIndicatedAltitude)()              const PURE;  //Feet
 
    STDMETHOD_(float,  GetTotalWeight)()                    const PURE;  //Pounds
    STDMETHOD_(float,  GetEmptyRollingMomentOfInertia)()    const PURE;  //Slugs-Ft^2
    STDMETHOD_(float,  GetDynamicPressure)()                const PURE;  //PSF
    STDMETHOD_(float,  GetIncidenceAlpha)()                 const PURE;  //Radians
    STDMETHOD_(float,  GetIncidenceBeta)()                  const PURE;  //Radians
    STDMETHOD_(float,  GetBetaDot)()                        const PURE;  //Radians/sec
    STDMETHOD_(float,  GetRollRate)()                       const PURE;  //Radians
    STDMETHOD_(float,  GetSigmaSqrt)()                      const PURE;
    STDMETHOD_(float,  GetLongitudinalAccelerationBody)()   const PURE;  //Feet/sec^2
    STDMETHOD_(float,  GetLateralAccelerationBody)()        const PURE;  //Feet/sec^2
    STDMETHOD_(float,  GetVerticalAccelerationBody)()       const PURE;  //Feet/sec^2
 
    STDMETHOD_(BOOL,   IsEngineTypePiston)()                const PURE;
    STDMETHOD_(UINT,   GetEngineCount)()                    const PURE;
    STDMETHOD_(float,  GetGeneralEngineRPM)(int iEngine)    const PURE;
    STDMETHOD_(BOOL,   IsEngineRunning)(int iEngine)        const PURE;
    STDMETHOD_(float,  GetTotalFuelCapacity)()              const PURE;  //Gallons
    STDMETHOD_(float,  GetFuelWeightPerGallon)()            const PURE;  //Pounds/Gallon
    STDMETHOD_(float,  GetEstimatedFuelFlowLbsPerHour)()    const PURE;  //Pounds / Hour
    STDMETHOD_(void,   StartEngines)()                            PURE;
    STDMETHOD_(void,   ShutdownEngines)()                         PURE;
 
    STDMETHOD_(BOOL, GetParkingBrake)()                     const PURE;
    STDMETHOD_(void, TapBrakes)()                                 PURE;
    STDMETHOD_(void, SetBrakePosition)(int iBrake,float fPos)     PURE;  // none 0->1 full
    STDMETHOD_(void, SetParkingBrake)(BOOL bOn)                   PURE;
    STDMETHOD_(void, ExtendLandingGear)()                         PURE;
    STDMETHOD_(void, RetractLandingGear)()                        PURE;
 
    STDMETHOD_(BOOL,   IsTailDragger)()                     const PURE;
    STDMETHOD_(BOOL,   IsSeaPlane)()                        const PURE;
    STDMETHOD_(float,  GetMinTakeoffLength)()               const PURE;  //Feet
    STDMETHOD_(float,  GetMinLandingLength)()               const PURE;  //Feet
 
    STDMETHOD_(void, SetNavLights)                  (BOOL bOn)    PURE;
    STDMETHOD_(void, SetBeaconLights)               (BOOL bOn)    PURE;
    STDMETHOD_(void, SetLogoLights)                 (BOOL bOn)    PURE;
    STDMETHOD_(void, SetRecognitionLights)          (BOOL bOn)    PURE;
    STDMETHOD_(void, SetTaxiLights)                 (BOOL bOn)    PURE;
    STDMETHOD_(void, SetLandingLights)              (BOOL bOn)    PURE;
    STDMETHOD_(void, SetStrobeLights)               (BOOL bOn)    PURE;
    STDMETHOD_(void, SetPanelLights)                (BOOL bOn)    PURE;
    STDMETHOD_(void, SetCabinLights)                (BOOL bOn)    PURE;
};

GetIndicatedAirspeed() – Gets the indicated airspeed. (feet per second)

GetTrueAirspeed() – Gets the true airspeed. (feet per second)

GetCruiseSpeedTrue() – Gets the normal true airspeed in cruise. (feet per second)

GetMaxIndicatedAirspeed() – Gets the maximum speed (red-line). (feet per second)

GetMach() – Gets the current mach.

GetMaxMach() – Gets the maximum rated mach.

GetIndicatedAltitude() – Gets the indicated alituded, or altimeter. (feet)

GetTotalWeight() – Gets the current total weight, including fuel, passengers, and payload. (pounds)

GetEmptyRollingMomentOfInertia() – Gets moment of inertia around the longitudinal axis of the empty aircraft. (slugs – feet^2)

GetDynamicPressure() – Gets the dynamic pressure of the aircraft's free stream. (pounds per square feet)

GetIncidenceAlpha() – Gets the current angle-of-attack. (radians)

GetIncidenceBeta() – Gets the current sideslip angle. (radians)

GetBetaDot() – Gets the current rate of change of the sideslip angle. (radians per second).

GetRollRate() – Gets the current rate of roll. (radians per second)

GetSigmaSqrt() – Gets the square root of the density ratio (ambient density divided by standard sea level density).

GetLongitudinalAccelerationBody() – Gets the indicated airspeed. (feet per second)

GetLateralAccelerationBody() – Gets linear acceleration along lateral axis. (feet per second^2)

GetVerticalAccelerationBody() – Gets linear acceleration along vertical axis. (feet per second^2)

IsEngineTypePiston() – Returns TRUE if engine is piston type.

GetEngineCount() – Returns number of engines on aircraft.

GetGeneralEngineRPM() – Returns engine RPM.

IsEngineRunning() – Returns TRUE if engine is currently combusting.

GetTotalFuelCapacity() – Returns capacity of the aircraft. (gallons)

GetFuelWeightPerGallon() – Returns weight of each gallon. (pounds per gallon)

GetEstimatedFuelFlowLbsPerHour() – Returns typical fuel flow at cruise. (pounds per hour)

StartEngines() – Triggers engines to all start.

ShutdownEngines() – Triggers all engines to shut down.

GetParkingBrake() – Returns TRUE if parking brake is on.

TapBrakes() – Triggers a momentary tap of the brakes.

SetBrakePosition() – Sets the desired brake position. (percent, 0.0 – 1.0)

SetParkingBrake() – Triggers parking brake to be on/off.

ExtendLandingGear() – Triggers landing gear to extend.

RetractLandingGear() – Triggers landing gear to retract.

IsTailDragger() – Returns TRUE if the center gear is aft of the main gear.

IsSeaPlane() – Returns TRUE if the aircraft configured with float points.

GetMinTakeoffLength() – Returns estimated minimum runway length necessary for takeoff. (feet)

GetMinLandingLength() – Returns estimated minimum runway length necessary for landing. (feet)

SetNavLights() – Triggers navigation lights to be on or off.

SetBeaconLights() – Triggers beacon lights to be on or off.

SetLogoLights() – Triggers logo lights to be on or off.

SetRecognitionLights() – Triggers recognition lights to be on or off.

SetTaxiLights() – Triggers taxi lights to be on or off.

SetLandingLights() – Triggers landing lights to be on or off.

SetStrobeLights() – Triggers strobe lights to be on or off.

SetPanelLights() – Triggers panel lights to be on or off.

SetCabinLights() – Triggers cabin lights to be on or off.

IAirplaneAIService

The IAirplaneAIService should be implemented on any airplane intended to be controlled by Prepar3D's internal AI Pilot.

DECLARE_INTERFACE_ (IAirplaneAIServiceV02, IAirplaneAIServiceV01)
{
    //Airplane Specific
    STDMETHOD_(float,  GetStallSpeedDirty)()               const PURE;  //FPS
    STDMETHOD_(float,  GetStallSpeedClean)()               const PURE;  //FPS
    STDMETHOD_(float,  GetMinDragSpeed)()                  const PURE;  //FPS
    STDMETHOD_(float,  GetZeroLiftAngleOfAttack)()         const PURE;  //Radians
    STDMETHOD_(float,  GetCriticalAngleOfAttack)()         const PURE;  //Radians
    STDMETHOD_(float,  GetLinearCLAlpha)()                 const PURE;  //Per Radian
    STDMETHOD_(float,  GetWingArea)()                      const PURE;  //Square Feet
    STDMETHOD_(float,  GetWingSpan)()                      const PURE;  //Feet
    STDMETHOD_(float,  GetTotalLongitudinalThrust)()       const PURE;  //Pounds
    STDMETHOD_(float,  GetLiftForce)()                     const PURE;  //Pounds
 
    STDMETHOD_(double, GetThrottlePercent)()               const PURE;
    STDMETHOD_(double, GetElevatorPercent)()               const PURE;
    STDMETHOD_(double, GetAileronPercent)()                const PURE;
    STDMETHOD_(double, GetRudderPercent)()                 const PURE;
    STDMETHOD_(double, GetSpoilersPercent)()               const PURE;
    STDMETHOD_(double, GetFlapsPercent)()                  const PURE;
 
    STDMETHOD_(void,   SetThrottlePercent)(double dPct)          PURE;
    STDMETHOD_(void,   SetElevatorPercent)(double dPct)          PURE;  // pitch down <-0-> pitch up
    STDMETHOD_(void,   SetAileronPercent)(double dPct)           PURE;  // roll left  <-0-> roll right
    STDMETHOD_(void,   SetRudderPercent)(double dPct)            PURE;  // yaw left   <-0-> yaw right
    STDMETHOD_(void,   SetFlapsPercent)(double dPct)             PURE;  // none 0-> full
    STDMETHOD_(void,   SetSpoilersPercent)(double dPct)          PURE;  // retracted 0-> extended
 
    //Controller functions (e.g. PID) based on aircraft dynamics
    STDMETHOD_(double, CalculateDesiredBank)(double dHeadingError /*radians*/, double dDeltaT) PURE; //Radians
    STDMETHOD_(double, CalculateDeltaThrottle)(double dSpeedError /*feet/sec*/,double dDeltaT) PURE; //Radians
 
    //Taxi and Pushback logic is handled by the simulation
    STDMETHOD_(void, SetTaxiHeading)(float fHeading)             PURE; //Radians
    STDMETHOD_(void, SetTaxiSpeed)(float fSpeed)                 PURE; //FPS
    STDMETHOD_(void, StopTaxi)()                                 PURE;
    STDMETHOD_(void, SetPushBack)(BOOL bOn)                      PURE;
 
    //Begin Carrier related functionality
    STDMETHOD_(void,   ExtendTailhook)()                         PURE;
    STDMETHOD_(void,   RetractTailhook)()                        PURE;
    STDMETHOD_(float,  GetTailhookPosition)()              const PURE; // 0=retracted, 1=extended
    STDMETHOD_(BOOL,   HasTailhook)()                      const PURE;
 
    STDMETHOD_(void,   ExtendLaunchBar)()                        PURE;
    STDMETHOD_(void,   RetractLaunchBar)()                       PURE;
    STDMETHOD_(float,  GetLaunchBarPosition)()             const PURE; // 0=retracted, 1=extended
    STDMETHOD_(BOOL,   HasLaunchBar)()                     const PURE;
    STDMETHOD_(void,   FoldWings)()                              PURE;
    STDMETHOD_(void,   UnfoldWings)()                            PURE;
    STDMETHOD_(float,  GetLeftWingPosition)()              const PURE; // 0=unfolded, 1=folded
    STDMETHOD_(float,  GetRightWingPosition)()             const PURE; // 0=unfolded, 1=folded
 
    STDMETHOD_(float,  GetFullMilitaryThrottlePosition)()  const PURE; // position (0.0 to 1.0)
 
    STDMETHOD_(void,   ArmNearestCatapult)(BOOL bArm)            PURE;
    STDMETHOD_(void,   FireArmedCatapult)()                      PURE;
    //End Carrier related functionality
};

GetStallSpeedDirty() – Returns stall speed with gear and flaps extended. (feet per second)

GetStallSpeedClean() – Returns stall speed with gear and flaps retracted. (feet per second)

GetMinDragSpeed() – Returns speed at which total drag is at its minimum. (feet per second)

GetZeroLiftAngleOfAttack() – Return angle-of-attack at which zero lift is generated. (radians)

GetCriticalAngleOfAttack() – Returns angle-of-attack at which the aircraft will stall. (radians)

GetLinearCLAlpha() – Returns the slope of the CL vs. angle-of-attack curve in the linear region, typically between zero lift and the critical angle-of-attack. (radians)

GetWingArea() – Returns the total area of the main wing. (feet squared)

GetWingSpan() – Return the wingspan of the main wing. (feet)

GetTotalLongitudinalThrust() – Returns the thrust force in the longitudinal axis. (pounds)

GetLiftForce() – Returns the lift force generated by the airplane, including wing, tail, and fuselage). (pounds)

GetThrottlePercent() – Returns the throttle position. (0 – 1)

GetElevatorPercent() – Returns the elevator position. (-1 down - +1 up)

GetAileronPercent() – Returns the aileron position. (-1 left - +1 right)

GetRudderPercent() – Returns rudder percent. (-1 left - +1 right)

GetSpoilersPercent() – Return the spoiler position. (0 – 1)

GetFlapsPercent() – Returns the flap percent deflection. (0 – 1)

SetThrottlePercent() – Sets the throttle to a specific position. (0 – 1)

SetElevatorPercent() – Sets the elevator to a specific position. (-1 down - +1 up)

SetAileronPercent() – Sets the aileron to a specific position. (-1 left - +1 right)

SetRudderPercent() – Sets the rudder to a specific position. (-1 left - +1 right)

SetFlapsPercent() – Sets the flaps to a specific position. (0 - +1 extended)

SetSpoilersPercent() – Sets the spoilers to a specific position. (0 - +1 extended)

CalculateDesiredBank() – Returns a desired bank for the AI pilot based on a heading error. This is typically calculated with a PID controller based on the airplane dynamics. (radians)

CalculateDeltaThrottle() – Returns the amount the throttle should be moved this frame based on the current speed error. This is typically calculated with a PID controller based on the airplane and engine dynamics. (-1 - +1)

SetTaxiHeading() – Sets the taxi heading (radians) NOTE: Ground handling is assumed to be tightly coupled and calculated within the airplane simulation.

SetTaxiSpeed() – Sets the taxi speed (feet per second) NOTE: Ground handling is assumed to be tightly coupled and calculated within the airplane simulation.

StopTaxi() – Triggers the taxi operation to stop. NOTE: Ground handling is assumed to be tightly coupled and calculated within the airplane simulation.

SetPushBack() – Triggers the ground handling simulation to move backwards. For example, pushing back from a gate. NOTE: Ground handling is assumed to be tightly coupled and calculated within the airplane simulation.

ExtendTailhook() – Extends the aircraft's tailhook inorder to catch arrestor cables.

RetractTailhook() – Retracts the aircraft's tailhook.

GetTailhookPosition() – Returns the position of the aircraft's tailhook. (retracted=0.0; extended=1.0)

HasTailhook() – Returns TRUE if the aircraft has a valid tailhook, FALSE otherwise.

ExtendLaunchBar() – Extends the aircraft's launch bar inorder to attach to catapults.

RetractLaunchBar() – Retracts the aircraft's launch bar.

GetLaunchBarPosition() – Returns the position of the aircraft's launch bar. (retracted=0.0; extended=1.0)

HasLaunchBar() – Returns TRUE if the aircraft has a valid launch bar, FALSE otherwise.

FoldWings() – Folds the aircraft's wings, if available.

UnfoldWings() – Unfolds the aircraft's wings, if available.

GetLeftWingPosition() – Returns the current folded position of the aircraft's left wing. (unfolded=0.0; folded=1.0)

GetRightWingPosition() – Returns the current folded position of the aircraft's right wing. (unfolded=0.0; folded=1.0)

GetFullMilitaryThrottlePosition() – Returns the throttle position that is considered to be full military power (no afterburner). (position from 0.0 to 1.0)

ArmNearestCatapult() – Attempts to attach and arm the nearest catapult. See also Waypoint.

FireArmedCatapult() – Fires the currently armed catauplt. See also Waypoint.

IHelicopterAIService

Prepar3D does not currently support AI control of helicopters. Because this interface derives from the IAircraftAIService, this interface may also be used for features related to AI monitoring, such as the Flying Tips feature.

DECLARE_INTERFACE_ (IHelicopterAIServiceV01, IAircraftAIServiceV01)
{
};

IGroundVehicleAIService

This interface enables ground vehicle implementations to be utilized by Prepar3D's internal AI controllers.

DECLARE_INTERFACE_ (IGroundVehicleAIServiceV01, IGroundVehicleAIService)
{
};

Other Interfaces

These are other services that are defined to support other required interfaces for SimObjects.

IMassProperties

Interface for getting mass properties from SimObject implementation.

DECLARE_INTERFACE (IMassElement)
{
    STDMETHOD_ (float, GetWeight()) const PURE;
    STDMETHOD (GetOffset)(float& fXFeet, float& fYFeet, float& fZFeet) const PURE;
};
DECLARE_INTERFACE_ (IMassProperties, IUnknown)
{
    STDMETHOD_ (float, GetWeight()) const PURE;
    STDMETHOD_ (BOOL, RegisterMass(__in const IMassElement* pElement))       PURE;
    STDMETHOD_ (BOOL, UnRegisterMass(__in const IMassElement* pElement))       PURE;
    STDMETHOD_ (void, ForceUpdate())       PURE;
};

IForceMoments

Interface for getting physical forces from a SimObject implementation.

DECLARE_INTERFACE (IForceElement)
{
    STDMETHOD_ (void, GetForceMoment(__out DXYZ& vForces, __out DXYZ& vMoment)) const PURE;
    STDMETHOD (GetOffset(float& fXFeet, float& fYFeet, float& fZFeet)) const PURE;
    STDMETHOD (SetForceMultiplier(float scalar))       PURE;
};
DECLARE_INTERFACE_ (IForceMoments, IUnknown)
{
    STDMETHOD_ (BOOL, RegisterElement(__in IForceElement* pElement))       PURE;
    STDMETHOD_ (BOOL, UnRegisterElement(__in IForceElement* pElement))       PURE;
    STDMETHOD_ (UINT, ElementCount()) const PURE;
    STDMETHOD_ (IForceElement*, GetElement(int index)) const PURE;
};

ICollisionService

Interface for getting crash parameters for this object

DECLARE_INTERFACE_ (ICollisionService, IUnknown)
{
    STDMETHOD_ (BOOL, InvokesCrashOnOtherObjects())       PURE;
    STDMETHOD_ (void, SetInvokesCrashOnOtherObjects(__in BOOL invokesCrash))       PURE;
};

The following interfaces should be implemented for Prepar3D to recognize an object with those behaviors:

Other Non-SimObject Interfaces

These are other services that are defined to support operations not specific to a single SimObject instance.

ISurfaceQueryManager

This service allows getting surface information based on a world coordinate location. This service is provided by the IPdk interface.

DECLARE_INTERFACE_ (ISurfaceQueryManager, IUnknown)
{
    STDMETHOD(QuerySurfaceInformation)(__out SurfaceInfo& SurfaceInfo, __in const DXYZ& vWorldPosRadiansFeet)     const PURE;
    STDMETHOD(QuerySurfaceElevation) (__out float& fElevationFeet, __in const DXYZ& vWorldPosRadiansFeet)     const PURE;
};

QuerySurfaceInformation() – Provides surface information for a given world-relative position. (X = Longitude in radians, Y = Altitude in feet, Z = Latitude in radians). Returns E_FAIL if query fails.

QuerySurfaceElevation() – Provides surface elevation (in feet) for a given world-relative position. (X = Longitude in radians, Y = Altitude in feet, Z = Latitude in radians). Returns E_FAIL if query fails.

IWaypointQueryManager

This service allows for getting information about waypoints loaded for the user in a mission. This service is provided by the IPdk interface.

DECLARE_INTERFACE_ (IWaypointQueryManager, IUnknown)
{
    //Manager queries
    STDMETHOD_ (UINT, GetNumberOfWaypointLists()) const PURE;
    STDMETHOD  (GetWaypointListIndexFromDescription(__in LPCTSTR pszDescription, __out UINT& iWaypointList)) const PURE;
    //Waypoint list queries
    STDMETHOD_ (UINT, GetNumberOfWaypoints) (__in UINT iWaypointList) const PURE;
    STDMETHOD  (GetWaypointListDescription) (__in UINT iWaypointList, __out LPTSTR pszDesc, __in UINT uLength) const PURE;
    //Waypoint queries
    STDMETHOD_ (int, GetWaypointID)     (__in UINT iWaypontList, __in UINT iWaypoint) const PURE;
    STDMETHOD  (GetWaypointDescription) (__in UINT iWaypontList, __in UINT iWaypoint, __out LPTSTR pszDescription, __in UINT uLength) const PURE;
    STDMETHOD  (GetWaypointPosition)    (__in UINT iWaypontList, __in UINT iWaypoint, __out P3D::DXYZ& vWorldPosition) const PURE;
    STDMETHOD  (GetWaypointOrientation) (__in UINT iWaypontList, __in UINT iWaypoint, __out P3D::DXYZ& vOrientation) const PURE;
    STDMETHOD_ (BOOL, IsAltitudeAGL)    (__in UINT iWaypontList, __in UINT iWaypoint) const PURE;
    STDMETHOD  (GetWaypointCustomValue) (__in UINT iWaypontList, __in UINT iWaypoint, __out LPTSTR pszCustomVal, __in UINT uLength) const PURE;
};

GetNumberOfWaypointLists() – Returns the number of waypoint lists the manager is holding.

GetWaypointListIndexFromDescription() – Provides the index (0 - based) of the waypoint list with the description string passed in. Returns E_FAIL if waypoint list not found.

GetNumberOfWaypoints() – Returns the number of waypoints for the list specified by the list index input.

GetWaypointListDescription() – Provides the description string for the list specified by the list index input.  Returns E_FAIL if waypoint list not found.

GetWaypointID() – Returns the specified integer ID of the waypoint.

GetWaypointDescription() – Returns the specified description of the waypoint.

GetWaypointPosition() – Provides the world-relative position for the waypoint specified by the list and waypoint index inputs. (X = Longitude in radians, Y = Altitude in feet, Z = Latitude in radians).  Returns E_FAIL if waypoint not found.

GetWaypointOrientation() – Provides the orientation for the waypoint specified by the list and waypoint index inputs. (X = Pitch in radians, Y = Heading in radians, Z = Bank in radians).  Returns E_FAIL if waypoint not found.

IsAltitudeAGL() – Returns whether the specified altitude of the waypoint is Above Ground Level or Mean Sea Level.

GetWaypointCustomValue() – Provides the text string specified in the Custom Value field for the waypoint specified by the list and waypoint index inputs.  Returns E_FAIL if waypoint not found.

IScenarioManager

This service allows getting mission and scenario file information (also known as a "flight"). This service is provided by the IPdk interface.

DECLARE_INTERFACE_ (IScenarioManager, IUnknown)
{
    STDMETHOD(GetScenarioFilePath)(__out LPTSTR pszFilePath, __in UINT uLength)     const PURE;
    STDMETHOD(GetMissionFilePath) (__out LPTSTR pszFilePath, __in UINT uLength)     const PURE;
    STDMETHOD(GetMissionFileName) (__out LPTSTR pszFileName, __in UINT uLength)     const PURE;
    STDMETHOD(RegisterForNewScenarioNotification) (__in PNewScenarioNotify pcbNotifyFunction)     const PURE;
};

GetScenarioFilePath() – Provides the fully qualified path to the scenario file (also known as a "flight" file).

GetMissionFilePath() – Provides the fully qualified path to the associated mission file. If one does not exist a zero-length string is returned.

GetMissionFileName() – Provides the file name of the associated mission file. If one does not exist a zero-length string is returned.

RegisterForNewScenarioNotification() – This allows registering a callback function for notification when the current scenario has been loaded or changed. See Types.h for the function profile of PNewScenarioNotify.

IMarkerManager

This service allows for placing a graphical orthogonal marker on a simobject at a specified offset. This is useful for visualizing physical offsets relative to the visual model. For example, wheel and engine positions. By default, the marker consists of red 30 meter orthogonal lines in both the positive and negative directions of the X,Y, and Z axis. This service is available through the PDK service provider.

DECLARE_INTERFACE_ (IMarkerManagerV01, IUnknown)
{
    STDMETHOD (CreateObjectMarker)(__in UINT idObject, __out HANDLE& hHandle) PURE;
    STDMETHOD (UpdateObjectMarkerOffset)(__in const HANDLE hHandle, __in const FXYZ& vOffset) PURE;
    STDMETHOD (RemoveMarker)(__inout HANDLE& hHandle) PURE;
};

Note: a handle of "0" is considered invalid.

CreateObjectMarker() – Creates a new marker with the manager. It is advised to pass "0" for the handle, as that will verify with the manager that this is a new marker. A valid handle will be returned when successfully created. idObject is the Object ID in which to attach the marker.

UpdateObjectMarkerOffset() – This is called to update the offset from the object's center in which to draw the marker.

RemoveMarker() – Called to remove the marker. This will unregister the marker. The handle will be returned to a value of "0", and use of the original should be avoided.

- top -