共用方式為

世界鎖定工具的初始設定

  • 發行項

最精簡的可能設定

本教學課程將逐步解說最少的設定，以啟動並執行應用程式世界鎖定的所有專案，而不需要採取任何進一步的動作（例如空間錨點）。 其位於此存放庫的 範例 存放庫同層級中。

快速入門指南

這裡可以找到將 WLT 整合到專案的概念上較不詳細且 更務實的方法 。 適當時，它會參考回這些更徹底的頁面。 雖然這確實是個人偏好的問題，這種方法更合適，但快速閱讀 「開始 之前」頁面，可以省下本檔中投入精力的時間。

支援的環境

適用於 Unity 的世界鎖定工具目前以 HoloLens 系列裝置的 UWP 應用程式為目標。 支援原始 HoloLens （x86） 和 HoloLens 2 （ARM64）。

其他平台的實驗支援可透過 Unity 的 AR 子系統取得。

World Locking Tools 持續整合 （CI） 組建會使用 Visual Studio 2017 向 Unity2018.4.6f1 進行驗證。 不過，使用 Unity2018 版本和 Unity2019 的範圍，也已完成廣泛的 WLT 開發。 Visual Studio 2017 和 Visual Studio 2019 都用於開發工具。

如果您遇到其他 Unity 和/或 Visual Studio 版本的任何相容性問題，我們很想聽聽！ 回報任何問題的最佳方式是透過 GitHub 上的問題入口網站 。

假設背景

假設想要將世界鎖定工具解決方案整合到其專案中的人已經熟悉為 HoloLens 系列裝置建置和部署應用程式的基本概念。 如果沒有，本文結尾會有一些 絕佳的參考 。

世界鎖定工具層

世界鎖定工具分成四層。 隨著指向圖層相依的箭號，直接的相依性圖形看起來像這樣：

分層圖

虛線表示選擇性相依性。

雖然 Examples 層使用 MixedRealityToolkit （MRTK），但其他層沒有任何外部相依性，而且完整的功能可與 MRTK 相容，但與 MRTK 無關。

以下將進一步說明應用程式相依性。

層次摘要如下：

外掛程式

命令式介面，允許與引擎 DLL 進行直接通訊。 您可以在這裡完成自變數封送處理等常見問題，以及一些組合在複合指示詞中經常使用的多個函式組成。 它仍然是基礎 C++ DLL 的低階 C# 介面。 其直接使用是可用的，但不需要也不建議。

核心

Core 是取得世界鎖定工具穩定世界鎖定空間之所有必要步驟的封裝，封裝成宣告式介面。 預期工作應用程式只會使用 Core 中的功能來寄送。

工具

工具基本上是診斷性質。 世界鎖定工具程式的視覺效果包含在表單中，可輕鬆地新增至任何使用世界鎖定工具的專案。

包含其他 方便的公用程式 ，但預期有助於開始撰寫自定義解決方案的程序代碼，而不是作為核心供應專案的最終解決方案。

範例

範例層會在使用世界鎖定工具時嘗試呈現設定常見案例的範例，以及世界鎖定工具整合到各種案例中的最佳做法。

UX 和物件操作的任何必要 MRTK 相依性都僅限於範例層的腳本和預製專案。 這可讓較低層沒有任何外部相依性。

範例層中的腳本和資產不應直接整合到出貨產品中，不過沒有禁止。 相反地，他們的建築有利於簡單明瞭，而不是重複使用性和效率。

應用程式

一般而言，應用程式只需要相依於世界鎖定工具核心。

在開發期間，工具層提供許多視覺效果和其他協助程式來瞭解非預期的行為。 在理想情況下，這些協助程式會從已完成的應用程式中去除，或至少停用。 當然，它們也可以免費供其他用途使用，無論是以其目前的形式或修改。 如需詳細資訊，請參閱授權。

為了進階使用及測試世界鎖定工具的完整功能，外掛程式層提供引擎 DLL 的低階命令式存取。

