استخدام الحاويات المكانية في Godot

أجهزة XR المشمولة
تساعدك هذه الإرشادات في إنشاء تجارب لهذه الأنواع من أجهزة XR.
مزيد من المعلومات حول أنواع أجهزة XR →
سماعات الرأس بنظام الواقع الممتد
نظارات سلكية بنظام الواقع الممتد
مزيد من المعلومات حول أنواع أجهزة XR →

تتيح الحاويات المكانية لتطبيقك عرض محتوى OpenXR الثلاثي الأبعاد داخل مربّع إحاطة حجمي ثلاثي الأبعاد يديره النظام في "وضع المساحة الكاملة"، أو الانتقال أثناء التشغيل إلى تجربة ملء الشاشة غير المحدودة.

اتّبِع هذا الدليل لإعداد "الحاويات المكانية" واستخدامها في مشروعك.

حاويات مكانية متعددة تعمل في "وضع المساحة الكاملة" على Android XR
الشكل 1. حاويات مكانية في وضع "المساحة الكاملة"، بما في ذلك حاوية تضاريس ثلاثية الأبعاد مثبّتة على الأرض ونموذج ثلاثي الأبعاد مقترن بواجهة مستخدم ثنائية الأبعاد

طريقة عمل "الحاويات المكانية"

عند تفعيل الحاوية المكانية في إعدادات مشروعك:

  • يتم وضع المشهد الثلاثي الأبعاد النشط بالكامل داخل حاوية مكانية أساسية واحدة تتوسّط نقطة بداية المشهد (0, 0, 0). ليس عليك وضع علامات على عُقد Node3D الفردية أو تخصيصها لوضعها داخل الحاوية.
  • يتم تشغيل تطبيقك في "وضع المساحة الكاملة" المُدار باستخدام وضع الحدود (Bounded أو Immersive) وأبعاد الحدود الأولية التي تم ضبطها في إعدادات مشروعك. في "الوضع المحدود"، يقتطع النظام تلقائيًا أي هندسة ثلاثية الأبعاد في المشهد تمتد خارج أبعاد مربّع الإحاطة.
  • يوفّر نظام Android XR تلقائيًا عناصر تحكّم في النوافذ ليتمكّن المستخدم من الإمساك بالحاوية المحدودة ونقلها وإعادة تحديد موضعها في المساحة الثلاثية الأبعاد، أو تصغيرها وإغلاقها. أثناء التشغيل، يمكن لتطبيقك تغيير حجم الحاوية والتبديل بين الوضع المحدود (OpenXRSpatialContainerState.BOUNDED) ووضع ملء الشاشة المجسم (OpenXRSpatialContainerState.IMMERSIVE)، والتفاعل مع التغييرات في الحدود والحالة باستخدام العنصر الفردي OpenXRSpatialContainerExtension.

المتطلبات الأساسية

قبل البدء، تأكَّد من أنّ بيئة التطوير وجهاز الاختبار يستوفيان المتطلبات التالية:

تفعيل ميزة "الحاويات المكانية" في إعدادات المشروع

اضبط إعدادات مشروعك لتفعيل OpenXR و"الحاويات المكانية" وأذونات التشغيل التلقائية و"الرؤية المحيطية" الممزوجة بألفا:

  1. افتح Project (المشروع) > Project Settings (إعدادات المشروع).
  2. فعِّل مفتاح التبديل الإعدادات المتقدّمة في أعلى يسار نافذة إعدادات المشروع.
  3. انتقِل إلى إعدادات عامة > الواقع الممتد > برامج التظليل واختَر مفعَّل.
  4. انتقِل إلى General > XR > OpenXR (الإعدادات العامة > الواقع الممتد > OpenXR) واضبط الإعدادات التالية:
    • اختَر مفعَّل لتفعيل OpenXR للمشروع.
    • اضبط وضع دمج البيئة (Environment Blend Mode) على دمج ألفا (Alpha Blend).
  5. ضِمن OpenXR أيضًا، انتقِل إلى قسم الإضافات (Extensions) واضبط الإعدادات التالية:
    • اختَر طلب أذونات التشغيل تلقائيًا (Automatically Request Runtime Permissions) ليطلب تطبيقك من المستخدم تلقائيًا عند بدء التشغيل أي أذونات XR مُعلَن عنها في ملف بيان Android.
    • ضمن الفقرة الفرعية الحاوية المكانية، اختَر مفعَّلة.
    • اضبط وضع الحدود على محدود لتشغيل التطبيق في مربّع حدود ثلاثي الأبعاد، أو مجسم لتشغيله في وضع مجسم بملء الشاشة.
    • اضبط الحدود على أبعاد العرض والارتفاع والعمق الأولية بالمتر، مثل Vector3(1.0, 1.0, 1.0).
  6. انتقِل إلى General (الإعدادات العامة) > Rendering (العرض) > Viewport (إطار العرض) واختَر Transparent Background (خلفية شفافة).

ضبط إعدادات التصدير والأذونات و"وضع المساحة الكاملة" في Android

بعد ذلك، اضبط الإعدادات المسبقة لتصدير Android والأذونات ووضع بدء النشاط لتشغيل تطبيقك في "وضع المساحة الكاملة" مع تفعيل "الحاويات المكانية".

ضبط الإعدادات المسبقة لتصدير Android

  1. انتقِل إلى Project > Export...‎ (المشروع > تصدير...) واختَر الإعداد المُسبَق للتصدير إلى Android.

  2. ضمن إصدار Gradle‏ (Gradle Build)، اختَر استخدام إصدار Gradle‏ (Use Gradle Build) واضبط الحد الأدنى لحزمة تطوير البرامج (Min SDK) على 34 أو إصدار أحدث.

    تفعيل

  3. ضمن ميزات الواقع الممتد (XR Features)، اضبط وضع الواقع الممتد (XR Mode) على OpenXR واختَر تفعيل المكوّن الإضافي لـ AndroidXR (Enable AndroidXR Plugin).

    اضبط الخيارات في

  4. ضِمن ميزات Android XR، اختَر استخدام الميزات التجريبية.

