SimObject Functions

Overview

To view a list of all SimObject SimConnect functions, see the SimObject Functions table.

General SimObject Functions

SimConnect_SetDataOnSimObject

The SimConnect_SetDataOnSimObject function is used to make changes to the data properties of an object.

Syntax

HRESULT SimConnect_SetDataOnSimObject(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_DEFINITION_ID  DefineID,
  SIMCONNECT_OBJECT_ID  ObjectID,
  SIMCONNECT_DATA_SET_FLAG  Flags,
  DWORD  ArrayCount,
  DWORD  cbUnitSize,
  void*  pDataSet
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
DefineID
[in]  Specifies the ID of the client defined data definition.
ObjectID
[in]  Specifies the ID of the Prepar3D object that the data should be about. This ID can be SIMCONNECT_OBJECT_ID_USER (to specify the user's aircraft) or obtained from a SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE structure after a call to SimConnect_RequestDataOnSimObjectType. Also refer to the note on multiplayer mode in the remarks for SimConnect_RequestDataOnSimObject.
Flags
[in]  Null, or one or more of the following flags.
Flag Description
SIMCONNECT_DATA_SET_FLAG_TAGGED The data to be set is being sent in tagged format. Refer to SimConnect_RequestDataOnSimObject for more details on the tagged format.
SIMCONNECT_DATA_SET_FLAG_UNBLOCK Any currently outstanding blocking callbacks are released. See SimConnect_RequestSynchronousBlock for more information.
ArrayCount
[in]  Specifies the number of elements in the data array. A count of zero is interpreted as one element. Ensure that the data array has been initialized completely before transmitting it to Prepar3D. Failure to properly initialize all array elements may result in unexpected behavior.
cbUnitSize
[in]  Specifies the size of each element in the data array in bytes. The data alignment of the individual element structures must align with the data layout defined by calls to the SimConnect_AddToDataDefinition function for the given definition (DefineID). Note that the default SIMCONNECT_DATATYPE value for the SimConnect_AddToDataDefinition DatumType paramater is SIMCONNECT_DATATYPE_FLOAT64 and must be correctly set if your element structures contain other data type members (i.e. int or float).

pDataSet
[in]  Pointer to the data that is to be written. If the data is not in tagged format, this should point to the block of data. If the data is in tagged format this should point to the first tag name (datumID), which is always four bytes long, which should be followed by the data itself. Any number of tag name/value pairs can be specified this way, the server will use the cbUnitSize parameter to determine how much data has been sent.

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

Example

static enum DATA_DEFINE_ID {
  DEFINITION3
};
  
// Link DEFINITION3 with the SIMCONNECT_DATA_INITPOSITION structure

hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION3, "Initial Position", "NULL", SIMCONNECT_DATATYPE_INITPOSITION, 0);

SIMCONNECT_DATA_INITPOSITION Init;
Init.Altitude = 5000.0;
Init.Latitude = 47.64210;
Init.Longitude = -122.13010;
Init.Pitch = -0.0;
Init.Bank = -1.0;
Init.Heading = 180.0;
Init.OnGround = 0;
Init.Airspeed = 0;

SimConnect_SetDataOnSimObject(hSimConnect, DEFINITION3, SIMCONNECT_OBJECT_ID_USER, 0, 0, sizeof(Init), &Init);

Working Samples

Primary samples Set Data
Throttle Control
 
Reference samples AI Objects and Waypoints
Managed AI Waypoints

Remarks

The data that is set on an object is defined in a data definition (see the SimConnect_AddToDataDefinition function). This data can include the following structures: SIMCONNECT_DATA_WAYPOINT, SIMCONNECT_DATA_INITPOSITION, and SIMCONNECT_DATA_MARKERSTATE. Any number of waypoints can be given to an AI object using a single call to this function, and any number of marker state structures can also be combined into an array.

The Simulation Variables document includes a column indicating whether variables can be written to or not. An exception will be returned if an attempt is made to write to a variable that cannot be set in this way.

See Also

SimConnect_ChangeVehicle

The SimConnect_ChangeVehicle function is used to change the selected vehicle.

Syntax

HRESULT SimConnect_ChangeVehicle(
  HANDLE  hSimConnect,
  const char*  Vehicletitle
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
Vehicletitle
[in]  title of the desired vehicle

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

Working Samples

Primary samples Change Vehicle
Managed Change Vehicle

Remarks

The instant replay does not get reset on the vehicle change which is the normal behavior when changing the vehicle in Prepar3D.

See Also

None.

SimConnect_RequestAttachPointData

The SimConnect_RequestAttachPointData function is used to request attach point data from a simulation object.

Syntax

HRESULT SimConnect_RequestAttachPointData(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID,
  DWORD  dwObjectID,
  const char*  szAttachPointName,
  BOOL  bRequestWorldCoordinates = FALSE
);

Parameters

hSimConnect
[in]   Handle to a SimConnect object.
RequestID
[in] Specifies the ID of the client-defined request. This is used later by the client to identify which data has been received. This value should be unique for each request, re-using a RequestID will overwrite any previous request using the same ID.
dwObjectID
[in]  The ID of the object to request attach point information from. This ID can be SIMCONNECT_OBJECT_ID_USER (to specify the user's aircraft) or obtained from a SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE structure after a call to SimConnect_RequestDataOnSimObjectType.
szAttachPointName
[in]  Specifies the name of the attach point to request data from.
bRequestWorldCoordinates
[in, optional]  If set to TRUE, the world position and orientation information will be requested as well. If FALSE, world position and orientation information will be returned as zero.

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

Remarks

The data will be returned in a SIMCONNECT_RECV_ATTACHPOINT_DATA structure.

See Also

SimConnect_RequestDataOnSimObject

The SimConnect_RequestDataOnSimObject function is used to request when the SimConnect client is to receive data values for a specific object.

Syntax

HRESULT SimConnect_RequestDataOnSimObject(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID,
  SIMCONNECT_DATA_DEFINITION_ID  DefineID,
  SIMCONNECT_OBJECT_ID  ObjectID,
  SIMCONNECT_PERIOD  Period,
  SIMCONNECT_DATA_REQUEST_FLAG  Flags = 0,
  DWORD  origin = 0,
  DWORD  interval = 0,
  DWORD  limit = 0
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
RequestID
[in]  Specifies the ID of the client defined request. This is used later by the client to identify which data has been received. This value should be unique for each request, re-using a RequestID will overwrite any previous request using the same ID.
DefineID
[in]  Specifies the ID of the client defined data definition.
ObjectID
[in]  Specifies the ID of the Prepar3D object that the data should be about. This ID can be SIMCONNECT_OBJECT_ID_USER (to specify the user's aircraft) or obtained from a SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE structure after a call to SimConnect_RequestDataOnSimObjectType. Also refer to the note on developing clients for multiplayer mode in the Remarks section below.
Period
[in]  One member of the SIMCONNECT_PERIOD enumeration type, specifying how often the data is to be sent by the server and received by the client.
Flags
[in, optional]  A DWORD containing one or more of the following values:
Flag value Description
0 The default, data will be sent strictly according to the defined period.
SIMCONNECT_DATA_REQUEST_FLAG_CHANGED

Data will only be sent to the client when one or more values have changed. If this is the only flag set, then all the variables in a data definition will be returned if just one of the values changes.


The following types support the SIMCONNECT_DATA_REQUEST_FLAG_CHANGED:

  • SIMCONNECT_DATATYPE_INT32
  • SIMCONNECT_DATATYPE_FLOAT32
  • SIMCONNECT_DATATYPE_INT64
  • SIMCONNECT_DATATYPE_FLOAT64
  • SIMCONNECT_DATATYPE_XYZ
  • SIMCONNECT_DATATYPE_PBH
  • SIMCONNECT_DATATYPE_LATLONALT
  • SIMCONNECT_DATATYPE_STRING8
  • SIMCONNECT_DATATYPE_STRING32
  • SIMCONNECT_DATATYPE_STRING64
  • SIMCONNECT_DATATYPE_STRING128
  • SIMCONNECT_DATATYPE_STRING256
  • SIMCONNECT_DATATYPE_STRING260
SIMCONNECT_DATA_REQUEST_FLAG_TAGGED Requested data will be sent in tagged format (datum ID/value pairs). Tagged format requires that a datum reference ID is returned along with the data value, in order that the client code is able to identify the variable. This flag is usually set in conjunction with the previous flag, but it can be used on its own to return all the values in a data definition in datum ID/value pairs. See the SIMCONNECT_RECV_SIMOBJECT_DATA structure for more details.
SIMCONNECT_DATA_REQUEST_FLAG_BLOCK Requested data will be sent using a blocking callback. See SimConnect_RequestSynchronousBlock for more information.
origin
[in, optional]  The number of Period events that should elapse before transmission of the data begins. The default is zero, which means transmissions will start immediately.
interval
[in, optional]  The number of Period events that should elapse between transmissions of the data. The default is zero, which means the data is transmitted every Period.
limit
[in, optional]  The number of times the data should be transmitted before this communication is ended. The default is zero, which means the data should be transmitted endlessly.

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

Example


static enum DATA_DEFINE_ID {
  DEFINITION_1,
  DEFINITION_2
};

static enum DATA_REQUEST_ID {
    REQUEST_1,
    REQUEST_2,
};

struct Struct1
{
    double  kohlsmann;
    double  altitude;
    double  latitude;
    double  longitude;
};
// Match string definitions from the Simulation Variables document with the client defined ID

hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Kohlsman setting hg", "inHg");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Indicated Altitude", "feet");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Plane Latitude", "degrees");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Plane Longitude", "degrees");

// Sections of code in DispatchProc

....
SimConnect_RequestDataOnSimObject(hSimConnect, REQUEST_2, DEFINITION_1, SIMCONNECT_OBJECT_ID_USER, SIMCONNECT_PERIOD_SECOND);
....
// When the data is received -- cast it to the correct structure type

case SIMCONNECT_RECV_ID_SIMOBJECT_DATA:
{
  SIMCONNECT_RECV_SIMOBJECT_DATA *pObjData = (SIMCONNECT_RECV_SIMOBJECT_DATA*) pData;

  switch(pObjData->dwRequestID)
  {
    case REQUEST_2:

      Struct1 *pS = (Struct1*)&pObjData->dwData;
   
      // Add code to process the structure appropriately

      break;
  }
break;
}
....

Working Samples

Primary samples Tagged Data
Reference samples Weather Station

Remarks

Changing the Period parameter or changing the content of a data definition has a higher performance cost than changing the origin, interval or limit parameters. So to temporarily turn off data requests, especially for short periods of time, consider setting the interval parameter to a very high value (such as DWORD _MAX). If changes are required to a data definition, consider setting the Period parameter to SIMCONNECT_PERIOD_NEVER (see the SIMCONNECT_PERIOD enumeration) before making the changes, and then turning on the appropriate period after the changes have been made.

It is possible to change the period of a request, by resending the SimConnect_RequestDataOnSimObject call with the same RequestID, DefineID and ObjectID parameters, but with a new period. The one exception to this is the new period cannot be SIMCONNECT_PERIOD_ONCE, in this case a request with a new RequestID should be sent.

If an object is removed, and if it has a current periodic data request, a SIMCONNECT_EXCEPTION_UNRECOGNIZED_ID exception will be sent every requested period. This can be avoided by sending a new SimConnect_RequestDataOnSimObject with the period set to SIMCONNECT_PERIOD_NEVER, before the object is removed or once the first exception is generated.

Data is always transmitted with the SimConnect_RequestDataOnSimObject function, so if timing only notifications are required, use the SimConnect_SubscribeToSystemEvent function.

Note that variable length strings should not be used in data definitions, except where the Period parameter has been set to SIMCONNECT_PERIOD_ONCE.

One method of testing whether the user has changed aircraft type is to use this function to return the title of the user aircraft, and note that if it changes, the user has changed the type of aircraft (all aircraft types have unique title strings, including those simply with different color schemes). An example of requesting the aircraft title is in the Variable Strings working sample. See the Aircraft Configuration Files document for more details on titles.

If boolean data has been requested as part of a data definition, note that the only reliable numeric equivalent is that 0 is returned for False. Non-zero values, especially both 1 and -1, are used to indicate True.

Note: Multiplayer Mode

When developing a client for use in multiplayer mode it is not safe to use the ID number for the user aircraft returned by the function SimConnect_RequestDataOnSimObjectType, as the actual number can change depending on several factors, including the number of users involved in the multiplayer scenario. Always use the constant SIMCONNECT_OBJECT_ID_USER for the ObjectID parameter if the SimConnect client is to work in multiplayer mode. Also note that in this mode it is good practice to remove any calls associated with periodic data on AI objects and to remove subscriptions to AI objects.

See Also

SimConnect_RequestDataOnSimObjectType

The SimConnect_RequestDataOnSimObjectType function is used to retrieve information about simulation objects of a given type that are within a specified radius of the user's aircraft.

Syntax

HRESULT SimConnect_RequestDataOnSimObjectType(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID,
  SIMCONNECT_DATA_DEFINITION_ID  DefineID,
  DWORD  dwRadiusMeters,
  SIMCONNECT_SIMOBJECT_TYPE  type
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
RequestID
[in]  Specifies the ID of the client defined request. This is used later by the client to identify which data has been received. This value should be unique for each request, re-using a RequestID will overwrite any previous request using the same ID.
DefineID
[in]  Specifies the ID of the client defined data definition.
dwRadiusMeters
[in]  Double word containing the radius in meters. If this is set to zero only information on the user aircraft will be returned, although this value is ignored if type is set to SIMCONNECT_SIMOBJECT_TYPE_USER. The error SIMCONNECT_EXCEPTION_OUT_OF_BOUNDS will be returned if a radius is given and it exceeds the maximum allowed (200000 meters, or 200 Km).
type
[in]  Specifies the type of object to receive information on. One member of the SIMCONNECT_SIMOBJECT_TYPE enumeration type.

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

Example

See SimConnect_AddToDataDefinition for an example of when to use this function

Working Samples

Primary samples Request Data
Variable Strings
Reference samples  

Remarks

The data will be returned on all the relevant objects within the specified radius, but they will not be returned in any specific order. It is the responsibility of the client program to sort the returned data into order, if that is required. Information is returned in a SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE structure, one structure per object.

Also refer to the note on multiplayer mode in the remarks for SimConnect_RequestDataOnSimObject.

See Also

AI Object Specific Functions

SimConnect_AICreateEnrouteATCAircraft

The SimConnect_AICreateEnrouteATCAircraft function is used to create an AI controlled aircraft that is about to start or is already underway on its flight plan.

Syntax

HRESULT SimConnect_AICreateEnrouteATCAircraft(
  HANDLE  hSimConnect,
  const char*  szContainertitle,
  const char*  szTailNumber,
  int  iFlightNumber,
  const char*  szFlightPlanPath,
  double  dFlightPlanPosition,
  BOOL  bTouchAndGo,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
szContainertitle
[in]  Null-terminated string containing the container title. The container title is found in the aircraft.cfg file (see the Aircraft Configuration Files document): for example: title=Mooney Bravo or title=Commercial Airliner.
szTailNumber
[in]  Null-terminated string containing the tail number. This should have a maximum of 12 characters.
iFlightNumber
[in]  Integer containing the flight number. There is no specific maximum length of this number. Any negative number indicates that there is no flight number.
szFlightPlanPath
[in]  Null-terminated string containing the path to the flight plan file. Flight plans have the extension .pln, but no need to enter an extension here. The easiest way to create flight plans is to create them from within Prepar3D itself, and then save them off for use with the AI controlled aircraft. There is no need to enter the full path to the file (just enter the filename) if the flight plan is in the default Prepar3D v4 Files directory.
dFlightPlanPosition
[in]  Double floating point number containing the flight plan position. The number before the point contains the waypoint index, and the number afterwards how far along the route to the next waypoint the aircraft is to be positioned. The first waypoint index is 0. For example, 0.0 indicates that the aircraft has not started on the flight plan, 2.5 would indicate the aircraft is to be initialized halfway between the third and fourth waypoints (which would have indexes 2 and 3). The waypoints are those recorded in the flight plan, which may just be two airports, and do not include any taxiway points on the ground. Also there is a threshold that will ignore requests to have an aircraft taxiing or taking off, or landing. So set the value after the point to ensure the aircraft will be in level flight. See the section on Aircraft Flight Plans.
bTouchAndGo
[in]  Flag, True indicating that landings should be touch and go, and not full stop landings.
RequestID
[in]  Specifies the client defined request ID.

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

Working Sample

Primary sample AI Traffic

Remarks

An enroute aircraft can be on the ground or airborne when it is created by this function. Typically this will be an aircraft flying under IFR rules, and in constant radio contact with ATC. A number of errors, including SIMCONNECT_EXCEPTION_CREATE_AIRCRAFT_FAILED, apply to AI objects (refer to the SIMCONNECT_EXCEPTION enum for more details).

A SIMCONNECT_RECV_ID_EVENT_OBJECT_ADDREMOVE event notification can be subscribed to (see the SimConnect_SubscribeToSystemEvent function), which will return a SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE structure whenever any client, including the one making the change, successfully adds or removes an AI controlled object.

This function should be used for fixed-wing aircraft flying between airports on land. There is no internal AI pilot for helicopters, gliders or hot-air balloons. In order to add a helicopter, glider or balloon not controlled by the user, the SimConnect client must implement full control of the aircraft. Set up these objects with a call to SimConnect_AICreateSimulatedObject.

For float-planes the recommended procedure is to control them using waypoints, and not the ATC system, as there is no concept of a "parking space" after a water landing. So, the waypoints of the route of the float-plane should include the route that it should follow before takeoff and after landing. For all these cases of controlling aircraft using the client, or using waypoints, set up the object using the SimConnect_AICreateNonATCAircraft call.

The Reality Bubble

In order to improve performance, only a certain area around the user's aircraft is actually simulated at any one time. As the user flies the aircraft that area (referred to in the simulator as the "reality bubble") moves along with the aircraft. Simulated objects outside of the area are removed altogether, and new AI aircraft are not created if they fall outside these bounds. The reality bubble is in fact more of a box, and is aligned to lines of latitude and longitude, so the box becomes narrower near the poles than it is as the equator. The following diagram shows how the reality bubble works. There are always nine boxes (approximately 64Km square at the equator) that are simulated, and the user aircraft is always in the center box. As the aircraft flies over a boundary line, then the areas that are simulated change. In the following diagram, the green areas are simulated (active aircraft, airports, ground vehicles, shipping traffic and so on), and the grey areas are not.

Reality1
Reality2

Note that if an aircraft, or other simulation object, falls outside this area and is deleted by the system, the client will no longer receive information on the object (typically requested by the SimConnect_RequestDataOnSimObject function). Consider using the SimConnect_SubscribeToSystemEvent function to request notifications for "ObjectRemoved" to test for these situations. No automatic notification is given when information is requested on an object, and then subsequently that object is removed.

Aircraft Flight Plans

The following table contains an example flight plan from Sea-Tac International airport (KSEA) to San Francisco International airport (KSFO), following high-altitude airways. There are six waypoints, including the departure and destination airports. A flight plan can be created by Prepar3D or created directly in XML, matching the required format. The simplest flight plan will contain only the departure and destination airports. The ATCWaypoints in a scenario file are not identical to the SIMCONNECT_DATA_WAYPOINT structures. ATCWaypoints in a flightplan can be very far apart, and the AI pilot of Prepar3D requires waypoints to be no more than around five miles apart, so a flightplan such as the one given below will be broken down by the AI component into shorter sections -- using the SIMCONNECT_DATA_WAYPOINT structures.

<?xml version="1.0" encoding="UTF-8"?>

<SimBase.Document Type="AceXML" version="1,0">
    <Descr>AceXML Document</Descr>
    <WorldBase.FlightPlan>
        <title>KSEA to KSFO</title>
        <FPType>IFR</FPType>
        <RouteType>HighAlt</RouteType>
        <CruisingAlt>31000</CruisingAlt>
        <DepartureID>KSEA</DepartureID>
        <DepartureLLA>N47 25' 53.27",W122 18' 28.83",+000433.00</DepartureLLA>
        <DestinationID>KSFO</DestinationID>
        <DestinationLLA>N37 36' 26.00",W122 22' 49.59",+000013.00</DestinationLLA>
        <Descr>KSEA, KSFO</Descr>
        <DeparturePosition>34R</DeparturePosition>
        <DepartureName>Seattle-Tacoma Intl</DepartureName>
        <DestinationName>San Francisco Intl</DestinationName>
        <AppVersion>
            <AppVersionMajor>10</AppVersionMajor>
            <AppVersionBuild>60327</AppVersionBuild>
        </AppVersion>

        <ATCWaypoint id="KSEA">
            <ATCWaypointType>Airport</ATCWaypointType>
            <WorldPosition>N47 25' 53.27",W122 18' 28.83",+000433.00</WorldPosition>
            <ICAO>
                <ICAOIdent>KSEA</ICAOIdent>
            </ICAO>
        </ATCWaypoint>

        <ATCWaypoint id="SEA">
            <ATCWaypointType>VOR</ATCWaypointType>
            <WorldPosition>N47 26' 7.36",W122 18' 34.59",+000000.00</WorldPosition>
            <ICAO>
                <ICAORegion>K1</ICAORegion>
                <ICAOIdent>SEA</ICAOIdent>
            </ICAO>
        </ATCWaypoint>

        <ATCWaypoint id="LMT">
            <ATCWaypointType>VOR</ATCWaypointType>
            <WorldPosition>N42 9' 11.34",W121 43' 39.10",+000000.00</WorldPosition>
            <ATCAirway>J65</ATCAirway>
            <ICAO>
                <ICAORegion>K1</ICAORegion>
                <ICAOIdent>LMT</ICAOIdent>
            </ICAO>
        </ATCWaypoint>

        <ATCWaypoint id="RBL">
            <ATCWaypointType>VOR</ATCWaypointType>
            <WorldPosition>N40 5' 56.07",W122 14' 10.88",+000000.00</WorldPosition>
            <ATCAirway>J65</ATCAirway>
            <ICAO>
                <ICAORegion>K2</ICAORegion>
                <ICAOIdent>RBL</ICAOIdent>
            </ICAO>
        </ATCWaypoint>

        <ATCWaypoint id="OAK">
            <ATCWaypointType>VOR</ATCWaypointType>
            <WorldPosition>N37 43' 33.30",W122 13' 24.92",+000000.00</WorldPosition>
            <ATCAirway>J3</ATCAirway>
            <ICAO>
                <ICAORegion>K2</ICAORegion>
                <ICAOIdent>OAK</ICAOIdent>
            </ICAO>
        </ATCWaypoint>

        <ATCWaypoint id="KSFO">
            <ATCWaypointType>Airport</ATCWaypointType>
            <WorldPosition>N37 36' 26.00",W122 22' 49.59",+000013.00</WorldPosition>
            <ICAO>
                <ICAOIdent>KSFO</ICAOIdent>
            </ICAO>
        </ATCWaypoint>

    </WorldBase.FlightPlan>
</SimBase.Document>

See Also

SimConnect_AICreateEnrouteATCAircraftW

The SimConnect_AICreateEnrouteATCAircraftW function is used to create an AI controlled aircraft that is about to start or is already underway on its flight plan. This version of the functions supports unicode file paths, titles, tail numbers, and flight plans.

Syntax

HRESULT SimConnect_AICreateEnrouteATCAircraftW(
  HANDLE  hSimConnect,
  const wchar_t*  szContainertitle,
  const wchar_t*  szTailNumber,
  int  iFlightNumber,
  const wchar_t*  szFlightPlanPath,
  double  dFlightPlanPosition,
  BOOL  bTouchAndGo,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
szContainertitle
[in]  Null-terminated string containing the container title. The container title is found in the aircraft.cfg file (see the Aircraft Configuration Files document): for example: title=Mooney Bravo or title=Commercial Airliner.
szTailNumber
[in]  Null-terminated string containing the tail number. This should have a maximum of 12 characters.
iFlightNumber
[in]  Integer containing the flight number. There is no specific maximum length of this number. Any negative number indicates that there is no flight number.
szFlightPlanPath
[in]  Null-terminated string containing the path to the flight plan file. Flight plans have the extension .pln, but no need to enter an extension here. The easiest way to create flight plans is to create them from within Prepar3D itself, and then save them off for use with the AI controlled aircraft. There is no need to enter the full path to the file (just enter the filename) if the flight plan is in the default Prepar3D v4 Files directory.
dFlightPlanPosition
[in]  Double floating point number containing the flight plan position. The number before the point contains the waypoint index, and the number afterwards how far along the route to the next waypoint the aircraft is to be positioned. The first waypoint index is 0. For example, 0.0 indicates that the aircraft has not started on the flight plan, 2.5 would indicate the aircraft is to be initialized halfway between the third and fourth waypoints (which would have indexes 2 and 3). The waypoints are those recorded in the flight plan, which may just be two airports, and do not include any taxiway points on the ground. Also there is a threshold that will ignore requests to have an aircraft taxiing or taking off, or landing. So set the value after the point to ensure the aircraft will be in level flight. See the section on Aircraft Flight Plans.
bTouchAndGo
[in]  Flag, True indicating that landings should be touch and go, and not full stop landings.
RequestID
[in]  Specifies the client defined request ID.

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

See Also

SimConnect_AICreateNonATCAircraft

The SimConnect_AICreateNonATCAircraft function is used to create an aircraft that is not flying under ATC control (so is typically flying under VFR rules).

Syntax

HRESULT SimConnect_AICreateNonATCAircraft(
  HANDLE  hSimConnect,
  const char*  szContainertitle,
  const char*  szTailNumber,
  SIMCONNECT_DATA_INITPOSITION  InitPos,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
szContainertitle
[in]  Null-terminated string containing the container title. The container title is case-sensitive and can be found in the aircraft.cfg file (see the Aircraft Configuration Files document): for example: title=Mooney Bravo or title=Commercial Airliner.
szTailNumber
[in]  Null-terminated string containing the tail number. This should have a maximum of 12 characters.
InitPos
[in]  Specifies the initial position, using a SIMCONNECT_DATA_INITPOSITION structure.
RequestID
[in]  Specifies the client defined request ID.

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

Working Sample

Primary sample AI Objects and Waypoints
Managed AI Waypoints

Remarks

A non-ATC aircraft can be on the ground or airborne when it is created by this function. A number of errors, including SIMCONNECT_EXCEPTION_CREATE_AIRCRAFT_FAILED, apply to AI objects (refer to the SIMCONNECT_EXCEPTION enum for more details).

Refer to the remarks for SimConnect_AICreateEnrouteATCAircraft.

See Also

SimConnect_AICreateParkedATCAircraft

The SimConnect_AICreateParkedATCAircraft function is used to create an AI controlled aircraft that is currently parked and does not have a flight plan.

Syntax

HRESULT SimConnect_AICreateParkedATCAircraft(
  HANDLE  hSimConnect,
  const char*  szContainertitle,
  const char*  szTailNumber,
  const char*  szAirportID,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
szContainertitle
[in]  Null-terminated string containing the container title. The container title is case-sensitive and can found in the aircraft.cfg file (see the Aircraft Configuration Files document): for example: title=Mooney Bravo or title=Commercial Airliner.
szTailNumber
[in]  Null-terminated string containing the tail number. This should have a maximum of 12 characters.
szAirportID
[in]  Null-terminated string containing the airport ID. This is the ICAO identification string, for example, KSEA for SeaTac International.
RequestID
[in]  Specifies the client defined request ID.

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

Working Sample

Primary sample AI Traffic

Remarks

Calling this function is no guarantee that there is sufficient parking space at the specified airport. An error will be returned if there is insufficient parking space, and an aircraft will not be created. A number of errors, including SIMCONNECT_EXCEPTION_CREATE_AIRCRAFT_FAILED, apply to AI objects (refer to the SIMCONNECT_EXCEPTION enum for more details). After creating an aircraft with this function, a call to SimConnect_AISetAircraftFlightPlan will set the aircraft in motion.

When allocating a parking space to an aircraft, the simulation uses a radius based on half the wingspan defined in the [aircraft_geometry] section of the Aircraft Configuration File. Use the Dump Airport List tool (refer to the Traffic Toolbox documentation) to see what parking spaces are available at any airport.

Refer also to the remarks for SimConnect_AICreateEnrouteATCAircraft.

See Also

SimConnect_AICreateSimulatedObject

The SimConnect_AICreateSimulatedObject function is used to create AI controlled objects other than aircraft.

Syntax

HRESULT SimConnect_AICreateSimulatedObject(
  HANDLE  hSimConnect,
  const char*  szContainertitle,
  SIMCONNECT_DATA_INITPOSITION  InitPos,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
szContainertitle
[in]  Null-terminated string containing the container title. The container title is case-sensitive and can be found in the sim.cfg file, for example:
Object Types Examples
Ground Vehicles title=Automobile
title=FuelTruck
title=VEH_air_bagcart1
title=VEH_air_bagcart_FlatNosed
Boats title=cargoA
title=cargoA_hoop
title=cargoB
Miscellaneous title=Flour_bomb_floating_dock
title=HumpbackWhale
InitPos
[in]  Specifies the initial position, using a SIMCONNECT_DATA_INITPOSITION structure.
RequestID
[in]  Specifies the client defined request ID.

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

Working Sample

Primary sample AI Objects and Waypoints
Managed AI Waypoints

Remarks

This function can be used to create a stationary aircraft (such as an unflyable aircraft on display outside a flight museum), but is typically intended to create simulation objects other than aircraft (such as ground vehicles, boats, and a number of special objects such as humpback whales and hot-air balloons). A number of errors apply to AI objects (refer to the SIMCONNECT_EXCEPTION enum for more details).

See Also

SimConnect_AICreateSimulatedObjectEx

The SimConnect_AICreateSimulatedObjectEx function is used to create AI controlled objects other than aircraft.

Syntax

HRESULT SimConnect_AICreateSimulatedObjectEx(
  HANDLE  hSimConnect,
  const char*  szContainertitle,
  SIMCONNECT_DATA_INITPOSITION  InitPos,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
  BOOL  isDisabled = FALSE
  int  OwnerID = -1
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
szContainertitle
[in]  Null-terminated string containing the container title. The container title is case-sensitive and can be found in the sim.cfg file, for example:
Object Types Examples
Ground Vehicles title=Automobile
title=FuelTruck
title=VEH_air_bagcart1
title=VEH_air_bagcart_FlatNosed
Boats title=cargoA
title=cargoA_hoop
title=cargoB
Miscellaneous title=Flour_bomb_floating_dock
title=HumpbackWhale
InitPos
[in]  Specifies the initial position, using a SIMCONNECT_DATA_INITPOSITION structure.
RequestID
[in]  Specifies the client defined request ID.

isDisabled
[in, optional]  Specifies whether the simulation starts disabled or not default value is FALSE.

OwnerID
[in, optional]  Specifies the owner of this simualted object. Default value is -1 which is an invalid object ID.

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

Working Sample

Primary sample AI Objects and Waypoints
Managed AI Waypoints

Remarks

This function can be used to create a stationary aircraft (such as an unflyable aircraft on display outside a flight museum), but is typically intended to create simulation objects other than aircraft (such as ground vehicles, boats, and a number of special objects such as humpback whales and hot-air balloons). A number of errors apply to AI objects (refer to the SIMCONNECT_EXCEPTION enum for more details).

See Also

SimConnect_AIReleaseControl

The SimConnect_AIReleaseControl function is used to clear the AI control of a simulated object, typically an aircraft, in order for it to be controlled by a SimConnect client.

Syntax

HRESULT SimConnect_AIReleaseControl(
  HANDLE  hSimConnect,
  SIMCONNECT_OBJECT_ID  ObjectID,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
ObjectID
[in]  Specifies the server defined object ID.
RequestID
[in]  Specifies the client defined request ID.

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

Remarks

This function should be used to transfer the control of an aircraft, or other object, from the AI system to the SimConnect client. If this is not done the AI system and client may fight each other with unpredictable results. To prevent the simulation engine from updating the latitude, longitude, altitude and attitude of an aircraft, refer to the range of KEY_FREEZE..... Event IDs.

The object ID can be obtained in a number of ways, refer to the SimConnect_RequestDataOnSimObjectType call, and also the use of the SIMCONNECT_RECV_ASSIGNED_OBJECT_ID structure.

See Also

SimConnect_AIReleaseControlEx

The SimConnect_AIReleaseControlEx function is used to clear the AI control of a simulated object, typically an aircraft, in order for it to be controlled by a SimConnect client. Optionally, this function can be used to completely remove the AI instead of clearing it. Removing the AI will allow for complete manual control of a SimConnect SimObject.

Syntax

HRESULT SimConnect_AIReleaseControlEx(
  HANDLE  hSimConnect,
  SIMCONNECT_OBJECT_ID  ObjectID,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
  BOOL  destroyAI = FALSE
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
ObjectID
[in]  Specifies the server defined object ID.
RequestID
[in]  Specifies the client defined request ID.

destroyAI
[in, optional]  Specifies whether to destory the AI or not (default value = FALSE).

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

Remarks

This function should be used to transfer the control of an aircraft, or other object, from the AI system to the SimConnect client. If this is not done the AI system and client may fight each other with unpredictable results. To prevent the simulation engine from updating the latitude, longitude, altitude and attitude of an aircraft, refer to the range of KEY_FREEZE..... Event IDs.

The object ID can be obtained in a number of ways, refer to the SimConnect_RequestDataOnSimObjectType call, and also the use of the SIMCONNECT_RECV_ASSIGNED_OBJECT_ID structure.

See Also

SimConnect_AIRemoveObject

The SimConnect_AIRemoveObject function is used to remove any object created by the client using one of the SimConnect AI creation functions.

Syntax

HRESULT SimConnect_AIRemoveObject(
  HANDLE  hSimConnect,
  SIMCONNECT_OBJECT_ID  ObjectID,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
ObjectID
[in]  Specifies the server defined object ID (refer to the SIMCONNECT_RECV_ASSIGNED_OBJECT_ID structure).
RequestID
[in]  Specifies the client defined request ID.

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

Remarks

A client application can only remove AI controlled objects that it created, not objects created by other clients, or by the simulation itself.

See Also

SimConnect_AISetAircraftFlightPlan

The SimConnect_AISetAircraftFlightPlan function is used to set or change the flight plan of an AI controlled aircraft.

Syntax

HRESULT SimConnect_AISetAircraftFlightPlan(
  HANDLE  hSimConnect,
  SIMCONNECT_OBJECT_ID  ObjectID,
  const char*  szFlightPlanPath,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
ObjectID
[in]  Specifies the server defined object ID.
szFlightPlanPath
[in]  Null-terminated string containing the path to the flight plan file. Flight plans have the extension .pln, but no need to enter an extension here. The easiest way to create flight plans is to create them from within the simulation, and then save them off for use with the AI controlled aircraft. There is no need to enter the full path (just the filename) if the flight plan is in the default Prepar3D v4 Files directory. See the section on Aircraft Flight Plans.
RequestID
[in]  Specifies client defined request ID.

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

Working Sample

Primary sample AI Traffic

Remarks

A number of errors, including SIMCONNECT_EXCEPTION_CREATE_FLIGHTPLAN_FAILED, apply to AI objects (refer to the SIMCONNECT_EXCEPTION enum for more details).

Typically this function would be used some time after the aircraft was created using the SimConnect_AICreateParkedATCAircraft call.

See Also

SimConnect_AISetAircraftFlightPlanW

The SimConnect_AISetAircraftFlightPlanW function is used to set or change the flight plan of an AI controlled aircraft. This version of the function supports unicode file paths.

Syntax

HRESULT SimConnect_AISetAircraftFlightPlanW(
  HANDLE  hSimConnect,
  SIMCONNECT_OBJECT_ID  ObjectID,
  const wchar_t*  szFlightPlanPath,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
ObjectID
[in]  Specifies the server defined object ID.
szFlightPlanPath
[in]  Null-terminated string containing the path to the flight plan file. Flight plans have the extension .pln, but no need to enter an extension here. The easiest way to create flight plans is to create them from within the simulation, and then save them off for use with the AI controlled aircraft. There is no need to enter the full path (just the filename) if the flight plan is in the default Prepar3D v4 Files directory. See the section on Aircraft Flight Plans.
RequestID
[in]  Specifies client defined request ID.

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

Working Sample

Primary sample AI Traffic

Remarks

A number of errors, including SIMCONNECT_EXCEPTION_CREATE_FLIGHTPLAN_FAILED, apply to AI objects (refer to the SIMCONNECT_EXCEPTION enum for more details).

Typically this function would be used some time after the aircraft was created using the SimConnect_AICreateParkedATCAircraft call.

See Also

SimConnect_AISetGroundClamp

The SimConnect_AISetGroundClamp function is used to enable/disable ground clamping on a SimConnect owned SimObject.

Syntax

HRESULT SimConnect_AISetGroundClamp(
  HANDLE  hSimConnect,
  SIMCONNECT_OBJECT_ID  ObjectID,
  BOOL  bGroundClamp,
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
ObjectID
[in]  Specifies the server defined object ID.
bGroundClamp
[in]  Boolean value that specifies if Ground Clamping should be enabled or disabled for the specified ObjectID. Ground Clamping keeps the object from being pushed below ground level.

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

See Also

Attach Sim Specific Functions

Overview

The Attach Sim APIs are used to attach one SimObject to another SimObject.  There's no physical simulation of the attached objects (i.e. the mass of an attached object doesn't affect the object its attached to, the attached object just suspends simulation and moves with the object its attached to.  When an attached object is released, it's primary sim resumes operation.

There are two versions of the attach API, AttachObjectToSimObject will create a new AI object and attach it to the specified SimObject. AttachSimObjectToSimObject is used to attach one existing SimObject to another SimObject (you can both attach the User SimObject to another object or attach other SimObjects to a User SimObject with this function).

SimConnect_AttachObjectToSimObject

The SimConnect_AttachObjectToSimObject function is used to create a new AI SimObject and attach it to an existing SimObject.

Syntax


HRESULT SimConnect_AttachObjectToSimObject(
  HANDLE  hSimConnect,
  DWORD  dwObjectID,
  SIMCONNECT_DATA_XYZ  vecOff1,
  SIMCONNECT_DATA_PBH  rotOff1,
  const char *  szContainertitle
  SIMCONNECT_DATA_XYZ  vecOff2
  SIMCONNECT_DATA_PBH  rotOff2
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
dwObjectID
[in]  ObjectID of the existing SimObject to attach to.
vecOff1
[in]  XYZ offset from existing SimObject model center to attachment point.
rotOff1
[in]  PBH offset from existing SimObject model body axis to attachment point.
szContainertitle
[in]  Null-terminated string containing the container title of the AI SimObject you want to create and attach to the existing SimObject. The container title is found in the aircraft.cfg file (see the Aircraft Configuration Files document): for example: title=Mooney Bravo or title=Commercial Airliner.
vecOff2
[in]  XYZ offset from created AI SimObject model center to attachment point.
rotOff2
[in]  PBH offset from created AI SimObject model body axis to attachment point.
RequestID
[in]  Specifies the ID of the client-defined request. This is used later by the client to identify which data has been received. This value should be unique for each request, re-using a RequestID will overwrite any previous request using the same ID.

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

See Also

SimConnect_AttachSimObjectToSimObject

The SimConnect_AttachSimObjectToSimObject function is used to create a new AI SimObject and attach it to an existing SimObject.

Syntax


HRESULT SimConnect_AttachSimObjectToSimObject(
  HANDLE  hSimConnect,
  DWORD  dwObjectID1,
  SIMCONNECT_DATA_XYZ  vecOff1,
  SIMCONNECT_DATA_PBH  rotOff1,
  DWORD  dwObjectID2
  SIMCONNECT_DATA_XYZ  vecOff2
  SIMCONNECT_DATA_PBH  rotOff2
);

Parameters


hSimConnect
[in]  Handle to a SimConnect object.
dwObjectID1
[in]  ObjectID of the existing SimObject to attach to.
vecOff1
[in]  XYZ offset from dwObjectID1's model center to attachment point.
rotOff1
[in]  PBH offset from dwObjectID1's model body axis to attachment point.
dwObjectID2
[in]  ObjectID of the existing SimObject that is being attached to dwObjectID1.
vecOff2
[in]  XYZ offset from dwObjectID2's model center to attachment point.
rotOff2
[in]  PBH offset from dwObjectID2's model body axis to attachment point.


Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

See Also

SimConnect_ReleaseSimObjectFromSimObject

The SimConnect_ReleaseSimObjectFromSimObject function is used to release a SimObject from the SimObject it is attached to.

Syntax


HRESULT SimConnect_ReleaseSimObjectFromSimObject(
  HANDLE  hSimConnect,
  DWORD  dwObjectID1,
  DWORD  dwObjectID2
);

Parameters


hSimConnect
[in]  Handle to a SimConnect object.
dwObjectID1
[in]  ObjectID of the existing SimObject that dwObjectID2 is being released from.
dwObjectID2
[in]  ObjectID of the existing SimObject that is being released from dwObjectID1.


Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

See Also

Attach Weapon Specific Functions

Overview

The Attach Weapon APIs are used to attach one Weapon to a SimObject.  The attach call can be made multiple times to fill out the required number of weapons. The hardpoints must be setup on the SimObject in order to use the Attach Weapon APIs.

SimConnect_AttachWeaponToObject

The SimConnect_AttachWeaponToObject function is used to attach a Weapon to a SimObject.

Syntax


HRESULT SimConnect_AttachWeaponToObject(
  HANDLE  hSimConnect,
  const char*  szContainertitle,
  SIMCONNECT_OBJECT_ID  dwObjectID
  int  attachPoint
  int  numOfRounds
);

Weapon Examples
title=AIM-9M_Sidewinder
title=AGM-88_HARM
title=AIM-120_AMRAAM

Parameters


hSimConnect
[in]  Handle to a SimConnect object.
szContainertitle
[in]  null-terminated string containing title of the Weapon being attached to ObjectID.
dwObjectID
[in]  ObjectID of the existing SimObject.
attachPoint
[in]  int containing the station index from the object's Attachments.xml file.
numOfRounds
[in]  int containing the number of rounds of the weapon being attached.


Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

See Also

SimConnect_ClearWeapons

The SimConnect_ClearWeapons function is used to remove all Weapons from a SimObject.

Syntax


HRESULT SimConnect_ClearWeapons(
  HANDLE  hSimConnect,
  SIMCONNECT_OBJECT_ID  dwObjectID
);

Parameters


hSimConnect
[in]  Handle to a SimConnect object.
dwObjectID
[in]  ObjectID of the existing SimObject.


Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

See Also

External Sim Specific Functions

Overview

The External Sim APIs are used to write your own simulation code in a SimConnect Addon.  When using an External Sim, instead of your SimObject behaving like an aircraft, helicopter, boat, ground vehicle, etc, it will behave how ever the code in your external sim add-on wants it to.

There are two primary ways to use/create an External Sim based SimObject:

  1. Define a complete SimObject container that has a Category=ExternalSim line in the [General] section of the sim.cfg/aircraft.cfg file and at least an ExternalSimID = {GUID_STRING} line in the [fltsim.n] sections, for an External Secondary Sim, you just need an ExternalSecondarySimID = {GUID_STRING} in the [fltsim.n] section.  When using this method you can use the standard Select Aircraft/Vehicle dialog to select the SimObject for use, or any of the standard AICreateXxx SimConnect functions.  There is a Sample External Sim SimObject container included in the SDK that you can use as a reference/template for creating your own External Sim related SimObjects.

  2. Use the API functions that allow creating AI objects or User objects using an existing SimObject container but providing your own external sim code to run instead of whatever would normally run for that SimObject.  When using this method, you must use one of the External Sim related create/attach functions - SimConnect_AICreateObjectWithExternalSim, SimConnect_ChangeVehicleWithExternalSim, or SimConnect_AttachExternalSecondarySimToSimObject.

There are two types of External Sims:

  1. An External Sim which provides all of the required code to simulate the vehicles movement.  This provides the primary sim code for the SimObject.

  2. An External Secondary Sim which just provides additional simulation to another SimObject (the primary sim could be one of the built in categories, or another External Sim).  You could have a tracked vehicle primary sim, and then use an External Secondary Sim to provide the simulation/drive animation vars/etc for a tank turret, and the same tank turret External Secondary Sim could also be used with a Wheeled vehicle primary sim or a Boat vehicle primary sim.

The External Sim APIs use the Synchronous SimConnect functionality implicitly (meaning you need to use one of the Unblock methods in all of the External Sim related callbacks). This is why the Register External Sim function accepts a callback mask, set this to only include the callbacks you actually implement handlers for.

The first thing an External Sim add-on needs to do is use the RegisterExternalSim/RegisterExternalSecondarySim function to let SimConnect know you want to provide External Sim services.  To register, you provide a GUID (used to reference this external sim from sim.cfg/aircraft.cfg files or other API functions), a callback mask (set to only the callbacks you actually implement handlers for), and a structure definition ID of the data structure that will be passed to the Simulate callback.

Before your add-on code exits, it should use the UnregisterExternalSim/UnregisterExternalSecondarySim function to let SimConnect know you will no longer be providing services for that GUID.

There are 5 External Sim Callbacks:

  1. Create - this is called whenever a SimObject using your External Sim is created.

  2. Destroy - this is called whenever a SimObject using your External Sim is destroyed.

  3. Simulate - this is called every simulation frame for each SimObject using your External Sim.

  4. Location Changed - this is called whenever a SimObject has potentially moved, primarily due to user UI manipulations.

  5. Event - this is called whenever a mapped event occurs. In order to map specific events be sent to your external sim add-on, you use the MapClientEventToSimEvent function.

To programmatically create AI objects that use a specific External Sim, you use the AICreateObjectWithExternalSim function to load an existing SimObject but override it to use an External Sim instead.

To programmatically create a User object that uses a specific External Sim, you use the ChangeVehicleWithExternalSim function to load an existing SimObject but override it to use an External Sim instead.

For External Secondary Sims, you don't use a create function, instead you use AttachExternalSecondarySimToSimObject/ DetachExternalSecondarySimFromSimObject to attach/detach an External Secondary sim to/from an existing Simobject.

A primary External Sim can write to any of the defined SimVars. A Secondary External Sim can write to any of the defined SimVars that aren't already being handled by the primary sim.

An External Sim can also make use of the Ground Info APIs to get a small grid of ground data around it's SimObject.

Besides providing the ability to simulate the physics for a SimObject, the External Sim APIs can also be used to create pseudo-multiplayer style add-ons allowing some external data source (an Entity Generator or another sim) to drive SimObjects around the sim world.

SimConnect_RegisterExternalSim

The SimConnect_RegisterExternalSim function is used to register a SimConnect client as an external sim provider.

Syntax


HRESULT SimConnect_RegisterExternalSim(
  HANDLE  hSimConnect,
  const GUID  guidExternalSimID,
  SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG  CallbackMask,
  SIMCONNECT_DATA_DEFINITION_ID  DefineID
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
guidExternalSimID
[in]  The GUID used to denote this external sim.
CallbackMask
[in]  One or more members of the SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG enumeration that specify which External Sim Callbacks this client wants to receive.
DefineID
[in]  The data definition ID for any data you would like to have sent with the External Sim Simulate Callback.


Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

Working Sample

Primary sample External Sim

See Also

SimConnect_UnregisterExternalSim

The SimConnect_UnregisterExternalSim function is used to unregister a SimConnect client as an external sim provider.

Syntax


HRESULT SimConnect_UnregisterExternalSim(
  HANDLE  hSimConnect,
  const GUID  guidExternalSimID
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
guidExternalSimID
[in]  The GUID used to denote this external sim.


Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

Working Sample

Primary sample External Sim

See Also

SimConnect_RegisterExternalSecondarySim

The SimConnect_RegisterExternalSecondarySim function is used to register a SimConnect client as an external secondary sim provider.

Syntax


HRESULT SimConnect_RegisterExternalSecondarySim(
  HANDLE  hSimConnect,
  const GUID  guidExternalSecondarySimID,
  SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG  CallbackMask,
  SIMCONNECT_DATA_DEFINITION_ID  DefineID
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
guidExternalSecondarySimID
[in]  The GUID used to denote this external secondary sim.
CallbackMask
[in]  One or more members of the SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG enumeration that specify which External Sim Callbacks this client wants to receive.
DefineID
[in]  The data definition ID for any data you would like to have sent with the External Sim Simulate Callback.


Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

See Also

SimConnect_UnregisterExternalSecondarySim

The SimConnect_UnregisterExternalSecondarySim function is used to unregister a SimConnect client as an external secondary sim provider.

Syntax


HRESULT SimConnect_UnregisterExternalSecondarySim(
  HANDLE  hSimConnect,
  const GUID  guidExternalSecondarySimID
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
guidExternalSecondarySimID
[in]  The GUID used to denote this external secondary sim.


Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

See Also

SimConnect_AttachExternalSecondarySimToSimObject

The SimConnect_AttachExternalSecondarySimToSimObject function is used to attach an External Secondary Sim to an existing SimObject.

Syntax


HRESULT SimConnect_AttachExternalSecondarySimToSimObject(
  HANDLE  hSimConnect,
  DWORD  dwObjectID,
  const GUID  guidExternalSecondarySimID,
  const char *  szExternalSimParams,
  DWORD  dwExternalSimVarCount
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
dwObjectID
[in]  ID of the SimObject to attach to.
guidExternalSecondarySimID
[in]  The GUID of the external secondary sim you want to attach.
szExternalSimParams
[in]  A string containing parameters to pass to the external secondary sim. Not used internally, but retrievable through the EXTERNAL PRIMARY SIM DATA simulation variable.
dwExternalSimVarCount
[in]  Number of variables to allocate for this external secondary sim to use (range 0 to 999).


Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

See Also

SimConnect_DetachExternalSecondarySimFromSimObject

The SimConnect_DetachExternalSecondarySimFromSimObject function is used to detach an External Secondary Sim from an existing SimObject.

Syntax


HRESULT SimConnect_DetachExternalSecondarySimFromSimObject(
  HANDLE  hSimConnect,
  DWORD  dwObjectID,
  const GUID  guidExternalSecondarySimID,
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
dwObjectID
[in]  ID of the SimObject to attach to.
guidExternalSecondarySimID
[in]  The GUID of the external secondary sim you want to attach.


Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

See Also

SimConnect_AICreateObjectWithExternalSim

The SimConnect_AICreateObjectWithExternalSim function is used to create an AI object and override the sim to use a specific external secondary sim.

Syntax


HRESULT SimConnect_AICreateObjectWithExternalSim(
  HANDLE  hSimConnect,
  const char *  szContainertitle,
  SIMCONNECT_DATA_INITPOSITION  InitPos,
  SIMCONNECT_DATA_REQUEST_ID RequestID,
  const GUID  guidExternalSimID,
  const char *  szExternalSimParams,
  DWORD  dwExternalSimVarCount
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
szContainertitle
[in]  Null-terminated string containing the container title.
InitPos
[in]  Specifies the initial position, using a SIMCONNECT_DATA_INITPOSITION structure.
RequestID
[in]  Specifies the client defined request ID.
guidExternalSimID
[in]  The GUID of the external secondary sim you want to use to override the default SimObject's sim.
szExternalSimParams
[in]  A string containing parameters to pass to the external sim. Not used internally, but retrievable through the EXTERNAL PRIMARY SIM DATA simulation variable.
dwExternalSimVarCount
[in]  Number of variables to allocate for this external sim to use (range 0 to 999).


Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

See Also

SimConnect_ChangeVehicleWithExternalSim

The SimConnect_ChangeVehicleWithExternalSim function is used to load a new user vehicle and override the sim using a specific external sim.

Syntax


HRESULT SimConnect_ChangeVehicleWithExternalSim(
  HANDLE  hSimConnect,
  const char *  szContainertitle,
  const GUID  guidExternalSimID,
  const char *  szExternalSimParams,
  DWORD  dwExternalSimVarCount
);

Parameters

hSimConnect
[in]  Handle to a SimConnect object.
szContainertitle
[in]  Null-terminated string containing the container title.
guidExternalSimID
[in]  The GUID of the external secondary sim you want to use to override the default SimObject's sim.
szExternalSimParams
[in]  A string containing parameters to pass to the external sim. Not used internally, but retrievable through the EXTERNAL PRIMARY SIM DATA simulation variable.
dwExternalSimVarCount
[in]  Number of variables to allocate for this external sim to use (range 0 to 999).


Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value Description
S_OK The function succeeded.
E_FAIL The function failed.

See Also

- top -