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, Google.Maps.IDiagnosableService
Constructors and Destructors |
|
---|---|
MapsService()
Constructor.
|
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.
|
FeatureTileApiUrlFormat = DefaultFeatureTileApiUrlFormat
|
string
The format string to be used for constructing HTTP Feature Tile requests. The format items will be replaced with (x, y, z) coordinates for requesting tiles.
|
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.
|
TerrainTileApiUrlFormat = DefaultTerrainTileApiUrlFormat
|
string
The format string to be used for constructing HTTP Terrain Tile requests. The format items will be replaced with (x, y, z) coordinates for requesting tiles.
|
Use32BitMeshIndexBuffers
|
bool
Specifies whether to generate features that have meshes with more than 65536 vertices.
|
ZoomLevel = 17
|
int
The map zoom (magnification) level.
|
Properties |
|
---|---|
CacheOptions
|
A container of parameters used for caching map data.
|
Events
|
A container for all of the events fired by the SDK.
|
GameObjectManager
|
Tracks destroyed and suppressed GameObjects.
|
Projection
|
The game world coordinate system.
|
RoadLattice
|
Global road lattice for this MapsService. Maintains a graph of roads in loaded tiles, stitched across tile boundaries.
|
Version
|
static string
|
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.
|
MobilePause()
|
virtual override void
Handle mobile application being paused.
|
MobileQuit()
|
virtual override void
Handle mobile application quitting.
|
MobileUnpause()
|
virtual override void
Handle mobile application being unpaused.
|
Shutdown()
|
virtual override void
Handle component shutdown.
|
Startup()
|
virtual override void
Handle component startup.
|
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.
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.
FeatureTileApiUrlFormat
string FeatureTileApiUrlFormat = DefaultFeatureTileApiUrlFormat
The format string to be used for constructing HTTP Feature Tile requests. The format items will be replaced with (x, y, z) coordinates for requesting tiles.
Other tile request options will be set via URL parameters (eg: "?key=API_KEY&languageCode=TILE_LANGUAGE_CODE").
If you modify this field after calling Awake, then your change won't take effect.
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.
TerrainTileApiUrlFormat
string TerrainTileApiUrlFormat = DefaultTerrainTileApiUrlFormat
The format string to be used for constructing HTTP Terrain Tile requests. The format items will be replaced with (x, y, z) coordinates for requesting tiles.
Other tile request options will be set via URL parameters (eg: "?key=API_KEY&languageCode=TILE_LANGUAGE_CODE").
If you modify this field after calling Awake, then your change won't take effect.
Use32BitMeshIndexBuffers
bool Use32BitMeshIndexBuffers
Specifies whether to generate features that have meshes with more than 65536 vertices.
This is not supported on all devices. See https://docs.unity3d.com/ScriptReference/Mesh-indexFormat.html for more information.
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.
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.
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.
Projection
Projection Projection
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 (MercatorTileCoords). Note: You must set the floating origin before using the coordinate system.
See also: InitFloatingOrigin
Details | |||
---|---|---|---|
Exceptions |
|
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.
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 |
|
||
Exceptions |
|
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 Projection before calling this method.
Calling this function is equivalent to calling LoadMapRegion().Bounds(bounds).Load(options)
.
See also: InitFloatingOrigin
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Exceptions |
|
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 Projection 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);
MapsService
MapsService()
Constructor.
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 |
|
||||
Exceptions |
|
||||
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 |
|
||||
Exceptions |
|
||||
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 |
|
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.
MobilePause
virtual override void MobilePause()
Handle mobile application being paused.
MobileQuit
virtual override void MobileQuit()
Handle mobile application quitting.
MobileUnpause
virtual override void MobileUnpause()
Handle mobile application being unpaused.
Shutdown
virtual override void Shutdown()
Handle component shutdown.
Startup
virtual override void Startup()
Handle component startup.