Maps SDK for Unity Example Scenes

The Maps SDK for Unity ships with a collection of example Unity scenes, and each one demonstrates a fundamental feature of the SDK. They're installed when you install the SDK, into the /GoogleMaps/Examples/ directory.

To run an example scene in Unity

  1. Integrate the Maps SDK for Unity by following the Getting Started procedure. When you're done, you'll have downloaded the SDK, and integrated it into Unity.

  2. In the Project pane, navigate to the /Assets/GoogleMaps/Examples/ folder. The example scenes are organized in the following folder structure:

    Folder Main scene Description
    01_GettingStarted HelloWorld Illustrates the simplest way to load a map.
    02_MapsService MapsService101 Details how to use the Maps Service to communicate with the SDK.
    03_MapsStyling StylingMaps101 Provides a comprehensive example of styling map features at run-time.
    04_Advanced Multiple scenes Regroups several examples that illustrate advanced topics such as benchmarking, edit time (styling) preview, mixed zoom, playable locations, pathfinding, and advanced styling.
  3. Double-click the example scene that you want to run. The scene appears in the Hierarchy pane.

  4. Before you can run the scene, you must add the apiKey to allow the SDK to communicate successfully with Google servers. The apiKey is a parameter of the MapsService Unity component, which is usually attached to the example game object or one of its children.

  5. Click the Run button.

Getting Started

This example scene demonstrates the most rudimentary aspects of the Maps SDK for Unity. By default, it loads the coordinates for the Statue of Liberty, and then displays the Statue of Liberty GameObject and surrounding geometry, in both the Scene and Editor panes.

If you stop the scene, you can then enter a new set of coordinates into the Latitude and Longitude fields (inside the Basic Example (Script) component in the Inspector), and then re-run the scene—and a different world-scene will display.

The code that enables communication with the Maps SDK for Unity is located in the Start() function of the script:

private void Start () {
   // Get required Maps Service component on this GameObject.
   MapsService mapsService = GetComponent<MapsService>();

   // Set real-world location to load.
   mapsService.InitFloatingOrigin(LatLng);

   // Register a listener to be notified when the map is loaded.
   mapsService.Events.MapEvents.Loaded.AddListener(OnLoaded);

   // Load map with default options.
   mapsService.LoadMap(ExampleDefaults.DefaultBounds,ExampleDefaults.DefaultGameObjectOptions);
}

In this example, the map is loaded with default bounds and styles instructions. The MapsService component is the gateway to communicate with the Maps SDK for Unity. Note that the latitude-longitude pair in the example initializes the floating origin of the map. The bounds parameter defines the loaded area around that origin.

MapsService 101

This example scene demonstrates how to use the MapsService component to interact with the Maps SDK for Unity in a variety of ways.

The scene puts into action several specialized components that you can use in your own Unity scenes. These components are assigned to the MapsExample gameobject in the scene hierarchy. They showcase the map-loading lifecycle. This example uses a first person perspective.

Component Description
BaseMapLoader Loads a map with the provided Lat Lng as the origin, and within a radius of MaxDistance. The BaseMapLoader component demonstrates how to handle loading errors encountered by the SDK.
DynamicMapsUpdater Dynamically loads or unloads more sections of the map as the user (in this case the main camera) moves around the world. The DynamicMapsUpdater component keeps the Camera.main viewport loaded at all times, unloading everything outside the viewport.
FloatingLatLngOriginUpdater Moves the floating origin and updates the relative position of all loaded map features when the user (in this case the main camera) reaches a FloatingOriginRange distance from the initial position.

The FloatingLatLngOriginUpdater component demonstrates how to use the MapsService.MoveFloatingOrigin method to re-center the gameworld. This becomes necessary because of floating-point rounding errors, which cause map features to be increasingly misplaced the further gameplay moves away from the game origin. For more information, see Floating Origin.
RoadNamesUpdater When the RoadNamesUpdater component is active, the loaded map displays road names as labels.
BuildingNamesUpdater When the BuildingNamesUpdater component is active, the loaded map displays building names as labels.
ProgressBarUpdater When the ProgressBarUpdater component is active, the HUD displays the current loading progress.
SearchByPlaceIdUpdater When the SearchByPlaceIdUpdater component is active, it keeps track of loaded placeIds and provides a way to search for a gameobject identified by a selected placeId on the loaded map.
MapFeaturesController When the MapFeaturesController component is active, it provides a way to dispatch the loaded map geometry into several predefined buckets (different gameobject parenting). It also provides ways to instruct the MapsService about the MapFeatures categories that should be loaded.

By default, this example loads the coordinates for Midtown Manhattan, New York, USA. If you stop the scene, you can then enter a new set of coordinates into the Latitude and Longitude fields of the Dynamic Maps Service Script component in the Inspector. Re-run the scene and a different world scene displays.

Maps Styling 101

This example scene demonstrates how to use the Maps SDK for Unity to style map features as they are created during the loading process.

There are three approaches for styling a map at runtime:

  1. Provide a styles configuration (GameObjectOptions) to the MapsService component when loading a map.
  2. Use WillCreate events to attach custom style instructions for a specific map GameObject before it is instantiated by the SDK.
  3. Style GameObjects at run-time after they’ve been created, either in a DidCreate event or after the MapLoaded event is received.

The Maps Styling 101 example illustrates the first two approaches.

The code processing each set of parameters is available in the following classes, located under /Assets/GoogleMaps/Examples/03_MapsStyling/Scripts:

AreaWaterConfigView
ExtrudedStructureConfigView
ModeledStructureConfigView
RegionConfigView
SegmentConfigView

