Google.Maps.MapsService

The MapsService class serves as the entry point for interacting with the Maps Unity SDK.

Summary

The SDK instantiates this class as a Unity script component called Maps Service (Script). You use it in a Unity scene by adding the Maps Service (Script) component to an empty GameObject in your scene. This GameObject becomes your anchor—and the map feature GameObjects that the SDK generates are added as its children.

You can configure options using the Inspector, but you cannot change most options after calling Awake (for example, you cannot change the ZoomLevel). However, you can create multiple MapsService instances, each with different properties. For example, you could add a bird's-eye mini-map with a different zoom level to your main map.

Inheritance

Inherits from: Google.Maps.Unity.HotLoadableMonoBehaviour, Google.Maps.IGameObjectOptionsProvider

Properties

CacheOptions
A container of parameters used for caching map data.
Coords
The game world coordinate system.
Events
A container for all of the events fired by the SDK.
GameObjectManager
Tracks destroyed and suppressed GameObjects.
RoadLattice
Global road lattice for this MapsService. Maintains a graph of roads in loaded tiles, stitched across tile boundaries.
Version
static string
The version of the Maps SDK for Unity.

Public attributes

ApiKey
string
The API key. You must have both the Semantic Tile API and the Playable Locations API enabled. For more information, see Get API Key.
CountryProvider
Country code provider.
EnableDiagnostics = true
bool
Specifies whether to send diagnostic information to Google. An example of diagnostic information is frame rate.
EnableExhaustiveIntersectionReconstruction = true
bool
Specifies whether to enable extra, expensive searching for road intersections.
EnableIntersections = false
bool
Specifies whether to enable the display of extra geometry at road intersections. Applicable only when EnableRoadLattice is true.
EnableModeledStructures = true
bool
Specifies whether to enable Feature.ModeledStructure features.
EnablePrivateRoads = false
bool
Specifies whether loaded map will include roads (Feature.Segment) that are marked private. A road may be marked private because it has signage discouraging or prohibiting use by the general public (e.g., roads with signs that say "Private", or "No trespassing.") or if it is within a gated community or other private area. Care should be taken when enabling private roads in localities where encouraging gameplay around these roads is discouraged by local expectations.
EnableRoadLattice = false
bool
Specifies whether to build and maintain a road lattice from the roads in the currently loaded portion of the map.
EnableTerrain = false
bool
Specifies whether the loaded map will include terrain data. Terrain data describes continuous properties that cover the entire landscape, such as elevation.
LanguageCode
string
The BCP-47 language code corresponding to the language that Map content should be localized with (for example "en-US" or "sr-Latn").
MapPreviewOptions = new MapPreviewOptions()
Options for edit-time preview of map.
MaxBasemapSortingOrder = -1
int
The maximum sorting order to use for basemap objects generated by MapsService. MapsService manages Renderer.sortingOrder on game objects generated by the SDK in order to achieve the correct rendering order for features. All game objects that should display above the basemap should have a sorting order greater than this value.
MetadataOptions = new MetadataOptions()
Options controlling how and if metadata is attached to game objects.
MinBasemapSortingOrder = -32767
int
The minimum rendering sort order to use for basemap objects generated by MapsService. MapsService manages Renderer.sortingOrder on game objects generated by the SDK in order to achieve the correct rendering order for features.
NetworkPoolSize = 100
int
Maximum number of concurrent connections to the Semantic Tile API.
NetworkTimeoutSeconds = 10
int
The maximum length of time (in seconds) to wait for a response after requesting map data.
NonBasemapSortingOrder = 0
int
The sorting order to use for non-basemap objects generated by MapsService. MapsService manages Renderer.sortingOrder on game objects generated by the SDK to achieve the correct rendering order for features.
ObjectCreationFrameBudget = 0
long
The maximum length of time (in milliseconds) per frame to use for creating GameObjects.
StaticBatching = false
bool
Specifies whether to enable static batching for all generated GameObjects.
TerrainOptions = new TerrainOptions()
Options for configuring Terrain.
ZoomLevel = 17
int
The map zoom (magnification) level.

Public functions

