إضافة إمكانية استخدام Android XR إلى مشروع Godot XR حالي

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

إذا كان لديك مشروع XR حالي في Godot، يمكنك إضافة إمكانية استخدام Android XR بدون بدء مشروع جديد منفصل. بعض الخطوات مطلوبة لجميع المشاريع، بينما تكون خطوات أخرى اختيارية حسب ميزات الواقع الممتد التي يستخدمها مشروعك. في جميع الخطوات، أدرجنا روابط تؤدي إلى مشاريع Godot XR متعددة مفتوحة المصدر أتاحت إمكانية استخدام Android XR، بالإضافة إلى طلبات سحب ذات صلة تعرض التغييرات المطلوبة لتفعيل ميزات معيّنة.

الخطوات المطلوبة لجميع المشاريع

أكمِل الخطوات الواردة في المواضيع التالية بغض النظر عن أنواع ميزات الواقع الممتد التي يدعمها مشروعك. بعد ذلك، راجِع الميزات الموضّحة في قائمة الخطوات الاختيارية لتحديد ما إذا كان مشروعك يتطلّب عملاً إضافيًا.

تحديث Godot والمكوّن الإضافي Godot OpenXR Vendors Plugin

اتّبِع الخطوات التالية لتعديل مشروعك إلى أحدث الإصدارات المطلوبة وإعداد إعدادات مشروعك لنظام Android XR:

  1. يجب تحديث إصدار Godot إلى 4.6.2 أو إصدار أحدث. راجِع المستندات حول نقل البيانات إلى إصدار جديد إذا كنت بحاجة إلى مساعدة إضافية في مشروعك.

  2. نزِّل الإصدار 5.1 أو إصدارًا أحدث من Godot OpenXR Vendors Plugin من Asset Store أو Asset Library أو المستودع على GitHub.

  3. اضبط إعدادات مشروعك على Android XR باتّباع الخطوات التالية:

    1. أضِف إعدادًا مُسبقًا للتصدير إلى Android XR.
    2. فعِّل استخدام إصدار Gradle.

    فعِّل

    1. في قسم ميزات الواقع الممتد (XR Features)، اختَر OpenXR في وضع الواقع الممتد (XR Mode)، ثم اختَر تفعيل المكوّن الإضافي AndroidXR (Enable AndroidXR Plugin).

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

إتاحة ميزة "تتبُّع اليد"

على الرغم من إمكانية توفّر أدوات التحكّم، فإنّ طريقة الإدخال الأساسية على سمّاعات الرأس بنظام الواقع الممتد ونظارات بنظام الواقع الممتد التي تعمل بنظام Android XR هي تتبُّع حركة اليد. إذا أمكن، يجب إضافة ميزة تتبُّع اليد إلى مشروع Godot.

إتاحة استخدام ميزة "تتبُّع اليد": ضبط إعدادات المشروع

أولاً، اتّبِع الخطوات التالية لإعداد إعدادات مشروعك من أجل تفعيل تتبُّع اليدين وإضافات OpenXR ذات الصلة.

  1. افتح إعدادات مشروعك وانتقِل إلى الإعدادات العامة > الواقع الممتد > OpenXR.

  2. في قسم الإضافات، اختَر تتبُّع حركة اليد وملف تعريف التفاعل باليد.

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

  3. ابحث عن القسم الفرعي Meta في قسم الإضافات، ثم اختَر شبكة تتبُّع اليد واستهداف تتبُّع اليد.

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

إتاحة تتبّع اليد: إضافة عُقد وحدة التحكّم وضبطها

