Konsep Utama Maps SDK for Unity

Bagian berikut berisi deskripsi konsep yang merupakan kunci untuk memahami dan menggunakan Maps SDK for Unity.

Class dan komponen MapsService

Class MapsService berfungsi sebagai titik entri untuk berinteraksi dengan Maps SDK for Unity. Library ini mengenkapsulasi ApiKey, dan mengekspos GameObjectManager, dan fungsi LoadMap, serta Events dari pipeline GameObject Creation.

Untuk menggunakan Maps SDK for Unity di project Unity, tambahkan komponen skrip Map Service ke GameObject kosong dalam scene. Layanan Peta secara otomatis menambahkan fitur peta yang dihasilkan GameObjects sebagai turunan dari GameObject anchor ini. Dengan Maps Service (Script) yang dilampirkan ke GameObject dasar, Anda dapat mengakses atribut publiknya di Unity Inspector—seperti yang ditunjukkan di sini.

Layanan Maps (Skrip)

Fitur geografis sebagai GameObjects Unity

Maps SDK for Unity merender fitur geografis (seperti bangunan, jalan, dan air) dari database Google Maps, sebagai GameObjects Unity dalam game. Saat runtime, class tersebut dibuat sebagai turunan dari GameObject tempat komponen MapsService dilampirkan, dan memiliki nama dengan format {MapFeatureType} ({PlaceID}).

Objek Game SDK

Pembuatan GameObject

Selama gameplay, SDK mengambil data geografis dari database Google Maps—sebagai kartu vektor semantik (melalui Semantic Tile API). Library ini mendekode data ini dengan cepat, sehingga mengubahnya menjadi Unity GameObjects. Pendekatan ini memungkinkan Anda mengakses data fitur peta (metadata dan data geometri) sesegera mungkin, sehingga Anda dapat menyesuaikan GameObjects sebelum mencapai akhir pipeline.

Hal pertama yang dilakukan Maps SDK for Unity saat menerima data vektor adalah membuat objek MapFeature dari objek tersebut.

Pada tahap perantara dalam pipeline, objek MapFeature dispesialisasi. Artinya, objek tersebut menjadi jenis tertentu (misalnya, Google.Maps.Feature.ModeledStructure). Objek MapFeature khusus ini berisi detail geometri MapFeatureShape (ModeledVolume dalam kasus ModeledStructure). Detail ini mencakup data khusus MapFeature (seperti verteks dan segitiga), dan antarmuka bersama untuk mengakses kolom umum (seperti kotak pembatas).

Data geometri dikonversi menjadi Unity Mesh, dan ditambahkan ke GameObject yang dihasilkan melalui MeshFilter, lalu ditampilkan dengan MeshRenderer.

Mengakses pipeline

MapFeature diekspos kepada Anda melalui peristiwa yang dipicu dalam berbagai tahap pipeline. Hal ini mencakup peristiwa WillCreate—yang diaktifkan tepat sebelum GameObject dibuat, sehingga Anda dapat menentukan opsi gaya, atau bahkan membatalkan pembuatan; dan peristiwa DidCreate—yang diaktifkan tepat setelah GameObject dibuat, sehingga Anda dapat membuat penambahan atau perubahan pada mesh yang sudah selesai.

Sebagai contoh, Anda dapat memeriksa ExtrudedStructures setelah WillCreateExtrudedStructureEvent aktif, dan menyembunyikan semua bangunan dengan panjang kurang dari 20 meter (atau Anda dapat melewati pembuatannya sama sekali).

Jenis peristiwa

Namespace Google.Maps.Event berisi class peristiwa untuk setiap jenis fitur geografis.

Setiap jenis peristiwa ini memiliki objek peristiwa anggota publik WillCreate dan DidCreate yang dapat Anda jadikan langganan, seperti yang ditunjukkan dalam contoh kode berikut.

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 peristiwa

Peristiwa WillCreate diaktifkan segera setelah MapFeature dibuat, tetapi sebelum GameObject akhir dihasilkan darinya. Peristiwa WillCreate memungkinkan Anda menyembunyikan atau menyesuaikan GameObjects yang dibuat dari MapFeature. Argumen peristiwa WillCreate memiliki bentuk berikut:

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;
    }
  }
}
  • Menetapkan Cancel (diwarisi dari CancelEventArgs) ke true akan menghentikan pembuatan GameObject.
  • MapObject bersifat hanya baca.
  • Menyetel Style memungkinkan Anda menyesuaikan tampilan GameObject yang dibuat.
  • Menyetel Prefab akan menggantikan GameObject yang akan dibuat, dengan prefab.