GetPreviewBounds()
Bounds
Gets the bounds covered by the edit-time preview. Works in play mode.
InitFloatingOrigin(LatLng floatingOrigin)
void
Sets the initial origin of the coordinate system.
LoadMap(Bounds bounds, GameObjectOptions options)
void
Loads a rectangular region (bounds) of the map.
MakeMapLoadRegion()
Initializes a MapLoadRegion object to load a region of the map.
MaybeGetGameObjectOptions()
Get the game object options (including style settings) that have been attached to this MapsService. See also:StyleAttachment
MoveFloatingOrigin(LatLng floatingOrigin, ICollection< GameObject > gameObjects)
Vector3
Re-establishes the origin based on a new Coord.LatLng value.
MoveFloatingOrigin(Vector3 floatingOrigin, ICollection< GameObject > gameObjects)
Vector3
Reestablishes the origin based based on a new Vector3 value.
RefreshPreview()
void
Force preview to refresh.
ResolveApiKey()
string
Resolves which API key to use.

Public static functions

EnableVerboseLogging(bool enable)
void
Specifies whether to enable verbose logging.

Protected functions

Destroy()
virtual override void
Handle object destruction.
Disable()
virtual override void
Disable the instance.
Enable()
virtual override void
Enable the instance.
FrameUpdate()
virtual override void
Handle Unity's Update event.
Shutdown()
virtual override void
Handle component shutdown.
Startup()
virtual override void
Handle component startup.

Properties

CacheOptions

CacheOptions CacheOptions

A container of parameters used for caching map data.

If you modify this field after Awake is called, then your change won't take effect.

Coords

Coords Coords

The game world coordinate system.

Manages the floating origin, Mercator scale, and converts between Unity Worldspace (Vector3), Earth-scale Mercator Space (Vector2D), and Google Maps Tile Coordinates (TileCoord). Note: You must set the floating origin before using the coordinate system.

See also: InitFloatingOrigin

Details
Exceptions
FloatingOriginNotSetException
Thrown when you use the coordinate system before setting the floating origin.

Events

Events Events

A container for all of the events fired by the SDK.

Events are part of the mechanism that allows you to style map feature GameObjects. For example, the SDK fires WillCreate and DidCreate events when it generates Feature.MapFeature objects and their corresponding GameObject during map loading. These events contain geometry information and metadata that you can use to style the GameObject.

GameObjectManager

GameObjectManager GameObjectManager

Tracks destroyed and suppressed GameObjects.

It notifies the SDK whenever a GameObject is destroyed so that it can then be recreated properly on subsequent calls to MapsService.LoadMap.

RoadLattice

RoadLattice RoadLattice

Global road lattice for this MapsService. Maintains a graph of roads in loaded tiles, stitched across tile boundaries.

The road lattice is in Unity World Space relative to the origin of the GameObject to which this Maps Service is attached, so the RoadLattice must be updated when the floating origin is updated.

Version

static string Version

The version of the Maps SDK for Unity.

Public attributes

ApiKey

string ApiKey

The API key. You must have both the Semantic Tile API and the Playable Locations API enabled. For more information, see Get API Key.

Note: If you modify this field after calling Awake, it has no effect.

CountryProvider

CountryProvider CountryProvider

Country code provider.

EnableDiagnostics

bool EnableDiagnostics = true

Specifies whether to send diagnostic information to Google. An example of diagnostic information is frame rate.

Caution: You must set this value before the Unity runtime calls Awake.

EnableExhaustiveIntersectionReconstruction

bool EnableExhaustiveIntersectionReconstruction = true

Specifies whether to enable extra, expensive searching for road intersections.

This flag can be used to find road intersections that have been optimized out of the source data.

EnableIntersections

bool EnableIntersections = false

Specifies whether to enable the display of extra geometry at road intersections. Applicable only when EnableRoadLattice is true.

This will add a slight map loading overhead and small increase in number of triangles rendered per frame.

EnableModeledStructures

bool EnableModeledStructures = true

Specifies whether to enable Feature.ModeledStructure features.

When set to false, Feature.ExtrudedStructure features are used instead, which results in reduced network traffic, CPU usage, and memory usage.

If you modify this field after Awake is called, then your change won't take effect.

EnablePrivateRoads

bool EnablePrivateRoads = false

Specifies whether loaded map will include roads (Feature.Segment) that are marked private. A road may be marked private because it has signage discouraging or prohibiting use by the general public (e.g., roads with signs that say "Private", or "No trespassing.") or if it is within a gated community or other private area. Care should be taken when enabling private roads in localities where encouraging gameplay around these roads is discouraged by local expectations.

EnableRoadLattice

bool EnableRoadLattice = false

