Utiliser des conteneurs spatiaux dans Godot

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 →

En savoir plus sur les types d'appareils XR →

Les conteneurs spatiaux permettent à votre application d'afficher du contenu OpenXR 3D dans un cadre de délimitation volumétrique 3D géré par le système en mode Full Space, ou de passer à l'exécution à une expérience plein écran non limitée.

Suivez ce guide pour configurer et utiliser des conteneurs spatiaux dans votre projet.

Fonctionnement des conteneurs spatiaux

Lorsque vous activez le conteneur spatial dans les paramètres de votre projet :

• L'intégralité de votre scène 3D active est placée dans un seul conteneur spatial principal centré sur l'origine de la scène (0, 0, 0). Vous n'avez pas besoin d'ajouter de tag ni d'attribuer des nœuds Node3D individuels pour les placer dans le conteneur.
• Votre application se lance en mode Full Space géré à l'aide du mode de limites (Bounded ou Immersive) et des dimensions de limites initiales configurées dans les paramètres du projet. En mode délimité, le système découpe automatiquement toute géométrie 3D de votre scène qui dépasse les dimensions du cadre de délimitation.
• Par défaut, le système Android XR fournit des commandes de fenêtre permettant à l'utilisateur de saisir, de déplacer et de repositionner le conteneur délimité dans l'espace 3D, ou de le réduire et de le fermer. Au moment de l'exécution, votre application peut redimensionner le conteneur, basculer entre le mode limité (OpenXRSpatialContainerState.BOUNDED) et le mode immersif plein écran (OpenXRSpatialContainerState.IMMERSIVE), et réagir aux limites et aux changements d'état à l'aide du singleton OpenXRSpatialContainerExtension.

Prérequis

Avant de commencer, assurez-vous que votre environnement de développement et votre appareil cible répondent aux exigences suivantes :

• Version de Godot : Godot 4.8-dev ou version ultérieure.
• Configuration du projet : suivez toutes les étapes du guide de configuration du projet Godot Engine.
• Plug-in Godot OpenXR Vendors : installez la version 5.2 ou ultérieure du plug-in Godot OpenXR Vendors, qui permet d'utiliser des extensions spécifiques à Android XR.
• Appareil cible : un appareil Android XR compatible avec l'API spatiale de niveau 4 ou supérieur. Au moment de l'exécution, appelez OpenXRSpatialContainerExtension.is_enabled() pour vérifier si l'extension est disponible sur l'appareil.

Activer les conteneurs spatiaux dans les paramètres du projet

Configurez les paramètres de votre projet pour activer OpenXR, les conteneurs spatiaux, les autorisations d'exécution automatiques et le passthrough avec mélange alpha :

