Motion

Exposes Core Motion functionalities such as accessing the device’s accelerometer, gyroscope, and magnetometer data.

Tracking of motion metrics can impact performance and battery drain. Use this feature judiciously to avoid negatively affecting the user experience.

autoStart: boolean

If set, motion tracking will start automatically as soon as any attribute is read. Default is true.

Set to false if you want to control when motion is tracked manually using the start and stop functions.

motion.start(referenceFrame)

Start tracking motion metrics.

Parameters:

referenceFrame (number) – The reference frame in which to track motion metrics. Can be one of the following values:

  • motion.referenceFrame.XArbitraryZVertical (default): The X-axis is arbitrary and the Z-axis is vertical.

  • motion.referenceFrame.XArbitraryCorrectedZVertical: The X-axis is arbitrary and the Z-axis is vertical. If available, the magnetometer will be used to correct for accumulated yaw errors.

  • motion.referenceFrame.XMagneticNorthZVertical: The X-axis points toward the magnetic north and the Z-axis is vertical.

  • motion.referenceFrame.XTrueNorthZVertical: The X-axis points toward the true north and the Z-axis is vertical.

referenceFrame: table

Reference frame constants for motion tracking.

Parameters:

  • XArbitraryZVertical (const) – The X-axis is arbitrary and the Z-axis is vertical.

  • XArbitraryCorrectedZVertical (const) – The X-axis is arbitrary and the Z-axis is vertical. If available, the magnetometer will be used to correct for accumulated yaw errors.

  • XMagneticNorthZVertical (const) – The X-axis points toward the magnetic north and the Z-axis is vertical.

  • XTrueNorthZVertical (const) – The X-axis points toward the true north and the Z-axis is vertical.

motion.stop()

Stop tracking motion metrics and set autoStart to false.

updateInterval: number

The interval, in seconds, at which motion data is updated. This value can be set to control the frequency of motion updates. A lower value means more frequent updates, which can provide smoother motion tracking but may consume more power. The default value is 1/30 second.

Note that the interval is clamped between limits defined by the system.

gravity: vec2

The gravity vector in the device’s reference frame. This vector is automatically rotated to follow device orientation changes.

acceleration: vec2

The acceleration vector in the device’s reference frame. This vector is automatically rotated to follow device orientation changes.

rotationRate: vec2

The rotation rate in the device’s reference frame. This vector is automatically rotated to follow device orientation changes.

sensorLocation: table

Sensor location constants.

Parameters:

  • default (const) – The location of the device’s sensors is the default one.

  • headphoneLeft (const) – The device’s sensors are located near the left headphone.

  • headphoneRight (const) – The device’s sensors are located near the right headphone.

heading: number

The heading in degrees relative to the current reference frame.

Device Orientation

attitude: table

Represents a measurement of your device attitude. This orientation of a body relative to a given frame of reference.

You can set motion.attitude.referenceFrame to specify the frame of reference in which the attitude is expressed.

The value can be one of the following motion.referenceFrame.XArbitraryZVertical, motion.referenceFrame.XArbitraryCorrectedZVertical, motion.referenceFrame.XMagneticNorthZVertical, motion.referenceFrame.XTrueNorthZVertical.

Parameters:

  • pitch (number) – The pitch of the device, in radians.

  • yaw (number) – The yaw of the device, in radians.

  • roll (number) – The roll of the device, in radians.

  • rotationMatrix (mat3x3) – The rotation matrix that describes the device’s orientation.

  • quaternion (quat) – The quaternion that describes the device’s orientation.

  • referenceFrame (integer) – The reference frame in which motion metrics are tracked.

Magnetic Field Data

magnetic: table

Magnetic field data.

Parameters:

  • field (vec3) – The magnetic field vector in the device’s reference frame.

  • accuracy (integer) – The accuracy of the magnetic field data.

magneticAccuracy: table

Magnetic field accuracy constants.

Parameters:

  • uncalibrated (const) – The magnetic field data is uncalibrated.

  • low (const) – The magnetic field data is of low accuracy.

  • medium (const) – The magnetic field data is of medium accuracy.

  • high (const) – The magnetic field data is of high accuracy.