SDK Maps for Unity Key Concepts

Le seguenti sezioni contengono descrizioni dei concetti fondamentali per comprendere e utilizzare Maps SDK for Unity.

La classe e il componente di MapsService

La classe MapsService funge da punto di accesso per interagire con Maps SDK for Unity. Incapsula ApiKey ed espone la funzione GameObjectManager, la funzione LoadMap e gli Eventi dalla pipeline GameObject Creation.

Per utilizzare Maps SDK for Unity nel tuo progetto Unity, devi aggiungere il componente di script Map Service a un elemento GameObject vuoto nella scena. Il servizio mappe aggiunge automaticamente GameObjects della mappa generata come elementi secondari di questo anchor GameObject. Con Maps Service (Script) collegato al tuo GameObject base, puoi accedere ai relativi attributi pubblici in Unity Inspector, come mostrato qui.

Servizio Maps (Script)

Elementi geografici come GameObject Unity

Maps SDK for Unity esegue il rendering delle funzionalità geografiche (ad esempio edifici, strade e acqua) del database di Google Maps, ad esempio GameObjects Unity nei giochi. In fase di runtime, sono creati come elementi secondari del GameObject a cui è associato il componente MapsService e hanno nomi nel formato {MapFeatureType}({PlaceID}).

Oggetti di gioco SDK

Creazione di GameObject

Durante il gameplay, l'SDK estrae i dati geografici dal database di Google Maps, sotto forma di riquadri di vettori semantici (tramite l'API Semantic Tile). Decodifica questi dati all'istante, trasformandoli in GameObject Unity. Questo approccio consente di accedere ai dati delle funzionalità della mappa (sia ai metadati sia ai dati geometrici) il prima possibile, in modo da poter personalizzare i GameObjects prima che raggiungino la pipeline.

La prima cosa che fa l'SDK Maps for Unity quando riceve dati vettoriali è la creazione di un oggetto MapFeature al suo interno.

In una fase intermedia della pipeline, MapFeature oggetti sono specializzati. In altre parole, diventano tipi specifici (ad esempio, un Google.Maps.Feature.ModeledStructure). Questi oggetti MapFeature specializzati contengono i dettagli della geometria di MapFeatureShape ( ModeledVolume nel caso di ModeledStructure). Questi dettagli includono sia dati specifici di MapFeature (come vertici e triangoli) e interfacce condivise per accedere ai campi comuni (come i riquadri di delimitazione).

I dati geometrici vengono convertiti in un mesh Unity, aggiunti al GameObject generato tramite MeshFilter e visualizzati con un MeshRenderer.

Accesso alla pipeline

Gli elementi MapFeature ti sono esposti tramite eventi che vengono attivati durante varie fasi della pipeline. Questi includono gli eventi WillCreate, che vengono attivati appena prima della creazione dell'elemento GameObject, per consentirti di specificare le opzioni di stile o persino annullare la creazione, mentre gli eventi DidCreate vengono attivati subito dopo la creazione dell'elemento GameObject, per consentirti di aggiungere o modificare la rete mesh completa.

Ad esempio, potresti esaminare ExtrudedStructures dopo l'accensione di WillCreateExtrudedStructureEvent e nascondere tutti gli edifici di durata inferiore a 20 metri (oppure saltare la creazione del tutto).

Tipi di eventi

Lo spazio dei nomi Google.Maps.Event contiene una classe evento per ogni tipo di elementi geografici.

Ciascuno di questi tipi di eventi ha un oggetto evento membro pubblico WillCreate e DidCreate a cui puoi abbonarti, come mostrato nell'esempio di codice che segue.

dynamicMapsService.MapsService.Events.ExtrudedStructureEvents.DidCreate.AddListener(args => {

    // Apply nine-sliced walls and roof materials to this building.
    buildingTexturer.AssignNineSlicedMaterials(args.GameObject);

    // Add a border around the building base using the Building Border Builder class,
    // coloring it using the given border Material.
    Extruder.AddBuildingBorder(args.GameObject, args.MapFeature.Shape, BuildingAndRoadBorder);
});

WillCreate di eventi

Gli eventi WillCreate vengono attivati immediatamente dopo la creazione di un MapFeature, ma prima che venga generato il GameObject finale. Gli eventi WillCreate ti consentono di sopprimere o personalizzare i GameObject creati da un MapFeature. Gli argomenti evento WillCreate hanno il seguente formato:

using System.ComponentModel;
using Google.Maps.Decoded;
using UnityEngine;

