Ajouter la prise en charge d'Android XR à un projet Godot XR existant

Appareils XR concernés
Ces conseils vous aideront à créer des expériences pour ces types d'appareils XR.
En savoir plus sur les types d'appareils XR →
Casques XR
Lunettes XR filaires
En savoir plus sur les types d'appareils XR →

Si vous disposez déjà d'un projet XR dans Godot, vous pouvez ajouter la prise en charge d'Android XR sans avoir à créer un projet distinct. Certaines étapes sont obligatoires pour tous les projets, tandis que d'autres sont facultatives en fonction des fonctionnalités XR utilisées par votre projet. Tout au long de ces étapes, nous avons inclus des liens vers plusieurs projets Godot XR Open Source qui ont ajouté la prise en charge d'Android XR, ainsi que des requêtes d'extraction pertinentes qui présentent les modifications nécessaires pour activer certaines fonctionnalités.

Étapes obligatoires pour tous les projets

Suivez les étapes décrites dans les rubriques suivantes, quels que soient les types de fonctionnalités XR compatibles avec votre projet. Ensuite, examinez les fonctionnalités décrites dans la liste des étapes facultatives pour déterminer si votre projet nécessite des modifications supplémentaires.

Mettre à jour Godot et le plug-in Godot OpenXR Vendors

Suivez ces étapes pour mettre à jour votre projet vers les dernières versions requises et configurer les paramètres de votre projet pour Android XR :

  1. Mettez à jour votre version de Godot vers la version 4.6.2 ou ultérieure. Consultez la documentation sur la migration vers une nouvelle version si vous avez besoin d'aide supplémentaire pour votre projet.

  2. Téléchargez le plug-in Godot OpenXR Vendors version 5.1 ou ultérieure depuis l'Asset Store, l'Asset Library ou le dépôt sur GitHub.

  3. Configurez les paramètres de votre projet pour Android XR :

    1. Ajoutez un préréglage d'exportation pour Android XR.
    2. Activez l'option Use Gradle Build (Utiliser la compilation Gradle).

    Activez le

    1. Dans la section XR Features (Fonctionnalités XR), sélectionnez OpenXR pour le XR Mode, puis sélectionnez Enable AndroidXR Plugin (Activer le plug-in AndroidXR).

    Configurez les options dans le

Ajouter la prise en charge du suivi des mains

Bien que des manettes puissent être disponibles, la principale méthode d'entrée sur les casques et lunettes Android XR est le suivi des mains. Si possible, vous devez ajouter la prise en charge du suivi des mains à votre projet Godot.

Ajouter la prise en charge du suivi des mains : configurer les paramètres du projet