Specifies whether to build and maintain a road lattice from the roads in the currently loaded portion of the map.

Enabling this will add overhead to each load of a non-cached map region.

EnableTerrain

bool EnableTerrain = false

Specifies whether the loaded map will include terrain data. Terrain data describes continuous properties that cover the entire landscape, such as elevation.

Note: Terrain elevation is only available for zoom levels 8 and beyond. If elevation is requested for levels out of this range, a flat terrain with a uniform altitude of zero meters above mean sea level will be returned.

LanguageCode

string LanguageCode

The BCP-47 language code corresponding to the language that Map content should be localized with (for example "en-US" or "sr-Latn").

More details about the BCP-47 language code can be found at http://www.unicode.org/reports/tr35/#Unicode_locale_identifier.

If not specified the current SystemLanguage will be used. Warning: Specifying a language other than the current System language is not recommended, as text labels on the map will be shown in a language potentially unfamiliar to the user, and potentially in a character set they cannot read. Use with caution.

MapPreviewOptions

MapPreviewOptions MapPreviewOptions = new MapPreviewOptions()

Options for edit-time preview of map.

MaxBasemapSortingOrder

int MaxBasemapSortingOrder = -1

The maximum sorting order to use for basemap objects generated by MapsService. MapsService manages Renderer.sortingOrder on game objects generated by the SDK in order to achieve the correct rendering order for features. All game objects that should display above the basemap should have a sorting order greater than this value.

MetadataOptions

MetadataOptions MetadataOptions = new MetadataOptions()

Options controlling how and if metadata is attached to game objects.

If you modify this field after Awake is called, then previously-created objects won't be updated to reflect the new options.

MinBasemapSortingOrder

int MinBasemapSortingOrder = -32767

The minimum rendering sort order to use for basemap objects generated by MapsService. MapsService manages Renderer.sortingOrder on game objects generated by the SDK in order to achieve the correct rendering order for features.

NetworkPoolSize

int NetworkPoolSize = 100

Maximum number of concurrent connections to the Semantic Tile API.

If you use a value less than 100, then you should expect longer load times for map data.

Warning: This field is experimental. Its value might change in a future release.

NetworkTimeoutSeconds

int NetworkTimeoutSeconds = 10

The maximum length of time (in seconds) to wait for a response after requesting map data.

When you set this value to 0, there is no limit to the wait time.

Note: This attribute is an integer rather than a floating point due to a limitation of the UnityWebRequest object.

NonBasemapSortingOrder

int NonBasemapSortingOrder = 0

The sorting order to use for non-basemap objects generated by MapsService. MapsService manages Renderer.sortingOrder on game objects generated by the SDK to achieve the correct rendering order for features.

ObjectCreationFrameBudget

long ObjectCreationFrameBudget = 0

The maximum length of time (in milliseconds) per frame to use for creating GameObjects.

Setting this to 0 defaults to 40ms.

This field can be modified at any time to change the current rate of creating GameObjects.

StaticBatching

bool StaticBatching = false

Specifies whether to enable static batching for all generated GameObjects.

When enabled, GameObjects are statically batched, unless otherwise specified in the corresponding WillCreate event.

If you modify this field after calling Awake, then your change won't take effect.

TerrainOptions

TerrainOptions TerrainOptions = new TerrainOptions()

Options for configuring Terrain.

ZoomLevel

int ZoomLevel = 17

The map zoom (magnification) level.

Controls the level of detail of map data (the set of feature types returned, their density, and geometry simplification). This determines the size of the requested map tiles.

The default zoom level is 17—which is considered appropriate for location-based games because lower zoom levels can miss important features such as buildings. Zoom level 17 is also considered more stable, meaning the set of features returned is less likely to change.

If you modify this field after Awake is called, then your change won't take effect.

Public functions

GetPreviewBounds

Bounds GetPreviewBounds()

Gets the bounds covered by the edit-time preview. Works in play mode.

Details
Returns
The bounds covered by the edit-time preview.

InitFloatingOrigin

void InitFloatingOrigin(
  LatLng floatingOrigin
)

Sets the initial origin of the coordinate system.

When converting Coord.LatLng values to and from Unity Worldspace, Vector3 values are translated relative to the current origin.

The initial origin value is used to determine the Unity Worldspace scale for the entire gaming session. Mercator scale is based on the latitude, per the Web Mercator projection.

