From X-Plane SDK
Revision as of 13:15, 15 April 2009 by Bsupnik (Talk)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
This page was imported from the previous wiki engine. It needs a review and cleanup of formatting. Please see this page for more information.
!!! Positioning planes in X-Plane

This note describes how to position the user's aircraft or multiplayer aircraft in X-Plane. Positioning the user's plane can be broadly divided into two cases:

  1. Positioning the user's plane once while the physics engine is running. Example: positioning the user for an ILS approach in a training situation.
  2. Positioning the user's plane continuously while the physics engine is not running. Example: visualizing flight data recorder information.

Generally most datarefs for positioning the user's plane are contained in sim/flightmodel/position/.

! A note on precision

All datarefs in this section are listed on the web page as either type int, float, or double. When a dataref is listed as float, it is internally stored in 32-bit floating point format. When a dataref is listed as double on the web page, it is internally stored in 64-bit double precision floating point format, but is accessable as both a float and a double for convenience. You may use either the double or float routines to write the dataref, depending on the precision you need.

Generally you will need to use double precision to work with latitude and longitude precisely. Because the local coordinate system moves to keep the plane near the origin, single precision should be adequate for cartesian XYZ values. The routines XPLMWorldToLocal and XPLMLocalToWorld work in double precision on the latitude-longitude side.

!! Positioning the User's Plane While the Physics Engine is Running

While the physics engine is running, you may position the user's plane; it will instantly move and then continue in the direction it was flying (or the direction you specify). Do not continuously reposition the user's plane with the physics engine running; your positioning commands and the physics engine will thrash the plane around.

! Positioning the Plane in Space

To place the user's plane, you position it in local coordinates (see ScreenCoordinates). This is a cartesian axis in meters. Use these datarefs:


You can read or write these datarefs at any time. You cannot write these datarefs:


X-Plane will calculate the latitude/longitude and elevations (AGL and MSL) for you from the local cartesian coordinates. If you need to place the plane based on latitude/longitude information, use the function XPLMWorldToLocal to convert coordinates.

Example: subtract 10 from sim/flightmodel/position/local_z; the plane hops 10 meters in the air and then continues.

! Orienting the Plane in Space

The plane's orientation is described by three rotations, "psi" (heading), "theta" (pitch), and "phi" (roll). However when the physics model is on, things are a bit more complicated. The datarefs


are read by the graphics engine to draw the plane. They are written by the physics model. The data ref


is read and written by the physics model and is the __master__ copy of the plane's orientation when the physics model is in. Every frame, the physics model updates q and then copies the values to psi, theta and phi. (Warning: datarefs are case sensitive; lower case q here is the quaternion plane rotation, while Q is a rotational rate of the plane.)

The dataref q here is a [quaternion |], stored as an array of four floats. Quaternions are mathematical constructs that (among other things) can fully describe an aribitrary rotation in 3-dimensional space. If you want to reorient the aircraft, you must write to q. Like local_x, local_y, and local_z, this will affect the sim immediately and the sim will continue from that position.

The following datarefs cannot be written:


They will be calculated based on the orientation you set, the plane's velocity, and the local wind conditions and magnetic variation.

Example: write a value of 0.1 to item 1 of sim/flightmodel/position/q. The plane rolls to the right.

! Changing the Plane's Velocity

While the sim is running, you can change the aircraft's velocity, both linearly and rotationally. The linear velocity of the plane is controlled by three values:


This determines both the plane's direction (in 3-d space) and its speed. Units are meters per second. This vector is in the world coordinate system; a velocity along the X axis moves the plane east no matter which way the plane is heading. The datarefs


are all derived from this one velocity vector. Please note that the values alpha, beta, hpath and vpath are also affected by this velocity vector; if the velocity vector points along the X axis but the plane is oriented along the Z axis, then the plane will be in a very heavy state of yaw.

Example: write 20 into sim/flightmodel/position/local_vy. The plane is launched up in the air.

You can also spin the plane by writing to the datarefs P, Q, and R, which are the rotation rates of the plane in degrees per second. Positive P rolls the plane to the right; Q pitches the plane up; positive R yaws the plane to the right.


You cannot write to the angular momentum datarefs N, M, and L; these are written by the flight model every frame.

You also cannot write to P_dot, Q_dot, or R_dot (angular accelerations) or the linear accelerations (local_ax, local_ay, and local_az).

Example: write a value of 20 to sim/flightmodel/position/Q. The aircraft rotates upward like Dr. Dre's car.

__WARNING:__The interaction of P, Q, and R vs. Prad, Qrad and Rrad is pretty sim specific. I do not recommend attempting to change the rotation rate of the plane.

!! Positioning the User's Plane While the Physics Engine is Not Running

The dataref


Controls whether X-Plane's physics engine is controlling the user's plane. It contains one element for each plane. You can set the first element to one to disable the physics model.

__WARNING:__ Do not use this dataref to disable AI planes; use the XPLMMultiplayer APIs described below instead. Future SDKs may not support more than one element in sim/operation/override/override_planepath.

