Maps SDK for Unity 範例情境

Maps SDK for Unity 隨附一系列 Unity 場景範例,每個都展示了 SDK 的基本功能。安裝 SDK 時會安裝到 /GoogleMaps/Examples/ 目錄中。

如何在 Unity 中執行範例場景

  1. 按照開始使用程序整合 Maps SDK for Unity。完成後,即可下載 SDK 並整合到 Unity 中。

  2. 在「Project」窗格中,前往 /Assets/GoogleMaps/Examples/ 資料夾。範例場景的編排方式如下:

    資料夾 主要場景 說明
    01_已開始 HelloWorld 說明載入地圖最簡單的方式。
    02_基礎知識 MapsService101 詳細說明如何使用地圖服務與 SDK 通訊。
    03_地圖樣式 StylingMaps101 完整範例提供完整的範例,說明如何在執行階段設定地圖項目樣式。
    04_進階 多個場景 將用來說明進階主題的多個範例重新分組,例如編輯時間 (樣式) 預覽、混合縮放、可播放的位置、路徑尋找和進階樣式。
  3. 在要執行的範例場景上按兩下。場景會顯示在「Hierarchy」(階層) 窗格中。

  4. 開始執行場景之前,必須新增 apiKey,讓 SDK 成功與 Google 伺服器通訊。apiKey 是 MapsService Unity 元件的參數,通常可附加至範例遊戲物件或其中一個子項。

  5. 按一下 [Run] (執行) 按鈕。

入門課程

此範例場景展示了 Maps SDK for Unity 最基本的部分。根據預設,它會載入利比爾雕像的座標,然後在「Scene」和「Editor」窗格中顯示 Liberty GameObject 的座標,以及周圍的幾何圖形。

如果停止場景,您可以在「Latitude」和「Longitude」欄位中輸入一組新的座標 (位於「Inspector」的「Basic Example (Script)」元件內),然後重新執行場景,接著則會顯示其他世界場景。

支援與 Maps SDK for Unity 通訊的程式碼,位於指令碼的 Start() 函式中:

private void Start () {
   // Get required Maps Service component on this GameObject.
   MapsService mapsService = GetComponent<MapsService>();

   // Set real-world location to load.
   mapsService.InitFloatingOrigin(LatLng);

   // Register a listener to be notified when the map is loaded.
   mapsService.Events.MapEvents.Loaded.AddListener(OnLoaded);

   // Load map with default options.
   mapsService.LoadMap(ExampleDefaults.DefaultBounds,ExampleDefaults.DefaultGameObjectOptions);
}

在本例中,地圖是以預設邊界和樣式指示載入。MapsService 元件是與 Maps SDK for Unity 通訊的閘道。請注意,範例中的經緯度組合會初始化地圖的浮動起點。bounds 參數會定義該起點周圍的載入區域。

MapsService 基本概念

這個場景範例說明如何使用 MapsService 元件,以各種方式與 Maps SDK for Unity 互動。

這個場景會分成幾個動作,您可以在自己的 Unity 場景中使用這些特殊元件。這些元件會指派給場景階層中的 MapsExample 遊戲物件。展示地圖載入的生命週期。此範例使用第一人稱視角。

元件 說明
BaseMapLoader 以提供的 Lat Lng 作為起點,且在 MaxDistance 半徑範圍內載入地圖。BaseMapLoader 元件示範如何處理 SDK 發生的載入錯誤。
DynamicMapsUpdater 隨著使用者 (在本例中為主要相機) 移動世界,動態載入或卸載更多地圖區域。DynamicMapsUpdater 元件會持續載入 Camera.main 可視區域,並卸載可視區域以外的所有內容。
FloatingLatLngOriginUpdater 當使用者 (在本例中為主相機) 達到與初始位置的 FloatingOriginRange 距離時,移動浮動起點,並更新所有載入的地圖項目的相對位置。

FloatingLatLngOriginUpdater 元件示範如何使用 MapsService.MoveFloatingOrigin 方法將遊戲世界重新置中。由於浮點捨入錯誤,造成地圖項目的位置變得越來越錯,從遊戲來源開始的位置就越來越不重要,因此必須採用這種做法。詳情請參閱「浮動來源」。
RoadNamesUpdater 如果 RoadNamesUpdater 元件啟用,載入的地圖就會顯示道路名稱做為標籤。
BuildingNamesUpdater BuildingNamesUpdater 元件啟用後,載入的地圖就會顯示建築物名稱做為標籤。
ProgressBarUpdater 啟用 ProgressBarUpdater 元件時,HUD 會顯示目前的載入進度。
SearchByPlaceIdUpdater 啟用 SearchByPlaceIdUpdater 元件時,會追蹤已載入的 placeIds,並可在載入的地圖上搜尋由特定 placeId 識別的遊戲物件。
MapFeaturesController 當 MapFeaturesController 元件啟用時,可提供方法,將已載入的地圖幾何圖形分派到數個預先定義的值區 (不同的遊戲物件父項)。也可藉此指示 MapsService 有關應載入的 MapFeatures 類別。

這個範例預設會載入美國紐約州曼哈頓中城的座標。如果停止場景,可前往「Inspector」中「Dynamic Maps Service Script」元件的「Latitude」和「Longitude」欄位。重新執行場景和不同世界場景的螢幕。

地圖樣式指南

這個場景範例說明如何使用 Maps SDK for Unity 為在載入程序中建立的地圖項目設定樣式。

在執行階段設定地圖樣式有三種方法:

  1. 在載入地圖時,為 MapsService 元件提供樣式設定 (GameObjectOptions)。
  2. 在 SDK 進行例項化之前,請使用 WillCreate 事件附加特定地圖 GameObject 的自訂樣式操作說明。
  3. 建立 GameObjects 後,請在執行階段設定樣式,可以是在 haveCreate 事件中,或收到 MapLoaded 事件之後。