The recommended floatingOrigin value to use is the player's starting location. It should be near the player's current location to ensure that Unity Worldspace Vector3 values remain small to avoid single precision floating point errors.

Details
Parameters
floatingOrigin
The initial origin value.
Exceptions
System.InvalidOperationException
Thrown when the origin has already been set.

LoadMap

void LoadMap(
  Bounds bounds,
  GameObjectOptions options
)

Loads a rectangular region (bounds) of the map.

GameObjects are asynchronously created for all map features within the bounds that you specify. Note: You must set the origin to Maps.Coord.Coords before calling this method.

Calling this function is equivalent to calling LoadMapRegion().Bounds(bounds).Load(options).

See also: InitFloatingOrigin

Details
Parameters
bounds
Defines a rectangular region.
options
User defined options which customise map construction.
Exceptions
FloatingOriginNotSetException
Thrown when the floating origin isn't set.

MakeMapLoadRegion

MapLoadRegion MakeMapLoadRegion()

Initializes a MapLoadRegion object to load a region of the map.

GameObjects are asynchronously created for all map features within the bounds that you specify. You must set the floating origin to Maps.Coord.Coords before calling this method.

The MapLoadRegion returned by this method is cleared and reused between calls to avoid unnecessary garbage collection.

The following example loads the region of the map visible in the main camera's viewport.

MapsService.MakeMapLoadRegion().AddViewport(Camera.main).Load(options);
  

MaybeGetGameObjectOptions

GameObjectOptions MaybeGetGameObjectOptions()

Get the game object options (including style settings) that have been attached to this MapsService. See also:StyleAttachment

Details
Returns
The attached game object options.

MoveFloatingOrigin

Vector3 MoveFloatingOrigin(
  LatLng floatingOrigin,
  ICollection< GameObject > gameObjects
)

Re-establishes the origin based on a new Coord.LatLng value.

You should re-establish the origin whenever the user moves far enough away from the origin that floating errors become noticeable.

This method translates all map feature GameObjects created by the SDK. You can pass in additional GameObjects to be translated. You can also use the returned Vector3 offset value to manually translate additional GameObjects yourself.

This method is an overload of the method MoveFloatingOrigin(Vector3, ICollection<GameObject>).

See Also:InitFloatingOrigin(LatLng).

The following code snippet re-establishes the origin to London. Two camera objects are also moved, to keep all GameObjects in the same position relative to the camera.

MapsService.MoveFloatingOrigin(
        new LatLng(51.5081, -0.0760),
        new GameObject[] {camera1, camera2});
  

Details
Parameters
floatingOrigin
The new origin value.
gameObjects
Additional GameObjects to be translated (if there are any).
Exceptions
FloatingOriginNotSetException
Thrown when the origin has not been set.
Returns
A Vector3 offset that you can use for manually translating GameObjects to reposition them relative to the new origin.

MoveFloatingOrigin

Vector3 MoveFloatingOrigin(
  Vector3 floatingOrigin,
  ICollection< GameObject > gameObjects
)

Reestablishes the origin based based on a new Vector3 value.

This method is an overload of the method MoveFloatingOrigin(LatLng, ICollection<GameObject>).

See also: InitFloatingOrigin(LatLng)

Details
Parameters
floatingOrigin
The new origin as a Vector3 value.
gameObjects
Additional GameObjects to be moved (if there are any).
Exceptions
FloatingOriginNotSetException
Thrown when the floating origin has not been set.
Returns
A Vector3 offset value, for manually moving GameObjects.

RefreshPreview

void RefreshPreview()

Force preview to refresh.

ResolveApiKey

string ResolveApiKey()

Resolves which API key to use.

Details
Returns
The API Key to use.

Public static functions

EnableVerboseLogging

void EnableVerboseLogging(
  bool enable
)

Specifies whether to enable verbose logging.

Enables/disables logging verbose debug information to the Unity console. Note: This feature is available only in debug builds.

Details
Parameters
enable
Specifies whether to enable or disable verbose logging.

Protected functions

Destroy

virtual override void Destroy()

Handle object destruction.

Disable

virtual override void Disable()

Disable the instance.

Enable

virtual override void Enable()

Enable the instance.

FrameUpdate

virtual override void FrameUpdate()

Handle Unity's Update event.

Shutdown

virtual override void Shutdown()

Handle component shutdown.

Startup

virtual override void Startup()

Handle component startup.