بدلاً من تعديل عقد XRController3D الحالية بشكل ديناميكي لتتبُّع اليد، أضِف عقد التحكّم لتتبُّع وعرض نماذج اليد، بالإضافة إلى معالجة الإدخال من إضافة Hand Tracking Aim:

  1. أضِف ثلاث عُقد XRController3D إضافية إلى عقدة XROrigin3D.

    1. سمِّ أحدهما "HandTrackingLeft"، واضبط سمة أداة التتبُّع على /user/hand_tracker/left.
    2. أضِف عنصرًا آخر باسم "HandTrackingRight"، واضبط سمة أداة التتبُّع على /user/hand_tracker/right.
    3. أدخِل اسمًا لآخر عنصر "HandTrackingAimLeft"، واضبط سمة أداة التتبُّع على /user/fbhandaim/left.

    إذا كانت أسماء عقد XRController3D الأصلية في مشروعك هي "XRController3D_left" و"XRController3D_right"، سيبدو المشهد على النحو التالي:

    الشكل الذي قد يبدو عليه المشهد بعد إضافة عُقد وحدة التحكّم

  2. اربط الإشارة tracking_changed في HandTrackingLeft وHandTrackingRight بوظائف فردية تعدّل إمكانية ظهور أدوات تتبُّع وحدات التحكّم المقابلة (XRController3D_left وXRController3D_right في المثال السابق).

    على سبيل المثال، قد تبدو الدالة المرتبطة بالإشارة في HandTrackingLeft كما يلي:

    func _on_hand_tracking_left_hand_tracking_changed(tracking):
    $XROrigin3D/XRController3D_left.visible = not tracking

  3. فعِّل السمة Show When Tracked في عقد عناصر التحكّم الخاصة بتتبُّع حركة اليد.

    يمكن لمشروعك الآن التبديل بشكل مرئي بين نماذج أدوات التحكّم ونماذج تتبُّع اليد، وذلك حسب ما إذا كان المستخدم يستعمل أدوات التحكّم أو ميزة تتبُّع اليد.

  4. أضِف بعض عُقد OpenXRFbHandTrackingMesh كعُقد فرعية إلى عُقد وحدة التحكّم في تتبُّع اليد.

  5. أضِف عُقد XRHandModifier3D كعُقد فرعية إلى عُقد OpenXRFbHandTrackingMesh هذه، مع التأكّد من ضبط السمة الصحيحة Hand Tracker، لتطبيق بيانات تتبُّع اليد في الوقت الفعلي على النماذج.

    شكل المشهد بعد إضافة العُقد الفرعية إلى عُقد التحكّم

إضافة دعم لتتبُّع حركة اليد: إعداد ملف تعريف "التفاعل باستخدام اليد" على "خريطة إجراءات OpenXR"

بعد ذلك، عليك إعداد ملف التفاعل باليد في خريطة إجراءات OpenXR:

  1. افتح قائمة خريطة إجراءات OpenXR في أسفل أداة التعديل.
  2. احذف ملف Simple Controller الشخصي لتجنُّب مشاكل التوافق مع وحدات التحكّم في Galaxy XR.
  3. انقر على إضافة ملف شخصي، واختَر التفاعل باليد، ثم انقر على موافق.

  4. اربط هذا الملف الشخصي بمجموعة إجراءات واحدة أو أكثر بالطريقة التي تريدها.

بناءً على متطلبات تطبيقك، قد تحتاج أيضًا إلى تعديل طريقة تعامل تطبيقك مع بيانات أدخلها المستخدم باستخدام ميزة تتبُّع اليد.

إتاحة تتبُّع حركة اليد: إعداد إيماءة قائمة في Android XR

أخيرًا، يمكنك تنفيذ إيماءة قائمة لنظام Android XR. يعرض هذا الخيار رمزًا عندما تكون يد اللاعب اليسرى في الموضع الصحيح لتنفيذ إيماءة القائمة، بالإضافة إلى عرض القائمة أو إخفائها عندما ينفّذ المستخدم الإيماءة. ستستخدم عقدة HandTrackingAimLeft التي أضفتها سابقًا للتعامل مع هذا الإجراء.

  1. أضِف لوحة إعلانية رباعية إلى عقدة تتبُّع اليد اليسرى تعرض رمزًا اخترته (راجِع عقدة MenuIcon في الصورة التالية من عقد التحكّم التي أضفتها سابقًا).

    شكل المشهد بعد إضافة العُقد الفرعية إلى عُقد التحكّم

  2. اربط الإشارتين button_pressed وbutton_released في HandTrackingAimLeft بدوال مثل هذه:

    @onready var menu_icon: MeshInstance3D = $XROrigin3D/HandTrackingLeft/MenuIcon

func _on_hand_tracking_aim_left_button_pressed(p_name):
  if p_name == "menu_pressed":
toggle_menu()
  elif p_name == "menu_gesture":
    if OS.has_feature("androidxr"):
      menu_icon.visible = true

func _on_hand_tracking_aim_left_button_released(p_name):
  if p_name == "menu_gesture":
    menu_icon.visible = false

خطوات اختيارية لبعض الميزات