如果需要存取外掛程式層，它可能會指出核心層中提供的 API 介面不足。 世界鎖定工具小組一直希望填補這類空白。 請考慮為小組提供這類深入解析。 請參閱 參與。

安裝路徑長度的警告附註

某些版本的 MRTK 有很長的安裝路徑問題。 MRTK 安裝中深層子資料夾的完整路徑長度可能超過 Windows 路徑限制（260 個字元）。 如果出現下列表單的建置錯誤：

DirectoryNotFoundException: Could not find a part of the path "D:\MyOverTwentyEightCharacterLongLengthInstallPath\MixedReality-WorldLockingTools-Unity\Assets\MRTK\MixedRealityToolkit.Providers\WindowsMixedReality\DotNetAdapter\Plugins\net46\Microsoft.Windows.MixedReality.DotNetWinRT\Editor\Microsoft.Windows.MixedReality.DotNetWinRT.Editor.asmdef"

但檔案實際上位於磁碟驅動器上，則問題可能是路徑長度。 MRTK 小組知道這一點，並正在努力改善它（注意：我相信他們在這裡做了很大的改進，它不再是問題）。 同時，因應措施是透過下列組合來縮短路徑前置詞：

  1. 將 Unity 專案安裝到較短長度的路徑根目錄中，例如 “D：\Proj”
  2. 如果複製存放庫，請將世界鎖定工具的根目錄複製到比預設 “\MixedReality-WorldLockingTools-Unity” 短的專案，例如：
git clone https://github.com/microsoft/MixedReality-WorldLockingTools-Unity.git d:\MyGit\wlt

此路徑限制通常不是世界鎖定工具本身的問題，因為它們不會使用深度的資料夾結構。

將世界鎖定工具新增至 Unity 專案

注意

下列說明手動安裝世界鎖定工具和相依性。 透過混合實境功能工具可取得更精簡的安裝程式。 這裡說明透過功能工具安裝。 如果功能工具安裝 WLT，您可以略過下列專案，並繼續 將 WLT 新增至場景

世界鎖定工具依賴 nuget 來安裝基礎凍結世界引擎。

如果將世界鎖定工具新增至現有的項目，建議您從已驗證的專案開始建置並部署至 HoloLens 裝置。 這有助於將應用程式在 HoloLens 上第一次執行的問題與世界鎖定工具的問題分開，這可能會很複雜。 然後繼續進行 下面的 FrozenWorld Engine 安裝和World 鎖定工具資產 一節。

FrozenWorld Engine 安裝

凍結的世界引擎 DLL 可以使用絕佳的 NuGet For Unity 公用程式，或手動從 NuGet 取得。

使用 NuGet for Unity

請確定 nuget.org 摘要位於來源中。 在 Unity > 編輯 > 喜好 > 設定 NuGet for Unity 中檢查此專案。 如果沒有， 請執行下列其中一項：

使用 Unity > 編輯>喜好>設定 NuGet For Unity 中的 [新增來源 GUI] 來新增相同的共用。

  • 以您選擇的名稱取代 「New Source」（例如，“NuGet” ）。
  • 將 「source_path」 取代為 “http://www.nuget.org/api/v2/" ;。

確認 nuget.org 摘要之後，在 Unity > NuGet 管理 NuGet > 套件中，尋找並安裝最新版本的 Microsoft.MixedReality.FrozenWorld.Engine。 （搜尋“冰凍世界”。）

若要更新為更新版本，請再次開啟 Unity > NuGet 管理 NuGet > 套件，然後尋找 FrozenWorld.Engine 套件，然後選取 [更新]。 注意：您可能必須前往 [更新] 索引標籤，才能尋找您要尋找的版本。

手動凍結世界引擎 DLL 安裝

使用文本編輯器將一 packageSources 行新增至 Assets/NuGet.config，例如：

  <packageSources>
    <add key="NuGet" value="http://www.nuget.org/api/v2/" />
  </packageSources>

如果您還沒有檔案 Assets/NuGet.config，您可以從世界鎖定工具 github 存放庫複製它。

使用文本編輯器，將凍結的世界引擎 DLL 套件新增至 Assets/packages.config，例如：