إضافة أذونات فهم المشهد لقفل الأرضية

لا يتطلّب إنشاء حاوية مكانية أساسية وعرضها أذونات تشغيل خطيرة (وتتم إضافة android.permission.HEAD_TRACKING إلى ملف البيان تلقائيًا عند تفعيل استخدام الميزات التجريبية). ومع ذلك، إذا كان تطبيقك يستخدم ميزات فهم المشهد، مثل قفل حاوية مكانية وتثبيتها على الأرضية المادية، يجب أن يصرّح تطبيقك عن إذن android.permission.SCENE_UNDERSTANDING_COARSE ويطلبه أثناء التشغيل.

يمكنك الاطّلاع على مقالة فهم أذونات XR للحصول على تفاصيل حول أذونات Android XR. إذا كان تطبيقك يستخدم ميزة تثبيت الأرضية أو فهم المشهد، عليك الإفصاح عن الإذن التالي وطلبه android.permission.SCENE_UNDERSTANDING_COARSE:

  1. انتقِل إلى المشروع > تصدير... (Project > Export...) > Android، انتقِل إلى الأذونات > الأذونات المخصّصة وأضِف android.permission.SCENE_UNDERSTANDING_COARSE.

  2. عند اختيار طلب أذونات التشغيل تلقائيًا في إعدادات المشروع > الإعدادات العامة > XR > OpenXR > الإضافات، يطلب تطبيقك الإذن تلقائيًا عند بدء تشغيل OpenXR. إذا كنت بحاجة إلى طلب الإذن يدويًا في GDScript بدلاً من ذلك، يمكنك استدعاء OS.request_permission():

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

ضبط وضع "مساحات كاملة"

لا تتيح الحاويات المكانية في Android XR سوى "وضع المساحة الكاملة" (XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED). تأكَّد من أنّ نشاط Android يعلن عن XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED في نموذج الإصدار المخصّص (android/build/AndroidManifest.xml، المثبَّت باستخدام المشروع > تثبيت نموذج إصدار Android...):

<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

تتيح فئة OpenXRSpatialContainerExtension الأحادية وفئة OpenXRSpatialContainerState استخدام إضافتَي XR_EXT_spatial_container وXR_EXT_spatial_container_self_rendering في لغة GDScript. أثناء التشغيل، استخدِم OpenXRSpatialContainerExtension لفحص حالة الحاوية المكانية الرئيسية وحدودها، والاستماع إلى إشارات الحاوية، وطلب الانتقال بين وضع BOUNDED (مربّع إحاطة ثلاثي الأبعاد) ووضع IMMERSIVE (عرض ملء الشاشة بدون حدود).

الربط بإشارات Spatial Container

يُرجى التحقّق من OpenXRSpatialContainerExtension.is_enabled() للتأكّد من أنّ إضافة Spatial Container متوافقة ونشطة على الجهاز الحالي، والاتصال بإشارات حدود الحاوية وحالتها في _ready().

يُصدر OpenXRSpatialContainerExtension إشارات الحالة التالية للحاوية المكانية:

  • spatial_container_visibility_changed: يتم إرسالها مع (spatial_container, is_visible) عند عرض الحاوية (true) أو إخفائها (false). يمكنك إيقاف الصور المتحركة أو الصوت أو تحديثات المحاكاة مؤقتًا عندما تكون قيمة is_visible هي false.
  • spatial_container_interactability_changed: يتم إرسالها مع (spatial_container, is_interactive) عندما تكتسب الحاوية (true) أو تفقد (false) تركيز إدخال المستخدم. تفعيل أو إيقاف ميزة "التمييز التفاعلي" ومعالجة الإدخال عند تغيير التركيز
  • ‫spatial_container_bounds_mode_changed: يتم إرسالها مع (spatial_container, bounds_mode) عندما تبدّل الحاوية بين OpenXRSpatialContainerState.BOUNDED و OpenXRSpatialContainerState.IMMERSIVE. يمكنك تفعيل أو إيقاف العناصر المرئية في البيئة (مثل الصور البانورامية أو ميزة "الرؤية من خلال النظارة") وعناصر التحكّم في واجهة المستخدم الخاصة بالوضع.
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

تغيير حجم المحتوى الثلاثي الأبعاد ليتناسب مع حدود الحاوية

عند استخدام وضع BOUNDED، يمكنك تغيير حجم المحتوى الثلاثي الأبعاد بشكل موحّد حسب أصغر بُعد في bounds للحفاظ على نسبة العرض إلى الارتفاع وملاءمة المحتوى دائمًا للجانب الأصغر من الحاوية. عند الانتقال إلى وضع "IMMERSIVE"، يجب استعادة المشهد إلى مقياس 1:1:

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

التبديل بين وضعَي "محدود" و"مجسم"

يمكنك استدعاء request_main_spatial_container_bounds_mode باستخدام OpenXRSpatialContainerState.BOUNDED أو OpenXRSpatialContainerState.IMMERSIVE للتبديل بين عرض ثلاثي الأبعاد محدود وعرض غامر بملء الشاشة:

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

انظر أيضًا

‫OpenXR™‎ وشعار OpenXR هما علامتان تجاريتان تملكهما شركة The Khronos Group Inc. ‎ ومسجَّلتان كعلامة تجارية في الصين والاتحاد الأوروبي واليابان والمملكة المتحدة.