namespace Google.Maps {
  public class WillCreateGameObjectEventArgs<T, U>
      : CancelEventArgs where T : IMapObject, U : IGameObjectStyle {

    public readonly T MapObject;
    public U Style;
    public GameObject Prefab;

    Public WillCreateGameObjectEventArgs(T mapObject, U defaultStyle, GameObject prefab) {
      MapObject = mapObject;
      Style = defaultStyle;
      Prefab = prefab;
    }
  }
}
  • L'impostazione di Cancel (ereditato da CancelEventArgs) su true elimina la creazione di GameObject.
  • MapObject è di sola lettura.
  • L'impostazione di Style consente di personalizzare l'aspetto del gioco GameObject creato.
  • L'impostazione Prefab sostituisce il GameObject che sarebbe stato generato, con il prefabbricato.

DidCreate di eventi

Gli eventi DidCreate vengono attivati dopo la generazione di un oggetto GameObject, dopo che è stato aggiunto alla scena. Ti avvisano quando la creazione del GameObject è riuscita, consentendoti di eseguire ulteriori elaborazioni. DidCreate argomenti evento hanno il seguente formato:

using System.ComponentModel;
using Google.Maps.Decoded;
using UnityEngine;

namespace Google.Maps {
  public class DidCreateGameObjectEventArgs<T, U>
      : EventArgs where T : IMapObject, U : IGameObjectStyle {

    public readonly T MapObject;
    public GameObject CreatedObject;

    Public DidCreateGameObjectEventArgs(T mapObject, GameObject createdObject) {
      MapObject = mapObject;
      CreatedObject = createdObject;
    }
  }
}
  • MapObject è di sola lettura, quindi la sua modifica non causerà alcuna modifica alla scena.
  • Se modifichi CreatedObject verrà modificato il GameObject aggiunto alla scena.

edifici

Esistono due tipi di edifici: edifici estrusi e strutture modellate.

Edifici estrusi

Gli edifici estrusi vengono generati da un contorno (ovvero una traccia 2D) e da un'altezza. L'SDK rappresenta la maggior parte degli edifici in questo modo e li genera nei tre modi seguenti:

  • Utilizzare dati di altezza reali (se disponibili). Questo è il comportamento predefinito.

  • Indicando un'altezza fissa per tutti gli edifici, senza tenere conto dell'altezza reale.

  • Fornendo un'altezza di backup per tutti gli edifici che non hanno un'altezza reale (per impostazione predefinita, questo valore è impostato su 10 metri).

La combinazione di questi tre metodi consente a Maps SDK for Unity di creare paesaggi urbani con varianza realistica che riflettono il mondo reale o con un'altezza costante degli edifici o una combinazione dei due.

Strutture modellate

Le strutture modellate vengono generate utilizzando l'approccio di modellazione 3D standard dei triangoli tessellati. Questo approccio è generalmente utilizzato per edifici storici, come la Statua della Libertà.

Statua della Libertà modellata

Applicazione di materiali

In Unity, il processo di rendering utilizza shader, materiali e texture per aggiungere realismo a GameObjects. Gli Shader definiscono il modo in cui le texture, i colori e l'illuminazione vengono applicati alla geometria visualizzata, con texture, colori e altre impostazioni specifici memorizzati come materiale. Per definire il rendering di una superficie, devi utilizzare i materiali, includendo i riferimenti alle texture utilizzate, alle informazioni sulla rifinitura e ai colori.

Gli Shader sono piccoli script contenenti la logica per il calcolo del colore di ciascun pixel, in base all'input dell'illuminazione e alla configurazione del materiale. Maps SDK for Unity include uno strumento di shadowing standard per le strutture modellate e un altro per le caratteristiche delle mappe base, ma supporta anche l'applicazione avanzata dei materiali. Le coordinate per la mappatura UV sono calcolate per i GameObjects degli elementi della mappa in modo che sia possibile applicare qualsiasi materiale di base e che risulti ragionevole senza modifiche.

Per effetti dei materiali più avanzati, Maps SDK for Unity fornisce dati aggiuntivi per vertice tramite canali UV aggiuntivi, oltre a una serie di funzioni utili per gli Shader CG tramite la libreria GoogleMapsShaderLib. In questo modo, puoi creare texture di edificio nove fette, ovvero tagliare una texture su tetto, terreno, angoli delle pareti e pareti piastrellate di un edificio.

Per ulteriori informazioni, consulta la sezione Creazione e utilizzo dei materiali nel Manuale dell'utente di Unity.

Canali UV