Tout d'abord, suivez ces étapes pour configurer les paramètres de votre projet afin d'activer le suivi des mains et ses extensions OpenXR associées.

  1. Ouvrez les paramètres de votre projet et accédez à General > XR > OpenXR (Général > XR > OpenXR).

  2. Dans la section Extensions, sélectionnez Hand Tracking (Suivi des mains) et Hand Interaction Profile (Profil d'interaction avec les mains).

    Configurez les options dans le

  3. Recherchez la sous-section Meta dans la section Extensions, puis sélectionnez Hand Tracking Mesh (Mesh de suivi des mains) et Hand Tracking Aim (Visée du suivi des mains).

    Configurez les options dans le

Ajouter la prise en charge du suivi des mains : ajouter et configurer des nœuds de manette

Plutôt que de modifier dynamiquement les nœuds XRController3D existants pour le suivi des mains, ajoutez des nœuds de manette pour suivre et afficher les modèles de mains, ainsi que pour gérer les entrées de l'extension Hand Tracking Aim (Visée du suivi des mains) :

  1. Ajoutez trois nœuds XRController3D supplémentaires à votre nœud XROrigin3D.

    1. Nommez-en un "HandTrackingLeft" et définissez la propriété du tracker sur /user/hand_tracker/left.
    2. Nommez-en un autre "HandTrackingRight" et définissez la propriété du tracker sur /user/hand_tracker/right.
    3. Nommez le dernier "HandTrackingAimLeft" et définissez la propriété du tracker sur /user/fbhandaim/left.

    Si les nœuds XRController3D d'origine de votre projet étaient nommés "XRController3D_left" et "XRController3D_right", votre scène se présenterait comme suit :

    À quoi votre scène pourrait ressembler après l'ajout des nœuds de contrôleur.

  2. Connectez le signal tracking_changed sur HandTrackingLeft et HandTrackingRight à des fonctions individuelles qui mettent à jour la visibilité des trackers de manette correspondants (XRController3D_left et XRController3D_right dans l'exemple précédent).

    Par exemple, la fonction connectée au signal sur HandTrackingLeft peut se présenter comme suit :

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

  3. Activez la propriété Show When Tracked (Afficher lors du suivi) sur les nœuds de manette de suivi des mains.

    Votre projet peut désormais basculer visuellement entre les modèles de manette et les modèles de suivi des mains, selon que l'utilisateur utilise le suivi des mains ou des manettes.

  4. Ajoutez des nœuds OpenXRFbHandTrackingMesh en tant qu'enfants à vos nœuds de manette de suivi des mains.

  5. Ajoutez des nœuds XRHandModifier3D en tant qu'enfants à ces nœuds OpenXRFbHandTrackingMesh, en vous assurant que la propriété Hand Tracker (Tracker de mains) correcte est définie, afin d'appliquer les données de suivi des mains en temps réel aux modèles.

    À quoi votre scène peut ressembler après avoir ajouté les nœuds enfants à vos nœuds de contrôleur.

Ajouter la prise en charge du suivi des mains : configurer un profil d'interaction avec les mains sur la carte d'actions OpenXR

Ensuite, vous allez configurer le profil Hand Interaction (Interaction avec les mains) sur la OpenXR Action Map (Carte d'actions OpenXR) :

  1. Ouvrez le menu OpenXR Action Map (Carte d'actions OpenXR) en bas de l'éditeur.
  2. Supprimez le profil Simple Controller (Manette simple) pour éviter les problèmes de compatibilité avec les manettes Galaxy XR.
  3. Cliquez sur Add Profile (Ajouter un profil), sélectionnez Hand Interaction (Interaction avec les mains), puis cliquez sur OK.

  4. Associez ce profil à un ou plusieurs ensembles d'actions comme vous le souhaitez.

En fonction des exigences de votre application, vous pouvez également ajuster la façon dont votre application gère les entrées utilisateur avec le suivi des mains.

Ajouter la prise en charge du suivi des mains : configurer un geste de menu pour Android XR

Enfin, vous pouvez implémenter un geste de menu pour Android XR. Une icône s'affiche lorsque la main gauche du joueur est dans la bonne position pour effectuer le geste de menu, et le menu s'affiche ou se masque lorsque l'utilisateur effectue le geste. Pour cela, vous utiliserez le nœud HandTrackingAimLeft que vous avez ajouté précédemment.

  1. Ajoutez un quad à panneau d'affichage au nœud de suivi des mains gauche, qui affiche une icône de votre choix (voir le nœud MenuIcon dans l'image suivante à partir des nœuds de manette que vous avez ajoutés précédemment).

    À quoi votre scène peut ressembler après avoir ajouté les nœuds enfants à vos nœuds de contrôleur.

  2. Connectez-vous aux signaux button_pressed et button_released sur HandTrackingAimLeft à des fonctions comme celle-ci :

    @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

Étapes facultatives pour certaines fonctionnalités

Une fois les étapes obligatoires pour votre projet terminées, vous pouvez décider si vous devez effectuer des modifications supplémentaires pour certaines fonctionnalités, en fonction des exigences et des capacités de votre application. Pour en savoir plus sur chacune de ces fonctionnalités facultatives, consultez les sections suivantes.

Enregistrer les pincements comme des appuis sur un bouton

Dans Android XR, le pincement est utilisé pour de nombreuses actions système fondamentales, telles que la sélection d'éléments, le défilement, le déplacement ou le redimensionnement de fenêtres, ainsi que le déplacement d'éléments d'interface utilisateur ou d'objets dans un espace 2D et 3D. Pour vous aligner sur ces modèles et offrir une expérience utilisateur cohérente, votre application doit enregistrer les pincements de la même manière que les appuis sur un bouton d'une manette lorsque vous utilisez le suivi des mains.

Pour configurer votre application de cette manière, utilisez les valeurs flottantes fournies par le profil d'interaction avec les mains que vous avez créé pour créer une action virtuelle :

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)

Points clés concernant le code

  • Vérifie si la valeur float est supérieure ou inférieure à des seuils spécifiques dans les signaux XRController3D input_float_changed.
  • Crée une action virtuelle appelée pinch_pressed.

Utiliser les fonctions XR Tools avec le suivi des mains

De nombreux projets Godot XR utilisent Godot XR Tools, y compris certains des projets Open Source liés à cette page. Pour que certaines fonctions XR Tools fonctionnent, telles que FunctionPointer pour les interactions de menu, vous aurez besoin de code supplémentaire pour échanger l'action qu'elle recherche lorsque l'utilisateur passe au suivi des mains.

Par exemple, lorsque vous utilisez FunctionPointer pour les interactions de menu, mettez à jour la active_button_action propriété vers l'action de suivi des mains en fonction du tracking_changed signal des XRController3D nœuds pour le suivi des mains (ces nœuds étaient HandTrackingLeft et HandTrackingRight dans les étapes de configuration du suivi des mains précédentes).

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

Points clés concernant le code

Utiliser le suivi des mains avec la locomotion artificielle

Si votre projet utilise la locomotion artificielle, la prise en charge du suivi des mains est toujours possible. Par exemple, vous pouvez créer un système de mouvement qui permet aux joueurs de tracer des chemins à parcourir avec un geste, ou vous pouvez leur permettre de lever et d'abaisser les mains pour accélérer, avec des gestes supplémentaires pour sauter, grimper et glisser.

Le Museum of All Things utilise la locomotion artificielle à l'aide des joysticks des manettes. La locomotion par suivi des mains a été implémentée en ajoutant des "joysticks virtuels" que le joueur déclenche en pinçant l'air et en déplaçant sa main dans la direction dans laquelle il souhaite que le joystick se déplace.

Voici quelques-uns des principaux points à retenir de la demande d'extraction qui a implémenté cette prise en charge :

  • Une scène XRVirtualThumbstick est instanciée lorsqu'un pincement est détecté.
  • Lorsque le pincement est maintenu, la distance et la direction relatives par rapport à l'emplacement de pincement d'origine sont converties en Vector2 et mappées virtuellement à l'entrée normale du joystick.
  • Un retour visuel de cette entrée est également fourni au joueur sous la forme de deux maillages quad à panneau d'affichage, illustrant la position du joystick.

Vous pouvez essayer une approche similaire pour que votre code de locomotion existant basé sur le joystick fonctionne avec un minimum de modifications. Toutefois, votre projet peut toujours nécessiter une solution de locomotion personnalisée pour le suivi des mains.

Ajouter la prise en charge du mode passthrough

Vous pouvez ajouter la prise en charge du mode passthrough à votre application afin que vos utilisateurs puissent voir leur environnement réel.

Pour ce faire, apportez les modifications de code suivantes à votre application :

  • Définissez le environment_blend_mode de l'OpenXR XRInterface sur XR_ENV_BLEND_MODE_ALPHA_BLEND.
  • Définissez le background_mode du nœud WorldEnvironment sur BG_COLOR.
  • Définissez le background_color du nœud WorldEnvironment sur n'importe quelle couleur entièrement transparente.
  • Définissez la propriété Viewport transparent_bg sur true.

Utiliser l'extension d'estimation de la lumière

Lorsque vous activez le mode passthrough, envisagez d'utiliser l'extension OpenXR d'estimation de la lumière Android XR. Cette extension ajuste les propriétés de WorldEnvironment et DirectionalLight3D pour mieux émuler l'éclairage de l'environnement réel d'un utilisateur. Les objets virtuels se fondent ainsi mieux dans les conditions d'éclairage réelles. Vous pouvez activer cette extension dans les paramètres de votre projet.

  1. Ouvrez les paramètres de votre projet et accédez à General > XR > OpenXR (Général > XR > OpenXR).

  2. Dans la section Androidxr, sélectionnez Light Estimation (Estimation de la lumière).

    Configurez les options dans le

  3. Ajoutez un nœud OpenXRAndroidLightEstimation à l'arborescence de votre scène et connectez-le à WorldEnvironment et DirectionalLight3D de votre scène.

    Options pour le

Exemple : activer ou désactiver le mode passthrough et l'estimation de la lumière

Le code suivant active ou désactive le mode passthrough et l'estimation de la lumière :

@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
Points clés concernant le code
  • Lorsque vous désactivez l'estimation de la lumière, la direction d'origine de DirectionalLight3D doit être restaurée manuellement.
  • Pour obtenir un exemple complet de projet utilisant le mode passthrough et l'estimation de la lumière, consultez Expedition to Blobotopia sur GitLab.