Class LocationSensor
Input device representing a GPS location sensor.
Inherited Members
Namespace: UnityEngine.InputSystem
Assembly: Unity.InputSystem.dll
Syntax
public class LocationSensor : Sensor
Remarks
A location sensor reports the device's geographic position (latitude, longitude, altitude). After enabling it with EnableDevice(InputDevice), the location service may take several seconds to acquire valid data, so readings are only valid once status reaches Running. Accessing location requires the user to have granted permission (isEnabledByUser). The sensor's presence (current being non-null) does not guarantee the location service is available or running; query status and isEnabledByUser to determine that.
Do not drive location from both this device and the legacy UnityEngine.Input.location API in the
same project. Both share the same underlying platform location service, so disabling this device also
stops updates for the legacy API (and vice versa). Use a single location API per project.
On Android and iOS the required location permission (Android) and usage description (iOS) are added to the
build automatically only when your compiled code references LocationSensor directly. If you
access the sensor solely through an .inputactions asset binding and never reference the type in code,
this detection does not trigger and the build ships without them, so the service fails to start at runtime.
Reference LocationSensor in code (for example by accessing current once),
or add the platform permission and usage description manually.
Properties
altitude
Altitude in meters.
Declaration
public AxisControl altitude { get; protected set; }
Property Value
| Type | Description |
|---|---|
| AxisControl |
current
The location sensor that most recently became current.
Declaration
public static LocationSensor current { get; }
Property Value
| Type | Description |
|---|---|
| LocationSensor | Current location sensor or |
Remarks
When a location sensor is added, it becomes current, because not all of its controls are noisy. When the current location sensor is removed, the remaining location sensor that was updated last becomes current. For more information about when a device becomes current, refer to MakeCurrent().
horizontalAccuracy
Horizontal accuracy of the reading in meters.
Declaration
public AxisControl horizontalAccuracy { get; protected set; }
Property Value
| Type | Description |
|---|---|
| AxisControl |
isEnabledByUser
Whether the user has granted the app permission to access the device location.
Declaration
public bool isEnabledByUser { get; }
Property Value
| Type | Description |
|---|---|
| bool |
Remarks
A user can grant permission while the service is not running. If permission is denied, the service won't reach Running. Must be accessed from the main thread only.
latitude
Latitude in degrees.
Declaration
public AxisControl latitude { get; protected set; }
Property Value
| Type | Description |
|---|---|
| AxisControl |
longitude
Longitude in degrees.
Declaration
public AxisControl longitude { get; protected set; }
Property Value
| Type | Description |
|---|---|
| AxisControl |
status
Current status of the location service.
Declaration
public LocationServiceStatus status { get; }
Property Value
| Type | Description |
|---|---|
| LocationServiceStatus |
Remarks
After the sensor is enabled the service starts asynchronously, passing through Initializing before it reaches Running. Readings are only valid while running. Must be accessed from the main thread only.
timestamp
Time the reading was taken, in seconds since the epoch used by the platform location service.
Declaration
public DoubleControl timestamp { get; protected set; }
Property Value
| Type | Description |
|---|---|
| DoubleControl |
verticalAccuracy
Vertical accuracy of the reading in meters.
Declaration
public AxisControl verticalAccuracy { get; protected set; }
Property Value
| Type | Description |
|---|---|
| AxisControl |
Methods
Configure(float, float)
Sets the desired accuracy and update-distance threshold for location readings.
Declaration
public void Configure(float desiredAccuracyInMeters, float updateDistanceInMeters)
Parameters
| Type | Name | Description |
|---|---|---|
| float | desiredAccuracyInMeters | Desired horizontal accuracy, in meters. |
| float | updateDistanceInMeters | Minimum distance the device must move before a new reading is reported, in meters. |
Remarks
By default, the sensor is configured with the values from locationAccuracy and locationDistanceThreshold. ResetConfiguration() returns to those defaults.
If the sensor is already enabled, readings may briefly pause while they are applied. If the sensor is disabled, values apply when the device is enabled. Must be called from the main thread only.
FinishSetup()
Perform final initialization tasks after the control hierarchy has been put into place.
Declaration
protected override void FinishSetup()
Overrides
Remarks
This method can be overridden to perform control- or device-specific setup work. The most common use case is for looking up child controls and storing them in local getters.
Examples
public class MyDevice : InputDevice
{
public ButtonControl button { get; private set; }
public AxisControl axis { get; private set; }
protected override void OnFinishSetup()
{
// Cache controls in getters.
button = GetChildControl("button");
axis = GetChildControl("axis");
}
}
MakeCurrent()
Makes this device the current device of its type.
Declaration
public override void MakeCurrent()
Overrides
Remarks
Many types of devices have .current getters that return the current device of that type
(for example, current). The current device of a type is the device of that
type that most recently became current. For a built-in sensor, the type is the class that derives directly
from Sensor. For example, an Android gyroscope becomes current.
The Input System calls this method in the following cases:
- When a device is added. If all the device's controls are noisy, the device becomes current only if no other device of its type is current. For example, a second gyroscope doesn't replace the first one as current, because all of a gyroscope sensor's controls are noisy.
- When input changes a control that isn't noisy. Input on noisy controls doesn't call this method.
- When a device's usage changes, with the same rule as when the device is added.
- When a layout change recreates a device. The new device is current if the old one was.
- When a device is removed. The remaining device of its type that was updated last becomes current.
If no device of that type is left,
.currentisnull. If you remove a sensor that isn't current,.currentstays the same.
A device with noisy controls (noisy) can receive events that carry no user interaction. For example, the PlayStation®4 (PS4) gamepad has a gyro and keeps sending events when nobody uses it. Without the rule for noisy controls, the PS4 gamepad would make itself current while the user plays with another gamepad.
When you call this method yourself, the device becomes current even if its controls are noisy.
If you override this method, call base.MakeCurrent(). Otherwise, the built-in .current
getters don't return the device, and the rules above don't apply to it.
See Also
OnAdded()
Called by the system when the device is added to devices.
Declaration
protected override void OnAdded()
Overrides
Remarks
This is called after the device has already been added. devicesAddedOnRemoved()
Examples
using UnityEngine.InputSystem;
public class MyDevice : InputDevice
{
public static MyDevice current { get; private set; }
protected override void OnAdded()
{
// use this context to assign the current device for instance
base.OnAdded();
current = this;
}
}
OnRemoved()
Called by the system when the device is removed from devices.
Declaration
protected override void OnRemoved()
Overrides
Remarks
Examples
using UnityEngine.InputSystem;
public class MyDevice : InputDevice
{
public static MyDevice current { get; private set; }
protected override void OnRemoved()
{
// use this context to unassign the current device for instance
base.OnRemoved();
if (current == this)
current = null;
}
}
ResetConfiguration()
Reverts the accuracy and update-distance threshold to the InputSettings defaults.
Declaration
public void ResetConfiguration()
Remarks
Subject to the same application timing as Configure(float, float). Must be called from the main thread only.