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
.
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:
- Through iteration over
RoadLattice.Nodes
. - From its position via
RoadLattice.FindNodeAt
. - By retrieving the nearest node to a world position using
RoadLattice.SnapToNode
. - Through its neighboring nodes using
RoadLatticeNode.Neighbors
orRoadLatticeNode.Edges
.
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:
- The source node still exists.
- 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.