DidCreate peristiwa

Peristiwa DidCreate akan diaktifkan setelah GameObject dibuat, setelah ditambahkan ke scene. Objek ini memberi tahu Anda saat pembuatan GameObject berhasil, sehingga Anda dapat melakukan pemrosesan lebih lanjut. Argumen peristiwa DidCreate memiliki bentuk berikut:

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 bersifat hanya baca, sehingga memutasikannya tidak akan menyebabkan perubahan pada scene.
  • Mengubah CreatedObject akan mengubah GameObject yang ditambahkan ke scene.

Bangunan

Ada dua jenis bangunan: bangunan yang diekstrusi dan struktur sesuai model.

Bangunan yang diekstrusi

Bangunan yang diekstrusi dihasilkan dari garis batas (yaitu, jejak 2D) dan ketinggian. SDK merepresentasikan sebagian besar bangunan dengan cara ini, dan menghasilkannya dengan tiga cara berikut:

  • Menggunakan data ketinggian yang sebenarnya (tempat informasi ini tersedia). Ini adalah perilaku default.

  • Dengan memberikan tinggi tetap untuk semua bangunan, tanpa memperhitungkan tingginya yang sebenarnya.

  • Dengan memberikan tinggi cadangan untuk semua bangunan yang tidak memiliki tinggi sebenarnya (secara default, nilai ini ditetapkan ke 10 meter).

Dengan menggabungkan ketiga metode ini, Maps SDK for Unity dapat membuat lanskap kota dengan varian realistis yang mencerminkan dunia nyata, atau dengan tinggi bangunan yang konstan, atau campuran keduanya.

Struktur sesuai model

Struktur sesuai model dibuat menggunakan pendekatan pemodelan 3D standar untuk segitiga tessellated. Pendekatan ini biasanya digunakan untuk bangunan terkenal, seperti Patung Liberty.

Patung Liberty Model

Menerapkan bahan

Di Unity, proses rendering menggunakan shader, material, dan tekstur, untuk menambahkan realisme ke GameObject. Shader menentukan cara tekstur, warna, dan pencahayaan diterapkan ke geometri yang ditampilkan, dengan tekstur, warna, dan setelan tertentu lainnya yang digunakan disimpan sebagai material. Anda menggunakan material untuk menentukan cara permukaan dirender—dengan menyertakan referensi ke tekstur yang digunakannya, pada informasi pemasangan ubin, dan warna.

Shader adalah skrip kecil yang berisi logika untuk menghitung warna setiap piksel—berdasarkan input pencahayaan dan konfigurasi material. Maps SDK for Unity dilengkapi dengan shader standar untuk struktur sesuai model, dan satu lagi untuk fitur peta dasar, tetapi juga mendukung aplikasi material lanjutan. Koordinat untuk pemetaan UV dihitung untuk fitur peta GameObjects sedemikian rupa sehingga setiap materi dasar dapat diterapkan, dan akan terlihat wajar tanpa modifikasi.

Untuk efek material lanjutan, Maps SDK for Unity menyediakan data tambahan per verteks melalui saluran UV tambahan, serta sejumlah fungsi praktis untuk shader cg melalui library GoogleMapsShaderLib. Dengan begitu, fitur seperti tekstur bangunan Sembilan-Sliced dapat digunakan untuk memotong tekstur ke atap, tanah, sudut dinding, dan dinding ubin, untuk sebuah bangunan.

Untuk mengetahui informasi selengkapnya, lihat Membuat dan Menggunakan Material dalam Panduan Pengguna Unity.

Saluran UV

Saluran UV untuk setiap jenis MapFeature berisi data dengan bentuk berikut:

ExtrudedStructure

Walls

Setiap dinding di ExtrudedStructure dibuat sebagai segi empat dari bentuk berikut:

Walls

Koordinat UV untuk dinding dihitung per segi empat. Verteks tidak dibagikan di antara paha depan—untuk memungkinkan normal keras antar-dinding (yaitu, membiarkan sudut dinding muncul sebagai sudut keras, bukan tepi melengkung yang lembut).

