❮ Quality & Performance
Scene Generation and Update Time ❯

Map Data Request Timeout

Note

This page focuses on the technical behavior, timeouts, and graph node stalls when map data requests are delayed or unavailable. For high-level experience design guidelines, trajectory projection strategies, and terrain constraints under map-free conditions, see the Map-Free Generation design guide.

Normally, the Spatial Experience SDK utilizes pre-loaded map data to anticipate turns and generate expansive virtual worlds aligned with real-world geography. However, when an active map data download/connection is unavailable, when there is no internet connection available or the connection is too slow (if the map data does not already reside in the cache), or when running in regions/routes where pre-downloaded map data is not stored, the SDK will continue to operate utilizing real-time vehicle sensor telemetry and geographic positioning (such as speed, acceleration, rotation, and geo location).

For developers, this means the virtual environment must be designed to handle stalled ElasticSceneGenerators (ESG):

  • Generation Overdue: If the player moves too far from what has currently been generated (i.e., beyond the pre-generated boundary before a new update cycle completes), the ESG will fire the OnEnterGenerationOverdue event.
  • Initial/Complete Load Failures: If no map data could ever be fully loaded to cover the ESG supported area, the OnGenerationFinished event will never fire.

In these situations, the system must rely on real-time vehicle sensors to drive interactive virtual environments independent of geographic map layers.

ElasticSceneGenerator Behavior

The following state machine lifecycle diagram illustrates the map data caching, downloading, and event-triggering flow when updating the player's position:

flowchart TD
    Start((Start)) --> StartESG["Start ElasticSceneGenerator"]
    StartESG --> UpdateGPS["Update GPS Position"]

    UpdateGPS --> StartGen["OnGenerationStarted / OnUpdateStarted"]
    StartGen --> DetermineMap["Determine required map tiles to cover ESG area"]
    DetermineMap --> InCache{"All required tiles in cache?"}

    InCache -->|No| Download["Downloading missing map tiles<br><i>(Graph nodes stall: RoadNetworkMask, RoadNetworkPoses, OSM nodes)</i>"]
    Download --> Result{"Result?"}
    
    Result -->|Success| InCache
    Result -->|Timeout| UpdateGPSTimeout["Update GPS Position"]
    UpdateGPSTimeout --> DetermineMap

    InCache -->|Yes| UpdateTerrain["Terrain gets updated"]
    InCache -->|No map tiles required| UpdateTerrain
    UpdateTerrain --> FinishGen["OnGenerationFinished / OnUpdateFinished"]
    FinishGen --> UpdateGPS

In this scenario, there is no explicit "No Map Data" mode. Instead, the check "All required tiles in cache?" will immediately resolve to "No map tiles required" (directly updating the terrain) if none of the map-dependent nodes are used. However, if any nodes in the Elastic Graph that require map data are present and cannot load their respective files, they will simply stall (i.e., stop processing or producing updates). This includes:

  • RoadNetworkMask (retrieves and rasterizes road geometries into binary masks)
  • RoadNetworkPoses (generates structured spawn poses along road paths)
  • All OSM nodes (OpenStreetMap nodes) that rely on external Overpass map queries:
    • OSMPoses (resolves geographic nodes or way centers into spawn poses)
    • OSMSpawner (places prefabs directly at positions resolved from Overpass queries)
    • OSMBuildingSpawner (procedurally places building models based on structural footprint queries)
    • OSMGeometryRasterizer (rasterizes polygonal area footprints, such as forests or parks, into map masks)
    • OSMVoronoi (generates Voronoi cells to subdivide terrain based on queried geographic coordinates)
❮ Quality & Performance
Scene Generation and Update Time ❯