بعد إكمال الخطوات المطلوبة لمشروعك، يمكنك تحديد ما إذا كنت بحاجة إلى تنفيذ أعمال إضافية لميزات معيّنة، وذلك حسب متطلبات تطبيقك وإمكاناته. لمزيد من المعلومات حول كل ميزة من هذه الميزات الاختيارية، راجِع الأقسام التالية.

تسجيل الضغطات كضغطات على الأزرار

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

لضبط تطبيقك بهذه الطريقة، استخدِم قيم الفاصلة العائمة التي يوفّرها ملف تعريف "التفاعل باليد" الذي أنشأته لإنشاء إجراء افتراضي:

const PRESSED_THRESHOLD := 0.8
const RELEASED_THRESHOLD := 0.6

@onready var left_controller: XRController3D = $XROrigin/XRController3D_left

func _on_xr_controller_3d_left_input_float_changed(p_name: String, value: float):
    if p_name == "pinch":
        var xr_tracker = XRServer.get_tracker(left_controller.tracker)
        if _left_hand_pinching:
            if value < RELEASED_THRESHOLD:
                _left_hand_pinching = false
                xr_tracker.set_input("pinch_pressed", false)
        else:
            if value > PRESSED_THRESHOLD:
                _left_hand_pinching = true
                xr_tracker.set_input("pinch_pressed", true)

النقاط الرئيسية حول الرمز

  • تتحقّق هذه السمة مما إذا كانت قيمة float أكبر من أو أقل من حدود معيّنة في إشارات XRController3D input_float_changed.
  • تنشئ هذه السمة إجراءً افتراضيًا باسم pinch_pressed.

استخدام وظائف "أدوات الواقع الممتد" مع ميزة "تتبّع اليد"

تستفيد العديد من مشاريع Godot XR من أدوات Godot XR، بما في ذلك بعض المشاريع مفتوحة المصدر المرتبطة في هذه الصفحة. لكي تعمل بعض وظائف XR Tools، مثل FunctionPointer للتفاعل مع القوائم، ستحتاج إلى بعض الرموز الإضافية لتبديل الإجراء الذي تبحث عنه عندما ينتقل المستخدم إلى تتبُّع اليد.

على سبيل المثال، عند استخدام FunctionPointer للتفاعل مع القوائم، عدِّل السمة active_button_action إلى إجراء تتبُّع اليد استنادًا إلى الإشارة tracking_changed لعُقد XRController3D الخاصة بتتبُّع اليد (كانت هذه العُقد HandTrackingLeft وHandTrackingRight في خطوات إعداد تتبُّع اليد السابقة).

const TRIGGER_POINTER_ACTION = "trigger_click"
const PINCH_POINTER_ACTION = "pinch_pressed"

@onready var func_point_left: XRToolsFunctionPointer = %FunctionPointerLeft

func _on_hand_tracking_left_tracking_changed(tracking: bool) -> void:
    if tracking:
        func_point_left.active_button_action = PINCH_POINTER_ACTION
else:
func_point_left.active_button_action = TRIGGER_POINTER_ACTION

النقاط الرئيسية حول الرمز

استخدام ميزة "تتبُّع اليد" مع ميزة "التنقّل الاصطناعي"

إذا كان مشروعك يستخدم التنقّل الاصطناعي، سيظل بإمكانك استخدام ميزة تتبُّع اليد. على سبيل المثال، يمكنك إنشاء نظام حركة يتيح للاعبين رسم مسارات للتنقّل باستخدام إيماءة، أو يمكنك السماح للاعبين بتحريك أيديهم للأعلى والأسفل للتسارع، مع إيماءات إضافية للقفز والتسلّق والانزلاق.

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

في ما يلي بعض النقاط الرئيسية التي يمكن استخلاصها من طلب السحب الذي نفّذ هذه الميزة:

  • يتم إنشاء مشهد XRVirtualThumbstick عند رصد عملية التصغير.
  • أثناء الضغط بإصبعين، يتم تحويل المسافة والاتجاه النسبيين من الموقع الأصلي للضغط بإصبعين إلى Vector2 ويتم ربطهما افتراضيًا بإدخال عصا التحكّم العادية.
  • يتم أيضًا تقديم ملاحظات مرئية للاعب بشأن هذا الإدخال في شكل شبكتَي رباعي الأضلاع معروضتَين على لوحة إعلانات، ما يوضّح موضع عصا التحكّم.

