Jetpack XR 適用的 ARCore

宣告依附元件

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

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

dependencies {
    implementation "androidx.xr.arcore:arcore:1.1.0-alpha01"
}

dependencies {
    implementation("androidx.xr.arcore:arcore:1.1.0-alpha01")
}

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

意見回饋

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

建立新問題

詳情請參閱 Issue Tracker 文件。

1.1 版本

1.1.0-alpha01 版本

2026 年 10 月 21 日

發布 androidx.xr.arcore:arcore-*:1.1.0-alpha01。1.1.0-alpha01 版包含這些修訂項目。

API 變更

• 推出 SpatialAnnotation API，用於追蹤 3D 實體幾何圖形和物件。新增 SpatialAnnotationTrackingOptions 和對應的建構工具模式，可透過相機圖片緩衝區設定空間追蹤。(I918ce)
• 在 Jetpack XR ARCore 中推出 SpatialAnnotation 和 SpatialAnnotationTrackingMode，讓開發人員能設定及追蹤針對實體真實世界空間環境的任意有界 3D 四邊形幾何圖形 (Quad)。(I880e4)
• 新增 TestSpatialAnnotation，允許在自動化測試中以程式輔助方式模擬空間註解。(If2335)
• 新增 geospatialPose、horizontalAccuracy、verticalAccuracy 和 orientationYawAccuracy 做為新 API，在地理空間狀態中提供更多資訊。(If28f8)

修正錯誤

• androidx.lifecycle:lifecycle-runtime 依附元件已更新至 2.10.0。如要搭配 AGP 9.5.0-alpha04 以上版本執行套裝生命週期執行階段 Lint 檢查，則必須使用這個版本。(I99bfd、b/556807521)
• 設定 AugmentedImage 時，檢查圖片數量上限是否為 0，並擲回 UnsupportedOperationException，而非意外失敗。I6ce439
• 妥善追蹤及取消算繪工作、處置實體，以及安全修改圖片集合，修正 AugmentedImageRenderer 中的記憶體流失和並行問題。Ie70760

1.0 版本

1.0.0 版

2026 年 10 月 21 日

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

1.0.0 的主要功能：

• ARCore for Jetpack XR 現已推出穩定版！ARCore for Jetpack XR 程式庫提供將數位內容與真實世界融合的功能。這個程式庫包含動作追蹤、永久錨點、點擊測試、使用語意標籤 (例如地板、牆壁和桌面) 辨識平面，以及使用 Google 視覺定位系統的地理空間姿勢。
• 詳情請參閱開發人員指南和 API 參考資料。

1.0.0-rc02 版

2026 年 10 月 7 日

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

修正錯誤

• 修正問題：不支援擴增圖片追蹤功能時，OpenXrRuntime 無法設定工作階段。(I8b9759)
• 修正多項問題，包括：使用 applicationContext 改善 XrInstanceManager 的記憶體管理、簡化 Session 和 Scene 快取機制，解決潛在的生命週期相關問題，以及強化 ReferenceCleaner，確保執行緒安全的清除註冊和明確處置。(Id0b76c)

1.0.0-rc01 版

2026 年 9 月 9 日

發布 androidx.xr.arcore:arcore-*:1.0.0-rc01。1.0.0-rc01 版本包含這些修訂版本。

1.0.0-beta02 版

2026 年 8 月 12 日

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

修正錯誤

• 修正 OpenXR 錨點持續性的並行問題。(I15c8b)
• 在更多類別中實作 toString()，以便偵錯。(I587e8)

1.0.0-beta01 版

2026 年 7 月 15 日

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

API 變更

