Godot'da uzamsal kapsayıcıları kullanma

Uygun XR cihazlar

Bu kılavuz, bu tür XR cihazları için deneyimler geliştirmenize yardımcı olur.

XR cihaz türleri hakkında bilgi edinin →

XR cihaz türleri hakkında bilgi edinin →

Üç boyutlu kapsayıcılar, uygulamanızın Tam Ekran Alanı modunda sistem tarafından yönetilen üç boyutlu hacimsel sınırlayıcı kutu içinde üç boyutlu OpenXR içeriği oluşturmasına veya çalışma zamanında tam ekran sınırsız deneyime geçmesine olanak tanır.

Projenizde Spatial Containers'ı yapılandırmak ve kullanmak için bu kılavuzu inceleyin.

Üç boyutlu kapsayıcıların işleyiş şekli

Proje ayarlarınızda Spatial Container'ı etkinleştirdiğinizde:

• Etkin 3D sahnenizin tamamı, sahne orijininde (0, 0, 0) ortalanmış tek bir birincil uzamsal kapsayıcıya yerleştirilir. Node3D düğümlerini kapsayıcıya yerleştirmek için etiketlemeniz veya ayrı ayrı atamanız gerekmez.
• Uygulamanız, proje ayarlarınızda yapılandırılan Sınır Modu (Bounded veya Immersive) ve ilk Sınırlar boyutlarını kullanarak yönetilen Tam Ekran Alanı Modu'nda başlatılır. Sınırlı modda sistem, sahnenizdeki sınırlayıcı kutunun boyutlarının dışına taşan tüm 3D geometrileri otomatik olarak kırpar.
• Android XR sistemi, varsayılan olarak pencere kontrolleri sağlar. Böylece kullanıcı, sınırlı kapsayıcıyı 3D alanda tutup taşıyabilir, yeniden konumlandırabilir, simge durumuna küçültebilir ve kapatabilir. Uygulamanız çalışma zamanında kapsayıcıyı yeniden boyutlandırabilir, sınırlı mod (OpenXRSpatialContainerState.BOUNDED) ile tam ekran yoğun içerik modu (OpenXRSpatialContainerState.IMMERSIVE) arasında geçiş yapabilir ve OpenXRSpatialContainerExtension singleton'u kullanarak sınırlara ve durum değişikliklerine tepki verebilir.

Ön koşullar

Başlamadan önce, geliştirme ortamınızın ve hedef cihazınızın aşağıdaki şartları karşıladığından emin olun:

• Godot sürümü: Godot 4.8-dev veya sonraki sürümler.
• Proje kurulumu: Godot Engine proje kurulumu kılavuzundaki tüm adımları tamamlayın.
• Godot OpenXR Vendors Plugin: Android XR'a özel uzantılar için destek sağlayan Godot OpenXR Vendors Plugin'in 5.2 veya sonraki bir sürümünü yükleyin.
• Hedef cihaz: Spatial API düzeyi 4 veya sonraki sürümleri destekleyen bir Android XR cihaz. Çalışma zamanında, uzantının cihazda kullanılabilir olup olmadığını doğrulamak için OpenXRSpatialContainerExtension.is_enabled() yöntemini çağırın.

Proje ayarlarında Spatial Containers'ı etkinleştirin

OpenXR, Spatial Containers, çalışma zamanında istenen otomatik izinler ve alfa karışımlı geçişi etkinleştirmek için proje ayarlarınızı yapılandırın:

1. Proje > Proje Ayarları'nı açın.
2. Proje Ayarları penceresinin sağ üst köşesindeki Gelişmiş Ayarlar açma/kapatma düğmesini etkinleştirin.
3. General > XR > Shaders'a (Genel > XR > Gölgelendiriciler) gidin ve Enabled'ı (Etkin) seçin.
4. General > XR > OpenXR'a (Genel > XR > OpenXR) gidin ve aşağıdaki ayarları yapılandırın:
   • Proje için OpenXR'ı etkinleştirmek üzere Etkin'i seçin.
   • Environment Blend Mode'u (Ortam Karıştırma Modu) Alpha Blend (Alfa Karışımı) olarak ayarlayın.