I canali UV per ogni tipo MapFeature contengono dati nel formato seguente:

ExtrudedStructure

Walls

Ogni muro di ExtrudedStructure è costruito come un quadrato del seguente modulo:

Walls

Le coordinate UV per le pareti sono calcolate per quad. I vertici non sono condivisi tra i quadricipiti, per consentire normali rigidi tra le pareti (in altre parole, consentire agli angoli delle pareti di apparire come angoli duri, invece che con bordi arrotondati e morbidi).

Canale 0: (x, y, larghezza, altezza)
x e y sono le coordinate relative all'angolo in basso a sinistra di questo riquadro quadrato (sezione quadrata) del muro, mentre larghezza e altezza sono la larghezza e l'altezza di questo riquadro. Questo vale per tutti i pezzi che compongono il muro.
Tetto

Le texture dei tetti possono essere allineate all'asse o alla direzione di ExtrudedStructure. Puoi impostarlo tramite l'oggetto ExtrudedStructureStyle.

Canale 0: (x, y, larghezza, altezza)
x e y sono le coordinate di ciascun vertice, rispetto all'angolo in basso a sinistra del tetto (in particolare, l'angolo del riquadro di delimitazione allineato all'asse di copertura minima per il tetto). width e height definiscono le dimensioni del riquadro di delimitazione del tetto.

Region

Canale 0: (x, y, larghezza, altezza)
x e y sono le coordinate di ciascun vertice rispetto all'angolo in basso a sinistra del riquadro di delimitazione allineato all'asse per la regione. width e height definiscono le dimensioni del riquadro di delimitazione.

Segment

Canale 0: (x, y, larghezza, lunghezza)
x e y sono le coordinate di ogni vertice, calcolate come se il segmento fosse completamente dritto, per consentire la piegatura delle texture intorno agli angoli. larghezza e lunghezza definiscono le dimensioni del segmento.

ModeledStructure

Canale 0:
Ogni coordinata è impostata su (0, 0, 0, 0) perché al momento non è presente un'implementazione con coordinate di texture.

GoogleMapsShaderLib

Maps SDK for Unity include una libreria di ShaderLib denominata GoogleMapsShaderLib, per aiutarti a creare ombreggiatori che funzionino bene con MapFeature GameObjects. La libreria è implementata nel file GoogleMapsShaderLib.cginc. Puoi utilizzare la libreria includendo la seguente istruzione #include nella sezione dei flag CGPROGRAM nello script delloshar.

CGPROGRAM
// ...
#include "/Assets/GoogleMaps/Materials/GoogleMapsShaderLib.cginc"
// ...
ENDCG

La raccolta Shader è raggruppata nel GoogleMaps.unitypackage. Dopo aver importato il pacchetto, puoi trovare GoogleMapsShaderLib.cginc nella cartella del progetto /Assets/GoogleMaps/Materials/.

A taglio

GoogleMapsShaderLib include una funzione pratica che puoi utilizzare negli shadowing dei frammenti per fornire nove sezioni delle texture. Il nove slicing è una tecnica per coprire le superfici con una texture, in cui la texture viene divisa in nove parti utilizzando una serie di limiti. Le aree tra i margini vengono affiancate, mentre le aree al di fuori dei limiti rimangono fisse, come illustrato qui:

A taglio

Ad esempio, se applichi una texture a nove fette alla parete di un edificio, la parte superiore della texture viene applicata in cima alla parete (appena sotto il tetto), la parte inferiore viene applicata alla parte inferiore della parete (collegata al suolo), i lati della texture vengono applicati ai bordi del muro e l'area al centro della texture viene piastrellata uniformemente sulla parete.

Sulle strade (ad es. un altro esempio), l'uso di nove sezioni consente di avere un marciapiede a larghezza fissa, ma con un numero variabile di corsie, a seconda della larghezza della strada.

Puoi utilizzare nove sezioni includendo GoogleMapsShaderLib.cginc nello shader e chiamando la funzione nineSlice. Shaker e materiali di esempio sono inclusi nel GoogleMaps.unitypackage per dimostrare come puoi utilizzare la funzione nineSlice per creare uno skyscraper realistico di dimensioni variabili, senza allungamenti o strappi.

Posizione dei materiali di esempio
/Assets/GoogleMaps/Examples/04_Advanced/MoreStyling/Materials/NineSlicing
Esempio di posizione Shader
/Assets/GoogleMaps/Examples/04_Advanced/MoreStyling/Materials/NineSlicing/BuildingWall.shader