• 更新可調整大小的修飾符，改用 ResizePolicy，而非兩個修飾符 (I7fb0f、b/496257436、b/519672992)
• 新增含有 movePolicy 參數的可移動超載，並淘汰 transformingMovable 和 movable (Ic88c1、b/481781189)
• 從公開 API 介面中移除 TrackingState.TRACKING_DEGRADED，並將地圖執行階段降級狀態改為 PAUSED。更新 TrackingState，使用列舉而非 int 值進行字串轉換和執行階段轉換。(I3eb5b、b/524326338)
• 將 Session.create 轉換為暫停函式。(I5d27f)
• 淘汰 ProjectedPermissionsResultContract (I141d5、b/515699436)
• 將 AnchorEntity 更新為 AnchorSpace (Ifa95e、b/513619219)

1.0.0-alpha15 版本

2026 年 6 月 17 日

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

API 變更

• 已移除「HitResult.createAnchor」，如果結果的可追蹤項目是 Anchorable，開發人員可以將命中位置提供給 Anchorable 的 createAnchor 函式，建立代表 HitResult 的錨點。(Ia851e)
• 已移除「AnchorUnsupportedObject」，JXR ARCore 執行階段不會再擲回這個例外狀況。(Ia851e)
• androidx.xr.arcore.Anchor 和 androidx.xr.arcore.ArDevice 現在會實作 androidx.xr.arcore.Trackable。(I57b65)
• Depth.left、Depth.right 和 Depth.mono 現在不可為空值 (I1fc5e)
• Face.getUserFace 現在不可為空值 (I0eac1)
• RenderViewpoint.left、RenderViewpoint.right、RenderViewpoint.mono 現在不可為空值 (Icf7fa)
• Hand.left 和 Hand.right 不可為空值 (Icef37)
• 新增 QrCode API (Ia0bbe)

1.0.0-alpha14 版本

2026 年 5 月 19 日

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

API 變更

• 淘汰 GeospatialMode.VPS_AND_GPS，改用 GeospatialMode.SPATIAL，並推出新的低功耗追蹤模式 GeospatialMode.INERTIAL，僅使用 IMU 和 GPS。(I1e6cd)
• 自訂錨定例外狀況類別：AnchorInvalidUuidException、AnchorNotAuthorizedException、AnchorUnsupportedLocationException、AnchorRuntimeFailureException 和 AnchorUnsupportedObjectException 現在是 RuntimeException 執行個體，不應檢查。(I9356e)
• 新增 ArCoreTestRule API，包括 TestArDevice、TestAugmentableObject、TestDepthMap、TestEye、TestFace、TestGeospatial、TestHand、TestPlane、TestRenderViewpoint 和 TestTrackable (I0ad3c)
• 移除 AnchorLoadInvalidUuid、AnchorCreateUnsupportedObject、AnchorCreateUnsupportedLocation 和 AnchorCreateNotAuthorized。現在，所有這些錯誤在執行階段都會視為例外狀況。移除 AnchorCreateIllegalState。在多數情況下，這項功能已由 AnchorCreateTrackingUnavailable 取代。新增 AnchorException 和衍生類別 AnchorInvalidUuidException、AnchorNotAuthorizedException、AnchorUnsupportedLocationException、AnchorRuntimeFailureException 和 AnchorUnsupportedObjectException。(I4c4dd)

外部貢獻

• 新增用於追蹤自訂標記的 AugmentedImage API (I0cf09)

1.0.0-alpha13 版

2026 年 5 月 6 日

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

API 變更

