適用於 Jetpack XR 的 ARCore

如要為 Jetpack XR 新增 ARCore 的依附元件，必須將 Google Maven 存放區新���至專案。詳情請參閱「 Google 的 Maven 存放區」。

在應用程式或模組的 build.gradle 檔案中，新增所需構件的依附元件：

dependencies {
    implementation "androidx.xr.arcore:arcore:1.0.0-alpha05"
}

dependencies {
    implementation("androidx.xr.arcore:arcore:1.0.0-alpha05")
}

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 說明文件。

1.0 版本

1.0.0-alpha05 版本

2025 年 7 月 30 日

發布 androidx.xr.arcore:arcore:1.0.0-alpha05、androidx.xr.arcore:arcore-guava:1.0.0-alpha05 和 androidx.xr.arcore:arcore-rxjava3:1.0.0-alpha05。1.0.0-alpha05 版包含這些修訂項目。

新功能

• 新增 getPrimaryHandSide，讓開發人員取得左側資訊 (I270bd)
• 新增地理空間檢查 VPS 可用性 API (I58573)
• 新增 checkVpsAvailability 的 ARCore API (Idbded)
• 新增至 :xr:arcore:arcore-rxjava3 的 stateFlowable 擴充功能函式，供 Java 開發人員使用。(I083aa、b/427247794)

API 變更

• 設定 *Mode 值已重新命名，以反映其行為。(I6d247、b/414648065)
• 主要的 ARCore 構件 (xr:arcore:arcore) 只會包含 Kotlin 樣式的非同步 API。Java 開發人員可以依附 xr:arcore:arcore-rxjava3 程式庫，存取相容的 API。(Ia525e、b/422794329)
• 主要的 ARCore 構件 (xr:scenecore:scenecore) 只會包含 Kotlin 樣式的非同步 API。Java 開發人員可以依附 xr:arcore:arcore-guava 程式庫，存取相容的 API。(Iffcb4、b/422773524)
• Anchor.persistAsync()，供 Java 開發人員使用。AnchorGuava(I4af1c、b/425984631)
• Earth.createAnchorOnSurfaceAsync(Session, Double, Double, Double, Quaternion, Surface)，供 Java 開發人員使用。EarthGuava(I66357、b/425992992)
• Java 開發人員會在 GltfModel.kt 中使用 GltfModel.createAsync 的擴充功能函式。系統會刪除 GltfModel 中的非同步函式。(I0af60)
• 這個程式庫現在使用 JSpecify 空值註解，這些註解屬於型別用途。Kotlin 開發人員應使用下列編譯器引數，強制執行正確用法：-Xjspecify-annotations=strict (這是 Kotlin 編譯器 2.1.0 版的預設值) (Ia8420、b/326456246)
• 新增至 :xr:arcore:arcore-rxjava3 的 subscribeAsFlowable 擴充功能函式，供 Java 開發人員使用。(Id3e49、b/427277298)

1.0.0-alpha04 版本

2025 年 5 月 7 日

發布 androidx.xr.arcore:arcore:1.0.0-alpha04。1.0.0-alpha04 版包含這些修訂項目。

API 變更

• 以 Kotlin 2.0 發布的專案必須使用 KGP 2.0.0 以上版本。(Idb6b5)
• TrackingState 和 HandJointType 已從 ARCore 移至 Runtime。
• 「Hand.State.isActive (boolean)」已變更為「Hand.State.trackingState (androidx.xr.runtime.TrackingState)」。
• 如果 UUID 無效，Anchor.load 會傳回 Anchor.AnchorLoadInvalidUuid。

1.0.0-alpha03 版本

2025 年 2 月 26 日

發布 androidx.xr.arcore:arcore:1.0.0-alpha03，該版本與上一個 Alpha 版沒有差別。1.0.0-alpha03 版包含這些修訂項目。

1.0.0-alpha02 版

2025 年 2 月 12 日

發布 androidx.xr.arcore:arcore:1.0.0-alpha02。1.0.0-alpha02 版包含這些修訂項目。

新功能

• 新增手部追蹤支援。使用 Hand.left 和 Hand.right 存取追蹤資訊。
• 產生錨點的 API (Anchor.create、Anchor.load、Plane.createAnchor) 現在都會傳回 AnchorCreateResult，並正確實作 AnchorCreateResourcesExhausted。

修正錯誤

• Anchor.detach 不會再因工作階段更新執行緒的競爭情況而導致嚴重異常終止。
• 在模擬器上執行 Anchor.create 時更穩定

1.0.0-alpha01 版

2024 年 12 月 12 日

發布 androidx.xr.arcore:arcore-* 1.0.0-alpha01。

初始版本的功能

ARCore for Jetpack XR 程式庫的靈感來自現有的 ARCore 程式庫，可提供將數位內容融入真實世界的功能。這個程式庫包含動作追蹤、持續性錨點、命中測試，以及使用語意標籤 (例如地板、牆壁和桌面) 識別平面。如要進一步瞭解如何使用 Jetpack XR 的 ARCore，請參閱開發人員指南。

• Session：Jetpack XR 適用的 ARCore 會在幕後使用 Jetpack XR Runtime，提供相關功能。您會使用 Session 與大多數 ARCore for Jetpack XR API 互動，因此請參閱相關說明文件。

• Plane：使用平面瞭解周遭世界。每個平面都有 Label，可從語意上描述平面。你可以使用 subscribe 接收最新偵測到的飛機通知，或使用 state 接收特定飛機的變更通知。

• Anchor：虛擬物件與現實世界位置之間的連結。錨點可以附加至空間中的特定位置 (使用 create)，或附加至 Trackable (使用 createAnchor)。

  • 錨點可在不同工作階段中重複使用。您可以使用 persist 儲存這些項目、使用 getPersistedAnchorUuids 列舉這些項目，以及使用 load 擷取這些項目。請務必在不再使用時unpersist這些裝置。

  • 錨點可在 Jetpack XR 適用的 ARCore 和 Jetpack SceneCore 之間互通。您可以使用錨點建立 AnchorEntity，也可以使用 getAnchor 擷取現有 AnchorEntity 的支援錨點。

  • 使用 hitTest 提供自然的使用者互動。hitTest 會使用 Ray 判斷與哪些內容相交，並從該位置建立 Anchor。請考慮從 InputEvent 執行 hitTest。

已知問題

• 呼叫 unpersist 後，系統可能需要一段時間，才會從 getPersistedAnchorUuids 傳回的結果中移除 UUID。

• create 不會驗證系統是否有足夠資源來傳回新錨點。建立過多錨點可能會導致當機。

• 目前不支援保存先前已保存但未保存的錨點。

• 系統支援在模擬器中使用，但行為可能不如在實際裝置上執行時穩定。特別是，對 create 的呼叫可能會因原生程式碼錯誤而失敗，並立即終止活動。

• 在某些情況下，使用「Anchor was not persisted」訊息呼叫 persist 時，可能會錯誤擲回 RuntimeException。在這些情況下，函式仍會成功，且錨點會持續存在。建議您將對 persist 的呼叫包裝在 try 區塊中，做為替代方案。