5. Ayrıca OpenXR altında Uzantılar bölümüne gidin ve aşağıdaki ayarları yapılandırın:
   • Uygulamanızın, Android manifest dosyanızda belirtilen XR izinleri için başlangıçta kullanıcıdan otomatik olarak izin istemesi amacıyla Çalışma Zamanında İstenen İzinleri Otomatik Olarak İste'yi seçin.
   • Spatial Container alt bölümünde Etkin'i seçin.
   • 3D sınırlayıcı kutuda başlatmak için Bounds Mode'u (Sınır Modu) Bounded (Sınırlı) olarak ayarlayın veya tam ekran yoğun içerik modunda başlatmak için Immersive (Yoğun İçerik) olarak ayarlayın.
   • Sınırlar'ı metre cinsinden ilk genişlik, yükseklik ve derinlik boyutlarına (ör. Vector3(1.0, 1.0, 1.0)) ayarlayın.
6. General > Rendering > Viewport'a (Genel > Oluşturma > Görüntü Alanı) gidin ve Transparent Background'u (Şeffaf Arka Plan) seçin.

Android dışa aktarma, izinler ve Tam Ekran Alanı modunu yapılandırma

Ardından, uygulamanızın Tam Ekran Alanı modunda çalışması ve konumsal kapsayıcıların etkinleştirilmesi için Android dışa aktarma hazır ayarınızı, izinlerinizi ve etkinlik başlatma modunuzu yapılandırın.

Android dışa aktarma hazır ayarını yapılandırma

1. Project > Export... (Proje > Dışa aktar...) bölümüne gidin ve Android dışa aktarma hazır ayarınızı seçin.

2. Gradle Build bölümünde Use Gradle Build'i seçin ve Min SDK'yı 34 veya daha yüksek bir değere ayarlayın.

   

3. XR Features (XR Özellikleri) bölümünde XR Mode'u (XR Modu) OpenXR olarak ayarlayın ve Enable AndroidXR Plugin'i (AndroidXR Eklentisini Etkinleştir) seçin.

   

4. Android XR Özellikleri bölümünde Deneysel Özellikleri Kullan'ı seçin.

Zemin kilitleme için sahne algılama izinleri ekleme

Temel bir uzamsal kapsayıcı oluşturmak ve oluşturmak için tehlikeli çalışma zamanında istenen izinler gerekmez (ve Deneysel Özellikleri Kullan etkinleştirildiğinde android.permission.HEAD_TRACKING otomatik olarak manifest dosyasına eklenir). Ancak uygulamanız, uzamsal kapsayıcıyı fiziksel zemine kilitleme ve sabitleme gibi sahne algılama özelliklerini kullanıyorsa çalışma zamanında android.permission.SCENE_UNDERSTANDING_COARSE iznini beyan etmeli ve istemelidir.

Android XR izinleriyle ilgili ayrıntılar için XR izinlerini anlama başlıklı makaleyi inceleyin. Uygulamanız zemin kilitleme veya sahne algılama özelliğini kullanıyorsa şunları beyan edin ve isteyin android.permission.SCENE_UNDERSTANDING_COARSE:

1. Proje > Dışa aktar... > Android'e gidin, İzinler > Özel İzinler'e gidip android.permission.SCENE_UNDERSTANDING_COARSE öğesini ekleyin.

2. Project Settings > General > XR > OpenXR > Extensions (Proje Ayarları > Genel > XR > OpenXR > Uzantılar) bölümünde Automatically Request Runtime Permissions'ı (Çalışma Zamanında İstenen İzinleri Otomatik Olarak İste) seçerseniz uygulamanız, OpenXR başladığında otomatik olarak izin ister. GDScript'te izni manuel olarak istemeniz gerekiyorsa OS.request_permission() yöntemini çağırın:

   if not OS.get_granted_permissions().has("android.permission.SCENE_UNDERSTANDING_COARSE"):
       OS.request_permission("android.permission.SCENE_UNDERSTANDING_COARSE")
   

Tam Ekran Alanı Modu'nu yapılandırma

Android XR'daki uzamsal kapsayıcılar yalnızca Tam Ekran Alanı modunu (XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED) destekler. Android etkinliğinizin, özel derleme şablonunuzda (Proje > Android Derleme Şablonu Yükle... kullanılarak yüklenen android/build/AndroidManifest.xml) XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED değerini beyan ettiğinden emin olun:

<manifest ...>
    <application ...>
        <property
            android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE"
            android:value="XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED"
            tools:replace="android:value" />
        ...
    </application>
</manifest>

GDScript'te uzamsal kapsayıcılarla çalışma

OpenXRSpatialContainerExtension singleton ve OpenXRSpatialContainerState sınıfı, XR_EXT_spatial_container ve XR_EXT_spatial_container_self_rendering uzantılarını GDScript'e gösterir. Çalışma zamanında, ana uzamsal kapsayıcının durumunu ve sınırlarını incelemek, kapsayıcı sinyallerini dinlemek ve BOUNDED modu (3D sınırlayıcı kutu) ile IMMERSIVE modu (tam ekran sınırsız görünüm) arasında geçiş isteğinde bulunmak için OpenXRSpatialContainerExtension kullanın.