Puoi utilizzare nove sezioni su qualsiasi MapFeature, ad eccezione di ModeledStructures, che al momento non ha coordinate di texture.

Il sistema di coordinate

Il sistema di coordinate di Maps SDK for Unity utilizza la proiezione di Web Mercator per eseguire la conversione tra latitudine-longitudine WGS 84 sferica e Unity Worldspace cartesiana (Vector3).

I valori di Vector3 sono relativi a un'origine mobile, che in genere è impostata sulla posizione di partenza dell'utente. Di conseguenza, i valori Vector3 non devono essere mantenuti al di fuori di una sessione (ovvero sul tuo server o sul dispositivo dell'utente). Ti consigliamo di specificare le posizioni fisiche del mondo utilizzando coppie latitudine-longitudine.

Per evitare problemi di stabilità in virgola mobile viene utilizzata un'origine mobile. La classe Vector3 di Unity utilizza numeri a virgola mobile a precisione singola e la densità dei numeri in virgola mobile rappresentabili diminuisce all'aumentare della loro grandezza (significa che i numeri a virgola mobile più grandi diventano meno precisi). Puoi aggiornare l'origine mobile ogni volta che gli utenti si allontanano dall'origine a sufficienza da diventare un problema. Puoi impostarlo su un valore relativamente basso (ad esempio 100 o 200 metri) o superiore (maggiore di 1 km) a seconda della frequenza degli aggiornamenti.

Unity Worldspace è scalata a 1:1 (metri), in base alla latitudine dell'origine iniziale. Nella proiezione di Mercator, la scala varia leggermente in base alla latitudine, pertanto la scala dello spazio dei parole di Unity diverge marginalmente da 1:1 quando gli utenti si spostano verso nord e sud; tuttavia, gli utenti non devono muoversi abbastanza lontano (o velocemente) da far sì che questo sia evidente.

L'SDK Maps for Unity contiene funzioni di conversione per la conversione tra Google.Maps.LatLng e Unity Worldspace (Vector3), che tengono conto dell'origine e della scala mobili.

Errori di caricamento

Gli errori che si verificano durante il caricamento dei dati delle mappe dalla rete possono essere gestiti con l'evento MapLoadErrorEvent. Se non aggiungi un gestore di eventi, Maps SDK for Unity gestisce la maggior parte dei tipi di errori. Tuttavia, è presente un errore che richiede l'esecuzione di un'azione da parte dell'app. Questo è specificato da MapLoadErrorArgs.DetailedErrorCode ed è descritto di seguito.

UnsupportedClientVersion

Questa versione di Maps SDK for Unity non è più supportata, probabilmente in combinazione con la chiave API attuale. In genere, l'app dovrebbe richiedere all'utente di eseguire l'aggiornamento a una versione più recente.

Questo errore di solito indica che la versione dell'SDK Maps for Unity è troppo vecchia. In rari casi, potremmo utilizzare questa opzione se rileviamo un problema critico con una versione di Maps SDK for Unity o con una chiave API. Faremo tutto il possibile per comunicare questo aspetto e garantire che ciò non avvenga finché non sarà disponibile una versione funzionante dell'app da aggiornare.

È consigliabile assicurarsi che, nel caso si verifichi questo errore, l'app abbia un percorso di upgrade adeguato, in modo che gli utenti possano eseguire la migrazione a una versione più recente dell'app con una versione dell'SDK supportata. Per ulteriori informazioni, consulta la documentazione relativa all'interruttore di arresto del client.

Problemi noti

Gli elementi della mappa base vengono visualizzati in primo piano senza il test z perché tutti gli elementi di questo tipo vengono visualizzati sullo stesso piano. Devi impostare il test z su ZTest sempre su tutti i materiali sostitutivi che applichi agli elementi della mappa base per assicurarti che vengano visualizzati correttamente.

Google ha incluso uno Shaker di esempio per risolvere questi problemi nel GoogleMaps.unitypackage. È denominato "BaseMapTextured.shader e si trova nella cartella /Assets/GoogleMaps/Materials/. Per utilizzarlo su un materiale, seleziona Google > Mappe > Sfumatori > Mappa base con texture dall'elenco a discesa dello Shader in Controllo materiali.

Quando definisci uno stile a un oggetto Feature.Region o Feature.AreaWater, puoi applicare un riempimento utilizzando un materiale, un colore personalizzato o un colore generato automaticamente scelto tramite l'enum di FillModeType all'interno dell'oggetto di stile. I colori Auto vengono generati in base al valore del tipo di utilizzo della regione.