地圖樣式設定 101 範例說明前兩種做法。

位於 /Assets/GoogleMaps/Examples/03_MapsStyling/Scripts 的下列類別提供處理每組參數的程式碼:

AreaWaterConfigView
ExtrudedStructureConfigView
ModeledStructureConfigView
RegionConfigView
SegmentConfigView

收集所有地圖項目樣式並傳送至 MapsService API 的程式碼位於 MapsStylingEditorView 類別。

地圖路徑尋找指南

這個場景範例說明如何使用 SDK 中的內建路徑尋找功能。這項服務仰賴 A* 演算法和載入地圖的道路緯度做為可週遊圖表。

此範例顯示了兩個字元。一個是由玩家推動,第二項則是由人工智慧管理

啟用後,邪惡的機器人 (紅色) 會嘗試跟上我們的顯示圖片 (綠色)。所有路徑都會即時更新。

本範例醒目顯示可載入地圖上可用的道路定點節點 (或路線控點) 圖表。

請注意,這些節點不會顯示視覺呈現。地圖顯示的白色長條僅供參考,

本例刻意隱藏道路部分以外的所有地圖項目。

處理主要字元的程式碼位於 RoadLatticeCharacterController 元件中,處理 AI Agent 搜尋行為的程式碼則位於 RoadLatticeAIController

進階主題

以下範例將展示建立 Unity 場景的進階功能。

編輯時間預覽畫面

/Assets/GoogleMaps/Examples/04_Advanced/EditTimePreview 下方的編輯時間預覽範例場景,可在編輯期間,使用編輯器於編輯器中設定地圖遊戲物件的樣式 (相對於地圖樣式 101 章節中所述的執行時間樣式),首先概略介紹。

混合縮放

/Assets/GoogleMaps/Examples/04_Advanced/MixedZoom 底下的混合縮放範例情境說明如何根據主要相機位置和地圖的距離,在載入地圖時使用不同的縮放等級。這項功能可用來處理不同層級的細節。

白天和夜晚

/Assets/GoogleMaps/Examples/04_Advanced/Miscellaneous 底下的日間和夜間範例場景示範如何使用 Unity 的 Skybox 系統、方向光源和發射材質建立日夜循環。

本例幾乎與九個切片範例相同。唯一的差別在於此範例新增了 SunAndMoonControllerEmissionController 來控製材質的光線和排放顏色,以模擬一整天的循環。將材質套用至建築物的基礎邏輯與 9 切割範例相同。

此範例也使用 DynamicMapsService 元件、BuildingTexturer 元件和 ErrorHandling 元件。

迷你地圖

/Assets/GoogleMaps/Examples/04_Advanced/Miscellaneous 下方的小圖範例情境說明如何設定相機的轉譯設定,在 UI 元素中顯示遊戲世界的小地圖檢視畫面。此場景使用 gameObject.layerCamera.cullingMask 來控制小導覽圖中顯示的內容。此場景也會使用 RenderTexture 連結至 UI.RawImage UI 元件,以便顯示為畫面上的小地圖。

位置追蹤者

/Assets/GoogleMaps/Examples/04_Advanced/Miscellaneous 下方的位置跟蹤範例場景示範如何使用玩家的實際 GPS 座標來更新遊戲世界位置。

更多樣式範例

以下具體樣式範例位於 /Assets/GoogleMaps/Examples/04_Advanced/MoreStyling 下方。

9 切割

此場景提供九個切片範例,示範如何使用九個切片材質來建構紋理。這些素材依賴 /Assets/GoogleMaps/Examples/04_Advanced/MoreStyling/Materials/NineSlicing 下方的自訂著色器 BuildingWall 牆 (9 Slice)。

這個程式庫使用 BuildingTexturer 元件套用九個切片材質,也會使用 DynamicMapsService 元件允許環遊世界,而 MapsService 元件則能隨時只載入世界上可見部分,

此範例也會使用 ErrorHandling 元件,顯示載入世界幾何圖形時發生的任何 MapsService 元件錯誤。

建築物邊界

建築物邊界範例場景示範如何在建築物底部加上邊框。

本例幾乎與九個切片範例相同。唯一的差別在於,這個範例使用 Extruder 類別,在建築物基底新增模型式框線。

此範例也使用 DynamicMapsService 元件、BuildingTexturer 元件和 ErrorHandling 元件。

護欄

參數場景範例說明如何在建築物頂端邊緣加入假衣

本例幾乎與九個切片範例相同。唯一的差別在於,這個範例使用 Extruder 在建築物屋頂周圍新增模擬地毯。它也會使用 DynamicMapsService 元件、BuildingTexturer 元件和 ErrorHandling 元件。

根據預設,這個範例會載入澳洲墨爾本的座標。

建築壓縮

建築物壓縮範例場景說明如何在靠近玩家的位置將建築物壓縮為零 (也就是將誇張建築物的高度降到零)。此範例使用 ErrorHandling 元件,顯示載入幾何圖形時 MapsService 元件發生的任何錯誤。

Prefab 替換

Prefab 替換範例場景說明如何使用定義的 Prefab 取代指定類型的建築物,或替換遭 SDK 抑制的建築物,因為這些建築物的頂點數量超過 Unity 支援的頂點數量上限 (每個網格 65,000 個頂點)。

這個場景開啟時,焦點會聚焦於西敏寺 (London),該模型似乎已由預法取代,因為這個特定模型太過精細,無法讓 Unity 處理 (因而因此遭到限制)。

此範例使用 ErrorHandling 元件,顯示載入幾何圖形時 MapsService 元件發生的所有錯誤。