1. Ouvrez Project > Project Settings (Projet > Paramètres du projet).
2. Activez l'option Paramètres avancés en haut à droite de la fenêtre Paramètres du projet.
3. Accédez à Général > XR > Shaders, puis sélectionnez Activé.
4. Accédez à General > XR > OpenXR (Général > XR > OpenXR), puis configurez les paramètres suivants :
   • Sélectionnez Activé pour activer OpenXR pour le projet.
   • Définissez Environment Blend Mode (Mode de fusion de l'environnement) sur Alpha Blend (Fusion alpha).
5. Toujours sous OpenXR, accédez à la section Extensions et configurez les paramètres suivants :
   • Sélectionnez Automatically Request Runtime Permissions (Demander automatiquement les autorisations d'exécution) pour que votre application invite automatiquement l'utilisateur au démarrage à accorder les autorisations XR déclarées dans votre fichier manifeste Android.
   • Dans la sous-section Conteneur spatial, sélectionnez Activé.
   • Définissez Bounds Mode (Mode de délimitation) sur Bounded (Délimité) pour lancer l'application dans un cadre de délimitation 3D, ou sur Immersive (Immersif) pour la lancer en mode immersif plein écran.
   • Définissez Limites sur les dimensions initiales de largeur, de hauteur et de profondeur en mètres, par exemple Vector3(1.0, 1.0, 1.0).
6. Accédez à General > Rendering > Viewport (Général > Rendu > Fenêtre d'affichage), puis sélectionnez Transparent Background (Arrière-plan transparent).

Configurer l'exportation Android, les autorisations et le mode Full Space

Ensuite, configurez votre préréglage d'exportation Android, vos autorisations et votre mode de démarrage d'activité pour que votre application s'exécute en mode Full Space avec les conteneurs spatiaux activés.

Configurer le préréglage d'exportation Android

1. Accédez à Project > Export... (Projet > Exporter...), puis sélectionnez votre préréglage d'exportation Android.

2. Sous Gradle Build, sélectionnez Use Gradle Build (Utiliser Gradle Build) et définissez Min SDK (SDK minimal) sur 34 ou une version ultérieure.

   

3. Sous XR Features (Fonctionnalités XR), définissez XR Mode (Mode XR) sur OpenXR, puis sélectionnez Enable AndroidXR Plugin (Activer le plug-in AndroidXR).

   

4. Sous Android XR Features (Fonctionnalités Android XR), sélectionnez Use Experimental Features (Utiliser les fonctionnalités expérimentales).

Ajouter des autorisations de compréhension de la scène pour le verrouillage au sol

La création et l'affichage d'un conteneur spatial de base ne nécessitent pas d'autorisations d'exécution dangereuses (et android.permission.HEAD_TRACKING est ajouté automatiquement au fichier manifeste lorsque l'option Utiliser les fonctionnalités expérimentales est activée). Toutefois, si votre application utilise des fonctionnalités de compréhension de scène, telles que le verrouillage et l'ancrage d'un conteneur spatial au sol physique, elle doit déclarer et demander l'autorisation android.permission.SCENE_UNDERSTANDING_COARSE au moment de l'exécution.

Pour en savoir plus sur les autorisations Android XR, consultez Comprendre les autorisations pour la réalité XR. Si votre application utilise le verrouillage au sol ou la compréhension de la scène, déclarez et demandez android.permission.SCENE_UNDERSTANDING_COARSE :

1. Dans Projet > Exporter… > Android, accédez à Permissions > Custom Permissions (Autorisations > Autorisations personnalisées), puis ajoutez android.permission.SCENE_UNDERSTANDING_COARSE.

2. Lorsque vous sélectionnez Automatically Request Runtime Permissions (Demander automatiquement les autorisations d'exécution) dans Project Settings > General > XR > OpenXR > Extensions (Paramètres du projet > Général > XR > OpenXR > Extensions), votre application demande automatiquement l'autorisation au démarrage d'OpenXR. Si vous devez demander l'autorisation manuellement dans GDScript, appelez OS.request_permission() :

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

Configurer le mode Full Space

Les conteneurs spatiaux sur Android XR ne sont compatibles qu'avec le mode Full Space (XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED). Assurez-vous que votre activité Android déclare XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED dans votre modèle de compilation personnalisé (android/build/AndroidManifest.xml, installé à l'aide de Project > Install Android Build Template...) :

<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>

Utiliser des conteneurs spatiaux dans GDScript

Le singleton OpenXRSpatialContainerExtension et la classe OpenXRSpatialContainerState exposent les extensions XR_EXT_spatial_container et XR_EXT_spatial_container_self_rendering à GDScript. Au moment de l'exécution, utilisez OpenXRSpatialContainerExtension pour inspecter l'état et les limites du conteneur spatial principal, écouter les signaux du conteneur et demander des transitions entre le mode BOUNDED (un cadre de délimitation 3D) et le mode IMMERSIVE (une vue plein écran non limitée).

Se connecter aux signaux de conteneur spatial

Vérifiez OpenXRSpatialContainerExtension.is_enabled() pour vous assurer que l'extension Spatial Container est compatible et active sur l'appareil actuel, puis connectez-vous aux limites du conteneur et aux signaux d'état dans _ready().

OpenXRSpatialContainerExtension émet les signaux d'état suivants pour le conteneur spatial :

• spatial_container_visibility_changed : émis avec (spatial_container, is_visible) lorsque le conteneur est affiché (true) ou masqué (false). Mettez en pause les animations, l'audio ou les mises à jour de simulation lorsque is_visible est défini sur false.
• spatial_container_interactability_changed : émis avec (spatial_container, is_interactive) lorsque le conteneur gagne (true) ou perd (false) la sélection de l'utilisateur. Activez ou désactivez les mises en surbrillance interactives et la gestion des entrées lorsque la sélection change.
• spatial_container_bounds_mode_changed : émis avec (spatial_container, bounds_mode) lorsque le conteneur bascule entre OpenXRSpatialContainerState.BOUNDED et OpenXRSpatialContainerState.IMMERSIVE. Activer/Désactiver les visuels de l'environnement (comme les skybox ou le passthrough) et les commandes d'interface utilisateur spécifiques au mode.

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

Mettre à l'échelle le contenu 3D selon les limites du conteneur

En mode BOUNDED, mettez à l'échelle votre contenu 3D de manière uniforme en fonction de la plus petite dimension de bounds afin qu'il conserve son format et s'adapte toujours au plus petit côté du conteneur. Lorsque vous passez en mode IMMERSIVE, restaurez votre scène à l'échelle 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

Basculer entre les modes délimité et immersif

Appelez request_main_spatial_container_bounds_mode avec OpenXRSpatialContainerState.BOUNDED ou OpenXRSpatialContainerState.IMMERSIVE pour basculer entre un volume 3D délimité et une vue immersive en plein écran :

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

Voir aussi

• Créer avec des conteneurs spatiaux
• Comprendre les autorisations pour la XR
• Ajouter la compatibilité avec Android XR à un projet Godot XR existant

OpenXR™ et le logo OpenXR sont des marques appartenant à The Khronos Group Inc. et sont déposées en Chine, dans l'Union européenne, au Japon et au Royaume-Uni.