Saluran 0: (x, y, lebar, tinggi)
x dan y adalah koordinat yang relatif terhadap sudut kiri bawah segi empat (bagian persegi) dinding ini, sedangkan lebar dan tinggi adalah lebar dan tinggi segi empat dinding ini. Ini berlaku untuk setiap segi empat yang membentuk dinding.
Atap

Tekstur atap memiliki opsi untuk disejajarkan dengan sumbu atau disejajarkan dengan arah ExtrudedStructure. Anda menetapkannya melalui objek ExtrudedStructureStyle.

Saluran 0: (x, y, lebar, tinggi)
x dan y adalah koordinat setiap verteks, relatif terhadap sudut kiri bawah atap (khususnya, sudut kotak pembatas minimum yang selaras dengan sumbu merata untuk atap). width dan height menentukan ukuran kotak pembatas atap.

Region

Saluran 0: (x, y, lebar, tinggi)
x dan y adalah koordinat setiap verteks yang relatif terhadap sudut kiri bawah kotak pembatas yang selaras dengan sumbu untuk wilayah. lebar dan tinggi menentukan ukuran kotak pembatas.

Segment

Saluran 0: (x, y, lebar, panjang)
x dan y adalah koordinat setiap verteks, yang dihitung seolah-olah segmen benar-benar lurus—agar tekstur dapat melengkung di sekitar sudut. lebar dan panjang menentukan dimensi segmen.

ModeledStructure

Saluran 0:
Setiap koordinat ditetapkan ke (0, 0, 0, 0) karena saat ini tidak ada penerapan koordinat tekstur.

GoogleMapsShaderLib

Maps SDK for Unity menyertakan library shader yang disebut GoogleMapsShaderLib, untuk membantu Anda membuat shader yang berfungsi baik dengan MapFeature GameObjects. Library ini diimplementasikan dalam file GoogleMapsShaderLib.cginc. Anda dapat menggunakan library ini dengan menyertakan perintah #include berikut dalam bagian tanda CGPROGRAM di skrip shader.

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

Library shader dipaketkan di dalam GoogleMaps.unitypackage. Setelah mengimpor paket, Anda dapat menemukan GoogleMapsShaderLib.cginc di dalam folder project /Assets/GoogleMaps/Materials/.

Sembilan irisan

GoogleMapsShaderLib mencakup fungsi praktis yang dapat Anda gunakan dalam shader fragmen untuk menyediakan sembilan irisan tekstur. Sembilan irisan adalah teknik untuk menutupi permukaan dengan tekstur, dengan tekstur dibagi menjadi sembilan bagian menggunakan serangkaian batas. Area di antara batas tersebut dibuat berulang, dan area di luar batas tersebut tetap bersifat tetap—seperti yang diilustrasikan di sini:

Sembilan irisan

Misalnya, saat menerapkan tekstur sembilan irisan ke dinding bangunan, bagian atas tekstur diterapkan ke bagian atas dinding (tepat di bawah atap), bagian bawah tekstur diterapkan ke bagian bawah dinding (terhubung ke tanah), sisi tekstur diterapkan ke tepi dinding, dan area di tengah tekstur dioleskan secara merata di seluruh dinding.

