L'interface utilisateur (UI) constitue le canal de communication privilégié entre le joueur et l'univers du jeu. Au-delà de la simple transmission d'informations, elle définit l'ergonomie et l'immersion globale. Cocos propose une architecture UI robuste et flexible, couvrant l'ensemble des besoins, de l'affichage statique aux interactions complexes. Cette documentation explore les fondements du système UI de Cocos : composants de base, gestion intelligente de la mise en page et stratégies d'adaptation multi-résolution.

Les composants UI fondamentaux

Les éléments d'interface sont construits à partir de composants spécialisés. Chaque brique possède des propriétés distinctes adaptées à des scénarios d'interaction spécifiques.

Le composant Button (Bouton)

Le bouton est l'élément interactif par excellence. Il permet de déclencher des actions logiques tout en offrant un retour visuel à l'utilisateur.

• Transition : Définit la réaction visuelle lors du clic (Color Tint, Scale ou Sprite Swap). Le mode "Scale" est souvent privilégié pour simuler un effet de pression physique.
• Interactable : Un booléen contrôlant si le bouton est actif. Lorsqu'il est désactivé, il peut automatiquement passer en niveaux de gris via l'option "Enable Auto Gray Effect".
• Click Events : Liste de rappels (callbacks) liant l'événement de clic à une fonction dans un script.

// Exemple de gestion personnalisée d'un clic
onTriggerAction(event) {
    // Exécution de la logique métier
    this.initiateSequence();
    
    // Empêcher la propagation de l'événement aux nœuds parents
    event.stopPropagation();
}

Pour des interactions plus riches comme l'appui long, on utilise les événements tactiles du nœud :

// Détection d'un appui prolongé
let timerAppui = 0;
let estEnTrainDePresser = false;

this.node.on('touchstart', () => {
    estEnTrainDePresser = true;
    timerAppui = 0;
    this.schedule(() => {
        if (estEnTrainDePresser) {
            timerAppui += 0.1;
            if (timerAppui >= 1.5) { // Déclenchement après 1.5s
                this.onLongPressDetected();
                estEnTrainDePresser = false;
            }
        }
    }, 0.1);
});

this.node.on('touchend', () => { estEnTrainDePresser = false; });

Toggle (Interrupteur) et Slider (Curseur)

Le Toggle gère les états binaires (activé/désactivé). Regroupés dans un ToggleContainer, ils permettent de créer des menus à choix unique (boutons radio).

Le Slider permet de sélectionner une valeur dans un intervalle continu. Sa propriété progress varie de 0 à 1, ce qui nécessite souvent un mappage vers une valeur métier (comme le volume sonore de 0 à 100).

// Mappage de la valeur d'un curseur pour le volume
onVolumeAdjust(slider) {
    const niveau = Math.round(slider.progress * 100);
    this.labelVolume.string = `Volume: ${niveau}%`;
    this.audioEngine.setMasterVolume(slider.progress);
}

ProgressBar (Barre de progression)

Essentielle pour les barres de vie ou le chargement de ressources, la ProgressBar supporte plusieurs modes : Horizontal, Vertical et Radial (pour les temps de recharge de compétences par exemple).

Système de mise en page : Widget et Layout

Pour garantir que l'UI reste cohérente sur différents formats d'écran, Cocos s'appuie sur deux composants piliers.

Le composant Widget (Alignement)

Le Widget permet d'ancrer un nœud par rapport aux bords ou au centre de son parent. C'est l'outil principal pour l'UI adaptative.

• Align Mode : Définit la fréquence de mise à jour (ONCE, ON_WINDOW_RESIZE ou ALWAYS).
• Target : Par défaut le parent, mais peut être n'importe quel nœud de référence.

Le composant Layout (Disposition)

Le Layout organise automatiquement ses nœuds enfants selon une logique horizontale, verticale ou en grille (Grid).

• Resize Mode : "Children" permet au conteneur de s'ajuster à la taille des enfants, tandis que "Container" force les enfants à s'adapter à l'espace disponible.
• Padding et Spacing : Contrôlent respectivement les marges internes et l'espacement entre les éléments.

// Rafraîchissement manuel d'une liste dynamique
refreshDynamicList() {
    const conteneur = this.contentNode.getComponent(cc.Layout);
    // Après l'ajout de nouveaux éléments
    conteneur.updateLayout();
}

Adaptation Multi-résolution

La diversité des terminaux mobiles impose une stratégie d'affichage flexible.

Le Canevas (Canvas)

Le composent Canvas est la racine de l'espace UI. Il définit la Design Resolution (résolution de conception, ex: 1920x1080). Deux stratégies majeures coexistent :

• Fit Width : La largeur de l'UI correspond à celle de l'écran. Idéal pour les jeux à défilement vertical.
• Fit Height : La hauteur est priorisée. Recommandé pour les jeux horizontaux afin d'éviter les coupures sur les éléments d'action.

Composent FitScreen

Pour les éléments qui doivent couvrir tout l'écran indépendamment du ratio (comme une image de fond), on utilise une logique de redimensionnement spécifique ou le composant FitScreen. Il permet d'ignorer certaines contraintes du Canvas pour remplir l'espace visible, évitant ainsi les bandes noires sur les écrans très larges ou très longs.

// Ajustement pour les zones sécurisées (Safe Area) des smartphones modernes
applySafeArea() {
    const area = cc.sys.getSafeAreaInsets();
    const widget = this.mainUINode.getComponent(cc.Widget);
    if (widget) {
        widget.top = area.top;
        widget.bottom = area.bottom;
        widget.updateAlignment();
    }
}

Composants de contenu avancés

Deux autres composants sont omniprésents dans la création d'interfaces :

• Label : Supporte les polices système et TTF. Le mode "Shrink" est utile pour que le texte s'adapte automatiquement à la taille de son cadre.
• ScrollView : Permet de créer des zones défilantes (inventaires, classements). Pour optimiser les performances avec des centaines d'objets, il est conseillé d'implémenter un système de liste virtuelle qui ne génère que les éléments visibles.