<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="Microsoft.MixedReality.Unity.FrozenWorld.Engine" version="1.0.0" />
</packages>

同樣地，如果您還沒有檔案 Assets/packages.config，您可以從 World 鎖定工具 github 存放庫取得檔案，或只是將上述複製到名為 “Assets/packages.config” 的文本檔。

設定 NuGet.config 和 packages.config 後，請依下列方式安裝：

  1. 從 NuGet 下載取得最新的nuget.exe。
  2. 請確定nuget.exe位於您的路徑中（這裡我會假設它已複製到資產中）。
  3. 開啟 PowerShell 命令視窗，並將目錄變更為 Assets 資料夾。
  4. 執行以下命令：
.\nuget.exe restore

若要升級至更新版本：

  1. 將上述 packages.config 檔案中的 FrozenWorld.Engine 版本號碼更新為所需的版本（例如，version=“1.0.0” 會變成 version=“1.0.1”。
  2. 從 「Microsoft.MixedReality.Unity.FrozenWorld.Engine」 開始，刪除 Assets/Packages 資料夾中的任何專案。
  3. 如上所示重新執行nuget.exe。

世界鎖定工具資產

將所需的世界鎖定工具 .unitypackage 檔案匯入專案（慣用的方法），或將它們複製到中。 它們可能會移至 Assets 內的子資料夾，讓他們擺脫應用程式開發的方式。

最新的穩定.unitypackage檔案可在適用於 Unity 版本的世界鎖定工具中找到。

絕對需要 WorldLocking.Core 和引擎層，因此最小安裝套件會是 WorldLockingCoreEngine.unitypackage。

若要判斷可能需要哪些其他圖層，請參閱上述世界鎖定工具層及其相依性的討論。 每一層都包含在單一 Unity 套件中。

由於某些「世界鎖定工具範例」使用 MRTK 的功能，因此範例隨附 unitypackage相容的 MRTK 快照集。 如需最新的 MRTK 版本，請參閱 這裡。

將世界鎖定工具新增至 Unity 場景

注意

下列步驟都是在 WLT 設定場景公用程式中自動化的，您可以在 [混合實境工具組 > 公用程式] [公用程式 > ] [世界鎖定工具] 功能表中找到。 Configuraton 功能表

在包含 FrozenWorld 引擎的 Unity 專案中（從 nuget.org），匯入任何所需的世界鎖定工具資產層（但至少為 WorldLocking.Core），以及選擇性的 MRTK。 然後建立新的場景（或開啟現有的場景）。

注意

在相機階層的根目錄新增額外的節點。 此節點將用來將頭部追蹤相機調整為世界鎖定的空間。 （如果使用 MRTK，這個新的 GameObject 會是 MixedRealityPlayspace 的父代 。

核心體驗

將 WorldLockingManager 預製專案從 Assets/WorldLocking.Core/Prefabs 拖曳到您的場景中。 它在場景中的位置並不重要，但它不應該在相機樹中。 如需建議的設定，請參閱範例場景。

WorldLockingManager 預製專案有可用的設定，但建議將其保留為其預設值，以開始使用。

如需所呈現選項的說明，請參閱 世界鎖定工具內容 。

[選擇性]MRTK

世界鎖定工具是互補的，但與 MRTK 的正交。 MRTK 與世界鎖定工具的使用是完全選擇性的。

也就是說，世界鎖定工具範例是使用 MRTK 建置的，MRTK 在開發受益於世界鎖定工具的 MR 應用程式類型方面通常非常有價值。

如果使用 MRTK，而不是使用範例隨附的快照集，建議您至少新增下列套件的最新版本：

  • MixedReality.Toolkit
  • MixedReality.Toolkit.Providers
  • MixedReality.Toolkit.Services
  • MixedReality.Toolkit.SDK

[選擇性]可視化海綿和世界鎖定錨點

這需要將 WorldLocking.Tools 新增至專案的 Assets。