Di jalan (misalnya, sembilan irisan memungkinkan Anda memiliki trotoar dengan lebar tetap, tetapi dengan jumlah jalur yang bervariasi, bergantung pada lebar jalan.

Anda dapat menggunakan nine-slicing dengan menyertakan GoogleMapsShaderLib.cginc dalam shader, lalu memanggil fungsi nineSlice. Contoh shader dan material disertakan dalam GoogleMaps.unitypackage untuk mendemonstrasikan cara menggunakan fungsi nineSlice guna membuat pilar yang realistis dengan ukuran bervariasi, tanpa melebar atau merobeknya.

Contoh lokasi Materi
/Assets/GoogleMaps/Examples/04_Advanced/MoreStyling/Materials/NineSlicing
Contoh lokasi Shader
/Assets/GoogleMaps/Examples/04_Advanced/MoreStyling/Materials/NineSlicing/BuildingWall.shader

Anda dapat menggunakan nine-slicing pada MapFeature apa pun, kecuali untuk ModeledStructures, yang saat ini tidak memiliki koordinat pemberian tekstur.

Sistem koordinat

Sistem koordinat Maps SDK for Unity menggunakan Web Mercator Projection untuk melakukan konversi antara lintang-bujur sferis WGS 84 dan Unity Worldspace kartesius (Vector3).

Nilai Vector3 relatif terhadap asal mengambang, yang biasanya ditetapkan ke lokasi awal pengguna. Akibatnya, Anda tidak boleh mempertahankan nilai Vector3 di luar sesi (yaitu, di server Anda, atau di perangkat pengguna). Sebaiknya Anda menentukan lokasi dunia fisik menggunakan pasangan lintang-bujur.

Origin mengambang digunakan untuk menghindari masalah stabilitas floating point. Class Vector3 Unity menggunakan bilangan floating point presisi tunggal, dan kepadatan bilangan floating point yang dapat ditampilkan akan menurun saat magnitudonya meningkat (artinya angka floating point yang lebih besar menjadi kurang akurat). Anda dapat mengupdate floating origin setiap kali pengguna bergerak cukup jauh dari origin sehingga hal ini menjadi masalah. Anda dapat menetapkannya ke nilai yang relatif kecil (misalnya, 100 atau 200 meter), atau lebih besar (lebih dari 1 km) bergantung pada seberapa sering Anda ingin mengupdate berbagai hal.

Unity Worldspace diskalakan ke 1:1 (meter), berdasarkan lintang tempat asal awal. Dalam Proyeksi Mercator, skala sedikit berbeda menurut garis lintang, sehingga skala Wordspace Unity sedikit berbeda dari 1:1 saat pengguna bergerak ke Utara dan Selatan. Namun, pengguna tidak diharapkan untuk bergerak terlalu jauh (atau cepat) agar perubahan ini terlihat.

Maps SDK for Unity berisi fungsi konversi untuk melakukan konversi antara Google.Maps.LatLng dan Unity Worldspace (Vector3)—yang memperhitungkan asal dan skala float.

Error pemuatan

Error yang terjadi saat memuat data peta dari jaringan dapat ditangani dengan peristiwa MapLoadErrorEvent. Maps SDK for Unity menangani sebagian besar jenis error jika Anda tidak menambahkan pengendali peristiwa. Namun, terjadi error yang mengharuskan aplikasi Anda melakukan beberapa tindakan. Hal ini ditentukan oleh MapLoadErrorArgs.DetailedErrorCode dan dijelaskan di bawah ini.

UnsupportedClientVersion

Versi Maps SDK for Unity ini tidak lagi didukung, mungkin dikombinasikan dengan Kunci API saat ini. Biasanya, aplikasi Anda akan meminta pengguna untuk mengupdate aplikasi ke versi yang lebih baru.

Error ini biasanya berarti bahwa versi Maps SDK for Unity terlalu lama. Dalam kasus yang jarang terjadi, kami mungkin menggunakannya jika menemukan masalah kritis pada versi Maps SDK for Unity atau dengan Kunci API. Kami akan melakukan segala upaya untuk menyampaikan hal ini dan memastikan hal ini tidak terjadi hingga versi aplikasi yang berfungsi tersedia untuk diupdate.

Sebagai praktik terbaik, sebaiknya pastikan aplikasi Anda memiliki jalur upgrade yang sesuai jika error ini terjadi, sehingga pengguna dapat bermigrasi ke versi aplikasi yang lebih baru dengan versi SDK yang didukung. Untuk mengetahui informasi selengkapnya, lihat dokumentasi Client Kill Switch.

Masalah umum

Fitur peta dasar dirender dari belakang ke depan tanpa pengujian z karena semua fitur dari jenis ini dirender di bidang yang sama. Anda harus menetapkan pengujian z ke ZTest Always pada setiap bahan pengganti yang Anda terapkan ke fitur peta dasar untuk memastikan bahwa bahan tersebut dirender dengan benar.

Google telah menyertakan contoh shader yang mengatasi masalah ini—di GoogleMaps.unitypackage. Namanya "BaseMapTextured.shader, dan terletak di folder /Assets/GoogleMaps/Materials/. Untuk menggunakannya pada material, pilih Google > Maps > Shaders > BaseMap Textured dari drop-down shader di material inspector.

Saat menata gaya objek Feature.Region atau Feature.AreaWater, Anda dapat menerapkan isi menggunakan material, warna kustom, atau warna yang dihasilkan secara otomatis yang dipilih melalui enum FillModeType dalam objek gaya visual. Warna Auto dibuat berdasarkan nilai jenis penggunaan Region.