The code collecting all map features styles and passing them to the MapsService API is located in the MapsStylingEditorView class.

Maps Pathfinding 101

This example scene demonstrates how to use the built-in pathfinding functionality in the SDK. This service relies on an A* algorithm and the road lattice of the loaded map as the traversable graph.

The example shows two characters on screen. One is driven by the player and the second is managed by artificial intelligence.

When activated, the evil bot (in red) tries to catch up with our avatar (in green). All paths are updated in real-time.

The example highlights the graph of road lattice nodes (or waypoints) available on the loaded map.

Note that these nodes do not have a visual representation. The white spheres displayed on the map are for illustrative purposes.

This example intentionally hides all map features but road segments.

The code handling the main character is located in the RoadLatticeCharacterController component, while the code handling the search behaviour of the AI Agent can be found in RoadLatticeAIController.

Advanced Topics

The following examples demostrate advanced features of creating Unity scenes.

Benchmarking

The benchmark runner example scene under /Assets/GoogleMaps/Examples/05_Advanced/Benchmarking/Scenes provides benchmarking results on LoadTime, Sustained FPS, Mixed Zoom FPS, and Pixel Counting.

Edit time preview

The edit time preview example scene under /Assets/GoogleMaps/Examples/05_Advanced/EditTimePreview gives a first glance at a new implementation that allows the styling of maps gameobjects in the editor at edit time, as opposed to the run-time styling described in the Maps Styling 101 section.

Mixed zooms

The mixed zoom example scene under /Assets/GoogleMaps/Examples/05_Advanced/MixedZoom illustrates how to use different zoom levels while loading a map, based on the location of the main camera and the distance to the map. This feature provides a way to handle different levels of details.

Day and night

The day and night example scene under /Assets/GoogleMaps/Examples/05_Advanced/Miscellaneous demonstrates how to create a day-night cycle using Unity's skybox system, directional lighting, and emissive materials.

This example is almost identical to the nine-slicing example. The only difference is that this example adds a SunAndMoonController and an EmissionController to control the lighting and emission-colors of materials to simulate a day-night cycle. The underlying logic of applying materials to buildings is the same as in the nine-slicing example.

This example also uses the DynamicMapsService component, the BuildingTexturer component, and the ErrorHandling component.

Buildings over roads

The buildings over roads example scene under /Assets/GoogleMaps/Examples/05_Advanced/Miscellaneous demonstrates how to automatically remove buildings from on top of roads (including rails and ferry lanes).

This example uses the DynamicMapsService to allow navigation around the world, with the MapsService keeping only the viewed part of the world loaded at all times. It also uses a BuildingTexturer to apply nine-sliced materials, and it uses the ErrorHandling component to display any errors encountered by the MapsService component when loading geometry.

Minimap

The minimap example scene under /Assets/GoogleMaps/Examples/05_Advanced/Miscellaneous demonstrates how to set up a Camera's render setting to display a minimap view of the gameworld in a UI element. This scene uses a gameObject.layer and a Camera.cullingMask to control what's displayed in the minimap. This scene also uses a RenderTexture to connect to a UI.RawImage UI component for displaying as an on-screen minimap.

Location follower

The location follower example scene under /Assets/GoogleMaps/Examples/05_Advanced/Miscellaneous demonstrates how to use the player's real-world GPS coordinates to update their gameworld position.

Admin area coloring

The admin area coloring example scene under /Assets/GoogleMaps/Examples/05_Advanced/Miscellaneous demonstrates how to display an outline around administrative areas. This is currently only supported in Japan.

More Styling Examples

The following specific styling examples are located under /Assets/GoogleMaps/Examples/05_Advanced/MoreStyling.

Nine-slicing

The nine-slicing example scene demonstrates how to texture buildings using nine-sliced materials. These materials rely on a custom shader BuildingWall Wall (9 Slice) located under /Assets/GoogleMaps/Examples/05_Advanced/MoreStyling/Materials/NineSlicing.

It uses the BuildingTexturer component to apply nine-sliced materials, and it uses the DynamicMapsService component to allow navigation around the world, with the MapsService component keeping only the viewed part of the world loaded at all times.

This example also uses the ErrorHandling component to display any errors encountered by the MapsService component when loading world geometry.

Building borders

The building borders example scene demonstrates how to add borders around the bases of buildings.

This example is almost identical to the nine-slicing example. The only difference is that this example uses the Extruder class to add modelled borders to the bases of buildings.

This example also uses the DynamicMapsService component, the BuildingTexturer component, and the ErrorHandling component.

Parapets

The parapets example scene demonstrates how to add parapets to the top edge of buildings.

This example is almost identical to the nine-slicing example. The only difference is that this example uses an Extruder to add modelled parapets around building roofs. It also uses the DynamicMapsService component, the BuildingTexturer component, and the ErrorHandling component.

By default, this example loads the coordinates for Melbourne, Australia.

Building squashing

The building squashing example scene demonstrates how to squash buildings (that is, reduce the height of extruded buildings to zero) when they are close to the player. This example uses the ErrorHandling component to display any errors encountered by the MapsService component when loading geometry.

Prefab replacement

The prefab replacement example scene demonstrates how to use a defined prefab to replace buildings of given types, or to replace buildings suppressed by the SDK because they have a vertex count that exceeds Unity's maximum supported vertex count (65,000 vertices per mesh).

When this scene opens, it focuses on Westminster Abbey (London), which appears replaced by a prefab because this particular model is too detailed for Unity to handle (and is therefore suppressed).

This example uses the ErrorHandling component to display any errors encountered by the MapsService component when loading geometry.