Once you disable the physics model, the following things change:

  • The quaternion rotation is no longer used or copied to psi, theta and phi. Instead, change the plane's orientation directly by writing to psi, theta, and phi.
  • The plane will basically hold any position and orientation you set.
  • Derived variables like indicated_airspeed and alpha will not be updated.

Once you reenable the physics model, the plane will continue based on 'q', the quaternion rotation, not the orientation you wrote with psi, theta and phi.

Example: write 1 to sim/operation/override/override_planepath[0]. Then write 40 to sim/flightmodel/position/theta and 100 to sim/flightmodel/position/indicated_airspeed. The plane will pitch up 40 degrees and indicate 100 knots, but the stall horn will not go off. Then write 40 to sim/flightmodel/position/alpha. The stall horn will sound.

__WARNING:__ The interaction with the instrument system when physics are disabled is a bit complex and may be subject to change.

! Transitioning From Disabled to Enabled Flight Model

When you re-enable the flight model, the sim will continue based on the velocity vector and quaternion q. So if you have set up the plane based on phi, psi, and theta for orientation, and some kind of speed, you will need to set the velocity vector to give the plane speed along its current heading, and conform the quaternion q to the current rotations. Once you do this, re-enabling the flight model should be relatively smooth.

!! Controlling the Other Aircraft

X-Plane also features up to nine other multiplayer aircraft. Generally they are controlled with the sim/multiplayer/position datarefs. Before controlling the aircraft, your plugin should call XPLMAcquireAircraft. This gives your plugin exclusive rights to these multiplayer planes. You will lose control of the planes when your plugin is disabled, so call XPLMAcquireAircraft whenever your plugin is enabled. If XPLMAcquireAircraft fails, it probably means another plugin is using multiplayer planes.

Once you have control of the aircraft, you can disable X-Plane's control over their position by calling XPLMDisableAIForPlane. The plane will now hold still until you reposition it.

Up through v8.40, AI aircraft were controlled by simple calculations constituting an "AI Flight Model". This can be overridden by setting the [sim/operation/override/override_planepath |] dataref for the aircraft you wish to control. When this dataref is set, the aircraft will not move on its own - you will need to provide a continuous set of positions and rotations, updated once per frame. These are controlled by sim/multiplayer/position/* datarefs found [here |].

This changed slightly with v8.50 in that AI aircraft feature a full flight model for the aircraft it is currently flying. The AI controls the aircraft via auto-pilot inputs. Just like v8.40, setting the [sim/operation/override/override_planepath |] dataref will override this behavior. As such, you will need to provide the same stream of positions and rotations for that aircraft, updated once per plane.

In v8.60, the AI aircraft feature a full flight model and are controlled in the same manner by the AI - via auto-pilot inputs. However, as of v8.60 we have a new dataref available, [sim/operation/override/override_plane_ai_autopilot |]. Setting this dataref allows us to disable the AI control of the aircraft, while retaining the full flight model. You are then able to control the aircraft by setting the auto-pilot datarefs for that aircraft, just as the AI would do on its own. See sim/cockpit/autopilot/* [here |] for available datarefs.

! Moving the Plane A Long Way (Around the Earth)

(This is a paste from an email to the dev needs cleanup.)

Starting with X-Plane 850 beta 9, plugins now can position the plane anywhere in the world without a crash. Here are some details:

(all datarefs are ins im/flightmodel/position/)

1. You do not ever have to override the flight model to move the plane. If you alter local_x, local_y and local_z the plane jumps instantly.

2. To move the plane a small amount, simply change local_x, local_y, and local_z.

3. To move the plane a LONG way, you must change local_x, local_y and local_z as well as latitude and longitude! Use XPLMWorldToLocal or XPLMLocalToWorld to get the "other" coordinate system (depending on whether your positioning is based on cartesian or geographic coords). This will only work in 850 beta 9 and newer.

4. Don't position the plane inside the earth. Enough said. ;-)

5. You do not need to, should not, and in 850 cannot write to lat_ref and lon_ref. The sim will pick this value for you as it processes scenery.

6. If "load scenery while flying" is off (very rare for home users - this is only meant for professional users), then global movement of the plane will _not_ work.

7. Just a warning: the orientation of the plane is in cartesian coordinates. So if you position the plane from latitude 45N to latitude 45S, the plane will be rotated 90 degrees relative to the horizon! This is because the horizon has rotated 90 degrees and the plane has not.

7a. The coordinate shift happens after you write your datarefs.'ll need to calculate the change in attitude/rotation yourself (and write the 'q' variable - see the SDK tech notes for more on positioning the plane) as you write xyz, anticipating the horizon angle changing.

8. In the future it may not be necessary to write lat/lon and xyz, but it won't be harmful. Please always write CONSISTENT results - e.g. don't write a lat/lon that are different from xyz (based on the current XPLMWorldToLocal and XPLMLocalToWorld conversions).