Road Lattice

The road lattice represents the road network of the loaded map region as a directed graph. It is an optional feature that can be enabled in a MapsService by selecting Map Feature Options > Road Lattice > Enable Road Lattice in the inspector. It can then be accessed via MapsService.RoadLattice.

A visualization of the road lattice.

The following example scenes exist under GoogleMaps/Examples/04_Advanced and demonstrate various ways of using the road lattice:

  • Intersections/Traffic: Traffic simulation using road intersections.
  • RoadLattice/AttributedRoadLattice: Road lattice visualization.
  • RoadLattice/Pathfinding101: Basic pathfinding.

Fundamentals

Road lattice

The RoadLattice class encapsulates all nodes in the road lattice. It is updated whenever map regions are loaded or unloaded. The DidModifyRoadLatticeEvent event is fired to notify you when these updates occur.

Only one RoadLattice exists per MapsService.

Nodes

Each node in the road lattice is represented by a RoadLatticeNode. Whenever a map region is loaded, nodes corresponding to the vertices of the polylines of each Segment map feature (e.g. roads) are inserted into the road lattice. A node may be shared by multiple segments, such as at road intersections.

Edges

Nodes are connected to other nodes by edges, each of which is represented by a RoadLatticeEdge. You can access a node's edge set using RoadLatticeNode.Edges, or alternatively access its neighbors directly using RoadLatticeNode.Neighbors.

Edges contain metadata that is useful for pathfinding. For example, you can get the Segment the edge lies on through RoadLatticeEdge.Segment and retrieve the type of segment the edge lies on (e.g. highways, footpaths, etc.) using Segment.SegmentMetadata.Usage.

Working with the road lattice

Retrieving nodes

There are four ways to retrieve a node from the road lattice:

Referencing nodes and edges

The road lattice is modified whenever map regions are loaded or unloaded. This means that any RoadLatticeNode or RoadLatticeEdge references you hold may no longer exist in the road lattice. A simple way to resolve this is to add a listener to the MapsService.RoadLatticeEvents.DidModify event and update any references when triggered.

If you need to hold any RoadLatticeNode or RoadLatticeEdge references that are expensive to update (such as those found using pathfinding), you can instead check that they still exist in the road lattice before using it. If they don't exist, you'll know that the references need to be updated.

To check if a RoadLatticeNode still exists, verify that RoadLattice.FindNodeAt(MyNode.LocationUID) returns MyNode. For a RoadLatticeEdge, you'll need to keep a reference to the source node and check that:

  1. The source node still exists.
  2. The source node has the same edge to the destination node (use RoadLatticeNode.EdgeTo).

Pathfinding

Unity provides systems that facilitate path-finding in your game world. For example, the NavMesh system allows you to create agents that can find their way between points in your game world.

The Client-side Road Network Pathfinding system in the Maps SDK for Unity is designed to provide similar facilities on the road network of the dynamically loaded map. It provides methods for calculating the shortest path between two intersections in the road network of the loaded map region (the RoadLattice).

Calculating paths

You can use RoadLattice.FindPath and RoadLattice.UncheckedFindPath to calculate paths between nodes. Learn more about retrieving nodes.

As paths are returned as a collection of nodes, keep in mind the best practices when holding references to nodes so that you know when they need to be re-calculated.

Example usage scenario

In a hypothetical game in which players play the part of a celebrity trying to avoid paparazzi, you could use the Client-side Road Network Pathfinding system to periodically update the shortest road path between each paparazzo and the current player location.

Client-side pathfinding doesn't provide the degree of accuracy required for driving navigation in the real world. It provides an approximation that's good enough for routing dynamic game agents. For example, client-side pathfinding doesn't respect real-world properties, such as one-way streets.