如果您想要將錨點可視化，請將AnchorGraphVisual預製專案從Assets/WorldLocking.Tools/Prefabs 拖曳到您的場景中。 在 Inspector 中切換視覺效果層面的複選框位於 WorldLockingManager 上。

由於診斷，WorldLocking.Tools 視覺效果並未大幅優化，而且會在核心世界鎖定工具處理時間變得相關之前，降低效能。

[選擇性]混合實境內參數控件的簡單儀錶板

提供簡單的 HUD，可用來在運行時間從 MR 內部控制 WorldLockingManager。 這些會提供於範例套件中。 雖然它們可以像往常一樣使用，但當將類似的功能建置至應用程式自己的顯示系統和 UX 時，它們會作為模式。

拖曳到 WorldLocking.Examples/Prefabs/Dashboard 預製專案，並將其錨點可視化檢視欄位指向上一節中的可視化檢視。

將現有的場景移轉至世界鎖定工具

移至世界鎖定工具時，最大的變更是不再需要使用空間錨點來鎖定世界鎖定虛擬物件。

空間錨點傳統上是唯一可供世界鎖定個別物件使用的工具。 但是，使用世界鎖定工具時，這些虛擬物件的座標空間已經世界鎖定。 不需要進一步鎖定。

空間錨點不僅不需要，而且無法正確運作，因為它們無法考慮相機階層的額外轉換（例如 MRTK “Playspace” 轉換）。

因此，應該從場景中移除任何和所有空間錨點，而且任何新增空間錨點的腳本都應該停止這樣做。 空間錨點不需要由任何專案取代;世界鎖定工具會將目標錨定到真實世界。

如果想要比較世界鎖定與沒有世界鎖定工具，而不是移除 WorldAnchors，它們可能會取代為 WorldLocking.Tools 中提供的 ToggleWorldAnchor 。

ToggleWorldAnchor 的運作方式與 WorldAnchor 完全相同，其重要差異在於，當世界鎖定工具管理員處於作用中狀態時，它會方便停用本身並脫離。 停用世界鎖定工具管理員時，其行為會是一般的 WorldAnchor。

如果基於其他一些原因，場景仍需要 WorldAnchors（例如網路共用），則可以搭配提供作為 WorldAnchorAdapter 的 適配卡使用。

WorldAnchorAdapter 會將由 WorldAnchor 定位的 GameObject 原始位置轉換成鎖定的 Unity 全域空間，然後將轉換套用至目標物件。 若要使用它，而不是將 WorldAnchor 直接新增至物件，WorldAnchor 應該套用至 Proxy 物件（通常是空白的 GameObject），然後在 Update（） 上，WorldAnchorAdapter 會讀取 WorldAnchor 的姿勢、正確轉換它，並將其套用至目標。

安裝程式完成

遵循上述步驟之後，部署至裝置的專案將會由世界鎖定工具進行調整，以維持最穩定的世界鎖定空間。 放置在場景中的任何固定對象，都會保持彼此和實體世界的視覺一致。

可用的範例應用程式

提供範例場景，包括腳本和資產，以示範世界鎖定工具功能的更複雜用法。

例如， WorldLockedPhysicsSample 提供簡單的環境，在其中可以建立和移除實體仿真的物件，彼此互動，並與環境互動（空間對應）。

如需更專注的太空釘選功能，SpacePin提供了一個簡化的範例，可將大規模虛擬對象與真實世界功能對齊。

RayPins 會擴充 SpacePin 範例所引進的功能，允許使用針對空間網格的光線測試將虛擬世界釘選到實體世界。

開始使用的參考

如果您不熟悉建立、建置和部署AR應用程式至HoloLens系列裝置的基本概念，以下是一些有助於開始使用的參考。

Unity 開發概觀 - 適用於 MR/AR 開發的 Unity。

MR Basics 100 - 逐步解說 HoloLens 的入門開發

HoloLens 2 教學課程 - 逐步解說 HoloLens 2 的入門開發。

坐標系統 在AR開發中協調空間影響。

  • 請注意，世界鎖定工具可解決這裡討論的問題。

有任何問題嗎？

請參閱 疑難解答指南。