Spatial Container sinyallerine bağlanma

OpenXRSpatialContainerExtension.is_enabled() öğesini kontrol ederek Spatial Container uzantısının mevcut cihazda desteklendiğini ve etkin olduğunu doğrulayın, ardından _ready() öğesindeki container sınırlarına ve durum sinyallerine bağlanın.

OpenXRSpatialContainerExtension, uzamsal kapsayıcı için aşağıdaki durum sinyallerini yayınlar:

• spatial_container_visibility_changed: Kapsayıcı gösterildiğinde (true) veya gizlendiğinde (false) (spatial_container, is_visible) ile yayınlanır. is_visible, false olduğunda animasyonları, sesleri veya simülasyon güncellemelerini duraklatın.
• spatial_container_interactability_changed: Kapsayıcı, kullanıcı girişi odağını kazandığında (true) veya kaybettiğinde (false) (spatial_container, is_interactive) ile birlikte yayınlanır. Odak değiştiğinde etkileşimli vurgulamaları ve giriş işlemeyi etkinleştirin veya devre dışı bırakın.
• spatial_container_bounds_mode_changed: Kapsayıcı OpenXRSpatialContainerState.BOUNDED ile OpenXRSpatialContainerState.IMMERSIVE arasında geçiş yaptığında (spatial_container, bounds_mode) ile birlikte yayınlanır. Ortam görsellerini (ör. gökyüzü kutuları veya geçiş) ve moda özel kullanıcı arayüzü kontrollerini açıp kapatın.

func _ready() -> void:
    if OpenXRSpatialContainerExtension.is_enabled():
        OpenXRSpatialContainerExtension.spatial_container_bounds_changed.connect(
            _on_bounds_changed
        )
        OpenXRSpatialContainerExtension.spatial_container_bounds_mode_changed.connect(
            _on_bounds_mode_changed
        )
        OpenXRSpatialContainerExtension.spatial_container_visibility_changed.connect(
            _on_visibility_changed
        )
        OpenXRSpatialContainerExtension.spatial_container_interactability_changed.connect(
            _on_interactability_changed
        )

func _on_visibility_changed(_rid: RID, is_visible: bool) -> void:
    # Pause or resume simulation and audio based on visibility
    pass

func _on_interactability_changed(_rid: RID, is_interactive: bool) -> void:
    # Enable or disable input handling and focus highlights
    pass

3D içeriği kapsayıcı sınırlarına göre ölçeklendirme

BOUNDED modundayken 3D içeriğinizi bounds öğesinin en küçük boyutuna göre eşit şekilde ölçeklendirin. Böylece en boy oranı korunur ve içerik her zaman kapsayıcının en küçük tarafına sığar. IMMERSIVE moduna geçerken sahnenizi 1:1 ölçeğine geri yükleyin:

func _on_bounds_changed(_rid: RID, bounds: Vector3) -> void:
    var uniform_scale: float = min(bounds.x, bounds.y, bounds.z)
    content_root.scale = Vector3.ONE * uniform_scale

func _on_bounds_mode_changed(
    _rid: RID, bounds_mode: OpenXRSpatialContainerState.BoundsMode
) -> void:
    if bounds_mode == OpenXRSpatialContainerState.IMMERSIVE:
        content_root.scale = Vector3.ONE

Sınırlı ve yoğun içerik modları arasında geçiş yapma

Sınırlı bir 3D hacim ile tam ekran etkileyici görünüm arasında geçiş yapmak için request_main_spatial_container_bounds_mode öğesini OpenXRSpatialContainerState.BOUNDED veya OpenXRSpatialContainerState.IMMERSIVE ile çağırın:

# Request transitioning to immersive mode (or pass BOUNDED to return)
OpenXRSpatialContainerExtension.request_main_spatial_container_bounds_mode(
    OpenXRSpatialContainerState.IMMERSIVE
)

Aşağıdaki kaynakları da incelemenizi öneririz:

• Spatial Containers ile geliştirme yapma
• XR izinlerini anlama
• Mevcut bir Godot XR projesine Android XR desteği ekleme

OpenXR™ ve OpenXR logosu, The Khronos Group Inc. şirketine ait ticari markalardır ve Çin, Avrupa Birliği, Japonya ve Birleşik Krallık'ta ticari marka olarak tescillidir.