يمكنك تجربة أسلوب مشابه لجعل رمز التنقّل الحالي المستند إلى عصا التحكّم يعمل بأقل تغييرات ممكنة. ومع ذلك، قد يظل مشروعك يتطلب حلاً مخصصًا للتنقّل من أجل تتبّع اليد.

إضافة إمكانية استخدام ميزة "نقل البيانات"

يمكنك إضافة ميزة "المرور" إلى تطبيقك ليتمكّن المستخدمون من رؤية محيطهم الواقعي.

لإجراء ذلك في تطبيقك، أدخِل تغييرات الرمز البرمجي التالية:

  • اضبط environment_blend_mode في XRInterface OpenXR على XR_ENV_BLEND_MODE_ALPHA_BLEND.
  • اضبط background_mode لعقدة WorldEnvironment على BG_COLOR.
  • اضبط قيمة background_color لعقدة WorldEnvironment على أي لون شفاف تمامًا.
  • اضبط السمة Viewport transparent_bg على true.

استخدام إضافة "تقدير الإضاءة"

عند تفعيل ميزة "نقل البيانات"، ننصحك باستخدام إضافة Android XR Light Estimation OpenXR. يعدّل هذا الامتداد خصائص WorldEnvironment وDirectionalLight3D لمحاكاة إضاءة بيئة المستخدم الحقيقية بشكل أفضل، ما يتيح دمج العناصر الافتراضية بشكل أفضل مع ظروف الإضاءة في العالم الحقيقي. يمكنك تفعيل هذه الإضافة في إعدادات مشروعك.

  1. افتح إعدادات مشروعك وانتقِل إلى الإعدادات العامة > الواقع الممتد > OpenXR.

  2. في قسم Androidxr، اختَر تقدير الإضاءة.

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

  3. أضِف عقدة OpenXRAndroidLightEstimation إلى شجرة المشهد واربطها بالعقدتين WorldEnvironment وDirectionalLight3D في المشهد.

    خيارات

مثال: تفعيل ميزة "الرؤية المجسّمة" و"تقدير الإضاءة" أو إيقافهما

يؤدي الرمز البرمجي التالي إلى تفعيل أو إيقاف ميزة "نقل البيانات" وتقدير الإضاءة:

@onready var world_environment = $WorldEnvironment
@onready var directional_light = $DirectionalLight3D
@onready var directional_light_orig_transform: Transform3D = directional_light.transform

func set_passthrough_enabled(p_enabled: bool) -> void:
    var xr_interface = XRServer.find_interface("OpenXR")
    if xr_interface == null:
        return

    var supported_blend_modes = xr_interface.get_supported_environment_blend_modes()
    if not supported_blend_modes.has(XRInterface.XR_ENV_BLEND_MODE_ALPHA_BLEND):
        return

    # Passthrough
    if p_enabled:
        xr_interface.set_play_area_mode(XRInterface.XR_PLAY_AREA_STAGE)
        xr_interface.environment_blend_mode = XRInterface.XR_ENV_BLEND_MODE_ALPHA_BLEND
        world_environment.environment.background_mode = Environment.BG_COLOR
        world_environment.environment.background_color = Color(0.0, 0.0, 0.0, 0.0)
        get_viewport().transparent_bg = true
    else:
        xr_interface.set_play_area_mode(XRInterface.XR_PLAY_AREA_ROOMSCALE)
        xr_interface.environment_blend_mode = XRInterface.XR_ENV_BLEND_MODE_OPAQUE
        world_environment.environment.background_mode = Environment.BG_SKY
        get_viewport().transparent_bg = false

    # Light Estimation
    if OS.has_feature("androidxr"):
        var light_estimation = Engine.get_singleton("OpenXRAndroidLightEstimationExtension")
        if p_enabled and light_estimation.is_light_estimation_supported():
            light_estimation.start_light_estimation()
        elif light_estimation.is_light_estimation_started():
            light_estimation.stop_light_estimation()
            directional_light.transform = directional_light_orig_transform
النقاط الرئيسية حول الرمز
  • عند إيقاف تقدير الإضاءة، يجب استعادة الاتجاه الأصلي DirectionalLight3D يدويًا.
  • للاطّلاع على مثال كامل لمشروع يستخدم ميزة "الرؤية المجسّمة" و"تقدير الإضاءة"، يمكنك الانتقال إلى Expedition to Blobotopia على GitLab.