Konsep Kunci 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. File ini mengenkapsulasi ApiKey, dan mengekspos GameObjectManager, 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 di scene. Layanan Peta secara otomatis menambahkan fitur peta yang dihasilkan GameObjects sebagai turunan dari GameObject anchor ini. Dengan Maps Service (Script) yang terpasang ke GameObject dasar, Anda dapat mengakses atribut publiknya di Unity Inspector—seperti yang ditunjukkan di sini.

Layanan Maps (Skrip)

Fitur geografis sebagai Unity GameObjects

Maps SDK for Unity merender fitur geografis (seperti bangunan, jalan, dan air) dari database Google Maps, sebagai Unity GameObjects dalam game. Saat runtime, objek ini dibuat sebagai turunan dari GameObject tempat komponen MapsService dilampirkan, dan memiliki nama formulir {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, mengubahnya menjadi Unity GameObjects. Pendekatan ini memungkinkan Anda mengakses data fitur peta (baik metadata maupun data geometri) pada kesempatan paling awal, 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 data tersebut.

Pada tahap menengah dalam pipeline, objek MapFeature dispesialisasi. Artinya, objek 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 melalui peristiwa yang dipicu selama berbagai tahap pipeline. Hal ini mencakup peristiwa WillCreate—yang diaktifkan tepat sebelum GameObject dibuat, memungkinkan Anda menentukan opsi gaya, atau bahkan membatalkan pembuatan; dan peristiwa DidCreate—diaktifkan tepat setelah GameObject dibuat, sehingga Anda dapat membuat penambahan atau perubahan pada mesh yang sudah selesai.

Misalnya, Anda dapat memeriksa ExtrudedStructures setelah WillCreateExtrudedStructureEvent terpicu, dan menyembunyikan semua bangunan yang kurang dari 20 meter (atau Anda dapat melewati pembuatannya sama sekali).

Jenis peristiwa

Ruang nama 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 pilih untuk berlangganan, 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);
});

Peristiwa WillCreate

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 menyembunyikan pembuatan GameObject.
  • MapObject bersifat hanya baca.
  • Dengan menetapkan Style, Anda dapat menyesuaikan tampilan GameObject yang dibuat.
  • Menetapkan Prefab akan menggantikan GameObject yang akan dibuat, dengan prefab.

Peristiwa DidCreate

Peristiwa DidCreate diaktifkan setelah GameObject dibuat, setelah ditambahkan ke scene. Kode 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 mengubah scene 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 dunia nyata (tempat informasi ini tersedia). Ini adalah perilaku default.

  • Dengan memberikan tinggi tetap untuk semua bangunan, mengabaikan tingginya 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 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 materi

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

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

Untuk efek material yang lebih canggih, 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, elemen seperti tekstur bangunan Nine-Sliced dapat memotong tekstur ke atap, tanah, sudut dinding, dan dinding ubin untuk bangunan.

Untuk 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 pada ExtrudedStructure dibuat sebagai segi empat dari bentuk berikut:

Walls

Koordinat UV untuk dinding dihitung per quad. Verteks tidak dibagi di antara kuadrat—untuk memungkinkan normal keras antar-dinding (yaitu, memungkinkan sudut dinding muncul sebagai sudut keras, bukan tepi melengkung yang lembut).

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

Tekstur atap memiliki opsi untuk diratakan terhadap 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 yang diselaraskan dengan sumbu minimum 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 memungkinkan tekstur membengkokkan sudut. lebar dan panjang menentukan dimensi segmen.

ModeledStructure

Saluran 0:
Setiap koordinat disetel 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 diterapkan dalam file GoogleMapsShaderLib.cginc. Anda dapat menggunakan library ini dengan menyertakan perintah #include berikut di dalam bagian tanda CGPROGRAM dalam 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 menyertakan 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 tersebut dibagi menjadi sembilan bagian menggunakan serangkaian batas. Area di antara batas tersebut diberi kotak, 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 diaplikasikan 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 diratakan secara merata di seluruh dinding.

Di jalan (untuk contoh lain), lapisan sembilan 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 menunjukkan cara menggunakan fungsi nineSlice guna membuat pilar ukuran berbeda yang realistis tanpa meregangkan atau melepas.

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 tekstur.

Sistem koordinat

Sistem koordinat Maps SDK for Unity menggunakan Proyeksi Web Mercator untuk melakukan konversi antara garis lintang-bujur WGS 84 sferis 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 tentukan lokasi dunia fisik menggunakan pasangan garis lintang dan bujur.

Origin floating 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 berkurang saat magnitudonya meningkat (artinya angka floating point yang lebih besar menjadi kurang akurat). Anda dapat mengupdate origin floating 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 sesuatu.

Unity Worldspace diskalakan ke 1:1 (meter), berdasarkan lintang tempat asal awal. Dalam Proyeksi Mercator, skala sedikit berbeda berdasarkan lintang, sehingga skala Unity Wordspace sedikit menyimpang dari 1:1 saat pengguna bergerak ke Utara dan Selatan. Namun, pengguna diperkirakan tidak akan cukup bergerak jauh (atau cepat) agar hal ini terlihat jelas.

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

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 itu sendiri jika Anda tidak menambahkan pengendali peristiwa. Namun, ada 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 bersamaan dengan Kunci API saat ini. Biasanya, aplikasi harus 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 menggunakan ini jika menemukan masalah kritis pada versi Maps SDK for Unity atau dengan Kunci API. Kami akan berupaya sebaik mungkin untuk menyampaikan hal ini dan memastikan bahwa hal ini tidak akan terjadi sampai ada versi aplikasi yang berfungsi yang tersedia untuk diupdate.

Praktik terbaiknya adalah memastikan aplikasi Anda memiliki jalur upgrade yang sesuai jika error ini terjadi, yang memungkinkan pengguna bermigrasi ke versi aplikasi yang lebih baru dengan versi SDK yang didukung. Untuk 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 materi tersebut dirender dengan benar.

Google telah menyertakan shader contoh 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 Tekstur dari drop-down shader di pemeriksa material.

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.