• TrackingState 和 VpsAvailabilityResult 已移至 androidx.xr.arcore package，且 androidx.xr.runtime 中的類型現已淘汰。(Ic7930、b/480462213)
• Plane.Type 已重新命名為 PlaneType。(I8c90c、b/482675376)
• Hand.HandSide 已重新命名為 HandSide。(Ica562、b/482675376)
• Plane.Label 已重新命名為 PlaneLabel。(Ic6b67、b/482675376)
• Geospatial.Surface 已重新命名為 GeospatialSurface。(I1a8be、b/482675376)
• Geospatial.State 已重新命名為 GeospatialState。(I203fa、b/482675376)
• 將 NativeData API 移至 xr:runtime:runtime 程式庫。(I87954、b/494251500)
• Session.create 和 Session.configure 現在僅列舉部分內容，且 when 陳述式中必須包含 else 子句。(I9885e、b/495805998、b/495805998)
• 淘汰了 androidx.xr.runtime.FieldOfView。請改用 androidx.xr.runtime.math.FieldOfView (Ia01a0、b/480233045)
• 將 Orbiter 變更為使用 OrbiterAnchorPoint + VolumeOffset 或 OrbiterPoseProvider，而非位置、偏移、offsetType、對齊和高度。同時也移除了 shouldRenderInNonSpatial 參數。如果開發人員不希望在非空間模式中算繪 Orbiter，應將 Orbiter 包裝在 if 陳述式中，並檢查 SpatialCapabilities。(I9fbb3、b/462428503)
• 新增可移動的修飾符。這些修飾符目前適用於 SpatialPanels 和 SpatialExternalSurface。SpatialGltfModels 很快也會支援這項功能。不過，我們的目標是讓所有 SubspaceComposables 都能妥善支援這些功能。(I9a3cd、b/479530787、b/478935063、b/478935063)
• 開發人員應觀察 ArDevice.state Flow 來監控 State.trackingState，並根據追蹤精確度調整應用程式的算繪或警告。(Ic00f0、b/445466590)
• 重新命名 HandJointType 列舉值。(Ifbc83、b/482670596)
• 重新命名 FaceConfidenceRegion 常數。(Ia62d5、b/482670596)
• 重新命名 FaceBlendShapeType 常數。(I33b8b、b/482670596)
• 新增 CreatePoseFromGeospatialPoseErrorInternal 及 CreateGeospatialPoseFromPoseErrorInternal。(I4bcf1、b/482666615)
• 將 DeviceTrackingMode.LAST_KNOWN 重新命名為 SPATIAL_LAST_KNOWN (包含已淘汰的備用方案)、新增 INERTIAL_LAST_KNOWN 以進行 3DoF 追蹤，並將 TRACKING_DEGRADED 新增至 TrackingState。(Ie661c、b/445466590)
• 淘汰了 GroupEntity。如要讓實體僅具備基本實體功能，請呼叫 Entity.create，系統會傳回實體介面。(I4c450、b/473867483)
• 新增 XrLog API。將 XrLog.isEnabled 設為 true，即可在 JetpackXR 中啟用記錄功能，並使用 XrLog.Level 設定記錄層級。(I76a1f、b/463460895、b/487378441)

修正錯誤

• 為 OpenXR 裝置新增裝置追蹤狀態支援。(I91485、b/445466590)

1.0.0-alpha12 版

2026 年 3 月 25 日

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

API 變更

• Config.augmentedObjectCategories 已從清單變更為集合。(I25a64、b/487376359)
• androidx.xr.arcore.Eye 和 androidx.xr.arcore.Hand 類型。(I42438、b/449032900)
• 新增 Session.create 超載，允許傳遞 Android Context 以限定資源範圍。(I7d3fe、b/415805990、b/477386334)
• 將 FakeRuntimeAnchor.ANCHOR_RESOURCE_LIMIT 變更為 FakeRuntimeAnchor.anchorResourceLimit。(I90841、b/431992235)
• 將 TiltGesture API 設為實驗性，因為日後可能會變更或移除。如要使用這個 API，請選擇加入 @ExperimentalGesturesApi (Ic9858)
• 新增在 Config 中設定 AugmentedObject 追蹤類別的功能 (I1f6e4、b/480220930)

修正錯誤

• 更新 META-INF/services/ 檔案，並提供 PerceptionRuntimeFactory 的實際位置，藉此修正 Chrome 的建構作業。(I7a801、b/481288291)

1.0.0-alpha11 版本

2026 年 2 月 25 日

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

1.0.0-alpha10 版本

2026 年 1 月 28 日

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

新功能

• 推出 TiltGesture API，提供回應式 Flow，可穩定偵測裝置傾斜 (向上/向下) 狀態和轉換進度。(Ic269f、b/448152779)
• Jetpack XR 適用的 ARCore 現在會使用 XR 執行階段記錄機制。詳情請參閱 androidx.xr.runtime.Log。(l52735、b/448697662)

