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.
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}).
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.
- Eventi dei segmenti
- Eventi Regioni
- Eventi acquatici lineari
- Eventi acquatici locali
- Eventi strutture estruse
- Eventi per strutture modellate
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 daCancelEventArgs
) 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à.
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:
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:
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.