stable
) 或最新版 (latest
)或是特定版號(數字),避免底層 API 變動影響既有系統。若有使用WebXR experience helper就可以直接有 .featuresManager可以使用。
// 透過 Experience Helper 取得 Features Manager
const fm = xrHelper.featuresManager;
在啟用任何功能前,最好先確認它是否被瀏覽器或 Babylon.js 支援,有兩種方式:
// 取得所有可用的功能名稱陣列
const availableFeatures = BABYLON.WebXRFeaturesManager.GetAvailableFeatures();
// 檢查特定功能是否可用
if (availableFeatures.includes(BABYLON.WebXRFeatureName.POINTER_SELECTION)) {
// 指針選擇功能 (Pointer Selection) 可用
}
並可以取得可用的所有版本號:
const availableVersions = featuresManager.GetAvailableVersions(WebXRFeatureName.POINTER_SELECTION);
功能模組 | 名稱 | 典型用途 |
---|---|---|
傳送移動 | TELEPORTATION |
解決 VR 暈眩的移動方法。 允許使用者瞬間改變位置,取代傳統的自由行走。 |
指標選取 | POINTER_SELECTION |
遠距離互動。 從控制器或手部發射光線(Ray),用於點擊虛擬按鈕、操作懸浮 UI 或選擇遠處物件。 |
碰撞偵測 (AR) | HIT_TEST |
真實世界錨定。 偵測和識別真實世界的表面(地面、牆壁、桌面),以便精確放置虛擬物件。 |
手部追蹤 | HAND_TRACKING |
自然輸入。 追蹤使用者雙手骨骼結構和動作,無需控制器。 |
錨點系統 | ANCHOR |
空間記憶。 讓虛擬物件鎖定在真實世界的特定座標,即使關閉並重新開啟應用程式也能保持位置。 |
運動邊界 | MOVEMENT_BOUNDS |
安全防護。 定義使用者在實體世界中的安全活動範圍。 |
Enable:enableFeature
初始化功能。
Attach:attach
啟動功能。(用在功能物件本身)
Detach:detach
暫停功能。可快速重新附加。(用在功能物件本身)
Disable:disableFeature
銷毀功能。
enableFeature
會將功能初始化載入並設定好,是將功能帶入場景的關鍵步驟,但不一定立即開始作用。以下用想啟用HIT_TEST
和TELEPORTATION
為例:
// 「最新版本」的 Hit Test 功能
const xrHitTestLatest = fm.enableFeature(BABON.WebXRFeatureName.HIT_TEST, "latest");
// 「特定版本」的 Teleportation 功能
const xrTeleport = fm.enableFeature(BABYLON.WebXRFeatureName.TELEPORTATION, 1);
// 之後在邏輯需要時手動啟動
xrHitTestLatest.attach();
// 暫停功能
xrHitTestLatest.detach();
// 銷毀功能並清理
fm.disableFeature(BABYLON.WebXRFeatureName.HIT_TEST);
fm.disableFeature(BABYLON.WebXRFeatureName.TELEPORTATION);
// 或是銷毀 Features Manager 本身, 可以一次銷毀不必手動呼叫每個 disableFeature
fm.dispose();
不難發現狀態管理對於WebXR來說不僅是眾多,並且交互關係繁雜的。因此進階的互動邏輯都是透過訂閱這些功能模組的Observables來實現的。這讓程式碼只在事件發生時才執行,可以讓效率提高。
// 啟用最新版本的指標選取功能
const xrPointerSelection = fm.enableFeature(BABYLON.WebXRFeatureName.POINTER_SELECTION, "latest");
// 你可以訂閱它的事件,例如當指針點擊物件時
xrPointerSelection.onPointerSelectedObservable.add((pointerInfo) => {
// 檢查被點擊的物件並執行邏輯
console.log("物件被點擊:", pointerInfo.hit.pickedMesh.name);
});
傳送移動 (TELEPORTATION)
觀察者 (Observable) | 參數類型 | 觸發時機 |
---|---|---|
onTeleportationRequestObservable |
WebXRTeleportationEvent |
已選定目標,但尚未移動 |
onTeleportationObservable |
WebXRTeleportationEvent |
傳送完成後玩家已到達新位置 |
onTargetMeshObservable |
AbstractMesh |
傳送弧線選定一個有效的傳送目標網格時 |
指標選取 (POINTER_SELECTION)
觀察者 (Observable) | 參數類型 | 觸發時機 |
---|---|---|
onPointerSelectedObservable |
WebXRControllerPointerSelection |
|
onPointerMoveObservable |
WebXRControllerPointerSelection |
當指標瞄準的物體發生變化時 |
onPointerOutObservable |
WebXRControllerPointerSelection |
當指標離開一個網格時 |
AR 模式中虛擬物件在真實世界的放置位置 (HIT_TEST)
觀察者 (Observable) | 參數類型 | 觸發時機 |
---|---|---|
onHitTestResultObservable |
WebXRHitResult[] |
每一幀或當你配置的觸發條件達成時,返回所有有效的碰撞偵測結果 |
onHitTestAdd |
WebXRHitTestResult |
首次成功偵測到一個 Hit Test 結果時 |
手部追蹤 (HAND_TRACKING)
觀察者 (Observable) | 參數類型 | 觸發時機 |
---|---|---|
onHandReadyObservable |
IWebXRHand |
|
onHandClosedObservable |
IWebXRHand |
當使用者做出「抓取」手勢(握拳)時 |
onHandOpenedObservable |
IWebXRHand |
當使用者鬆開「抓取」手勢(張開手掌)時 |