API 變更

• Geospatial.createPoseFromGeospatialPose 現在可在支援 OpenXR 的裝置上運作。(l362c6)

1.0.0-alpha09 版本

2025 年 12 月 3 日

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

1.0.0-alpha08 版本

2025 年 11 月 19 日

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

新功能

• Jetpack XR 的 ARCore 現在支援可使用 Google Play 服務 - AR 適用的裝置。
• 新增 Geospatial API，用於 VPS 可用性和姿勢轉換 (I144dc)

1.0.0-alpha07 版本

October 22, 2025

發布 androidx.xr.arcore:arcore-*:1.0.0-alpha07。1.0.0-alpha07 版包含這些修訂版本。

修正錯誤

• :xr:arcore:arcore-openxr 已新增為 :xr:arcore:arcore 的實作依附元件 (I47315、b/446999229)

1.0.0-alpha06 版本

2025 年 9 月 24 日

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

API 變更

• ARCore 的測試支援已遷移至 xr:arcore:arcore-testing 模組。(I25469)
• 新增 ArDevice 和 RenderViewpoint，允許應用程式擷取裝置的姿勢和顯示設定，以便進行算繪。(Ib7e3f)
• 使用 HAND_JOINT_TYPE_ 前置字元重新命名 HandJointType 列舉。(I3f7cd)
• HandJointType 已從 xr:runtime:runtime 移至 xr:arcore:arcore。(Iadb9c、b/409058039)
• Hand.State 現在會公開 java.nio.FloatBuffer，其中包含關節姿勢，格式可讓注重效能的應用程式輕鬆存取。(I55e27)

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)
• stateFlowable 擴充功能函式已新增至 :xr:arcore:arcore-rxjava3，供 Java 開發人員使用。(I083aa、b/427247794)

API 變更

• Config *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() 已新增至 AnchorGuava，供 Java 開發人員使用。(I4af1c、b/425984631)
• Earth.createAnchorOnSurfaceAsync(Session, Double, Double, Double, Quaternion, Surface) 已新增至 EarthGuava，供 Java 開發人員使用。(I66357、b/425992992)
• Java 開發人員會使用 GltfModel.kt 中 GltfModel.createAsync 的擴充功能函式。GltfModel 中的非同步函式將會刪除。(I0af60)
• 這個程式庫現在使用 JSpecify 可為空值註解，屬於類型用途。Kotlin 開發人員應使用下列編譯器引數，強制執行正確用法：-Xjspecify-annotations=strict (這是 Kotlin 編譯器 2.1.0 以上版本的預設值) (Ia8420、b/326456246)
• subscribeAsFlowable 擴充功能函式已新增至 :xr:arcore:arcore-rxjava3，供 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 移至執行階段。
• 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 存取追蹤資訊。
• 產生錨點 (Anchor.create、Anchor.load、Plane.createAnchor) 的 API 現在都會傳回 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 程式庫，可將數位內容與真實世界融合。這個程式庫包含動作追蹤、永久錨點、點擊測試，以及平面識別與語意標籤 (例如地板、牆壁和桌面)。請參閱開發人員指南，進一步瞭解如何搭配使用 ARCore 和 Jetpack XR。

• Session：ARCore for Jetpack XR 會在背景使用 Jetpack XR Runtime 執行功能。您會使用工作階段與大多數 Jetpack XR 版 ARCore API 互動，因此請參閱相關說明文件。

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

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

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

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

  • 使用 hitTest 提供自然的使用者互動。hitTest 會使用 Ray 判斷與其交集的內容，並從該位置建立 Anchor。建議從 InputEvent 執行 hitTest。

已知問題

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

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

• 目前不支援持續保存先前已保存和未保存的錨點。

• 模擬器支援這項功能，但行為可能不如在實際裝置上執行時穩定。具體來說，呼叫 create 可能會失敗，並顯示原生程式碼錯誤，且立即終止活動。

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