הוספת תמיכה ב-Android XR לפרויקט Godot XR קיים

מכשירי XR שמתאימים לשימוש
ההנחיות האלה יעזרו לכם ליצור חוויות למכשירי XR מהסוגים הבאים.
מידע על סוגי מכשירי XR →
משקפי XR
משקפי XR חוטיים
מידע על סוגי מכשירי XR →

אם יש לכם פרויקט XR קיים ב-Godot, אתם יכולים להוסיף תמיכה ב-Android XR בלי להתחיל פרויקט חדש ונפרד. חלק מהשלבים נדרשים לכל הפרויקטים, ואחרים הם אופציונליים ותלויים בתכונות ה-XR שבהן נעשה שימוש בפרויקט. במהלך השלבים, הוספנו קישורים לכמה פרויקטים של קוד פתוח ב-Godot XR שנוספה להם תמיכה ב-Android XR, יחד עם בקשות רלוונטיות למשיכת קוד שמציגות את השינויים שנדרשים כדי להפעיל תכונות מסוימות.

שלבים שחובה לבצע בכל הפרויקטים

חשוב לבצע את השלבים בנושאים הבאים, לא משנה באילו סוגים של תכונות XR הפרויקט שלכם תומך. לאחר מכן, כדאי לעיין בתכונות שמפורטות ברשימת השלבים האופציונליים כדי לבדוק אם הפרויקט דורש עבודה נוספת.

עדכון של Godot ושל Godot OpenXR Vendors Plugin

כדי לעדכן את הפרויקט לגרסאות הנדרשות האחרונות ולהגדיר את הגדרות הפרויקט ל-Android XR:

  1. מעדכנים את גרסת Godot לגרסה 4.6.2 ואילך. אם אתם צריכים עזרה נוספת בפרויקט, תוכלו לעיין בתיעוד בנושא מעבר לגרסה חדשה.

  2. מורידים את Godot OpenXR Vendors Plugin בגרסה 5.1 ומעלה מ-Asset Store, מ-Asset Library או מהמאגר ב-GitHub.

  3. הגדרת ההגדרות של הפרויקט ל-Android XR:

    1. מוסיפים הגדרות קבועות מראש לייצוא ל-Android XR.
    2. מפעילים את האפשרות Use Gradle Build (שימוש ב-Gradle Build).

    מפעילים את

    1. בקטע XR Features, בוחרים באפשרות OpenXR בשדה XR Mode, ומסמנים את התיבה Enable AndroidXR Plugin.

    מגדירים את האפשרויות ב

הוספת תמיכה במעקב ידיים

יכול להיות שיהיו בקרים זמינים, אבל שיטת הקלט העיקרית באוזניות ובמשקפיים של Android XR היא מעקב ידיים. אם אפשר, כדאי להוסיף תמיכה במעקב אחרי תנועות ידיים לפרויקט Godot.

הוספת תמיכה במעקב ידיים: הגדרת הגדרות הפרויקט

קודם, צריך לבצע את השלבים הבאים כדי להגדיר את הגדרות הפרויקט להפעלת מעקב אחרי הידיים והתוספים הקשורים של OpenXR.

  1. פותחים את ההגדרות של הפרויקט ועוברים אל כללי > XR > OpenXR.

  2. בקטע תוספים, בוחרים באפשרות מעקב אחרי תנועות הידיים ובאפשרות פרופיל אינטראקציה עם הידיים.

    מגדירים את האפשרויות ב

  3. בקטע Extensions (תוספים), מחפשים את קטע המשנה Meta ובוחרים באפשרויות Hand Tracking Mesh (רשת מעקב אחרי הידיים) ו-Hand Tracking Aim (מעקב אחרי הידיים לצורך כיוון).

    מגדירים את האפשרויות ב

הוספת תמיכה במעקב ידיים: הוספה והגדרה של צמתי בקרה

במקום לשנות באופן דינמי את הצמתים הקיימים של XRController3D למעקב תנועות הידיים, מוסיפים צמתים של בקר למעקב ולהצגה של מודלים של הידיים, וגם לטיפול בקלט מהתוסף Hand Tracking Aim:

  1. מוסיפים עוד שלושה צמתים XRController3D לצומת XROrigin3D.

    1. נותנים לאחד מהם את השם HandTrackingLeft ומגדירים את מאפיין המעקב ל-/user/hand_tracker/left.
    2. נותנים שם אחר ל-HandTrackingRight ומגדירים את מאפיין ה-tracker ל-/user/hand_tracker/right.
    3. נותנים שם ל-"HandTrackingAimLeft" האחרון, ומגדירים את מאפיין ה-tracker ל-/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 Action Map (מיפוי פעולות OpenXR) בחלק התחתון של העורך.
  2. כדי למנוע בעיות תאימות עם בקרי Galaxy XR, צריך למחוק את הפרופיל Simple Controller.
  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.

שימוש בפונקציות של XR Tools יחד עם מעקב ידיים

הרבה פרויקטים של Godot XR משתמשים ב-Godot XR Tools, כולל חלק מהפרויקטים של קוד פתוח שמקושרים בדף הזה. כדי שחלק מהפונקציות של 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 של OpenXR XRInterface לערך 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. פותחים את ההגדרות של הפרויקט ועוברים אל כללי > XR > OpenXR.

  2. בקטע Androidxr, בוחרים באפשרות Light Estimation.

    מגדירים את האפשרויות ב

  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.