Libellé

Un composant (component) Label affiche une portion de texte à l’écran, dans l’espace de jeu. Par défaut, il est trié et dessiné avec tous les sprites et les éléments graphiques à base de tuiles. Le composant possède un ensemble de propriétés qui déterminent le rendu du texte. L’interface graphique de Defold prend en charge le texte, mais il peut être délicat de placer des éléments d’interface graphique dans le monde de jeu (game world). Les libellés facilitent cette tâche.

Création d’un libellé

Pour créer un composant Label, faites un clic droit sur l’objet de jeu (game object) et sélectionnez Add Component ▸ Label.

(Si vous souhaitez instancier plusieurs libellés à partir du même modèle, vous pouvez aussi créer un nouveau fichier de composant Label : faites un clic droit sur un dossier dans le navigateur Assets et sélectionnez New... ▸ Label, puis ajoutez le fichier en tant que composant aux objets de jeu de votre choix)

Définissez la propriété Font sur la police que vous souhaitez utiliser et veillez à définir la propriété Material sur un matériau correspondant au type de police :

Polices vectorielles et émojis en couleur

Pour utiliser une police Vector, suivez la configuration des polices vectorielles, affectez la ressource .font à la propriété Font du Label et définissez son Material sur /builtins/fonts/label-vector.material. Utilisez Font Size pour contrôler la taille affichée.

Pour les émojis en couleur, effectuez également la configuration de la police de repli COLRv1 et de sa mise en bundle. L’exemple ci-dessous suppose un Label d’identifiant label et un script sur le même objet de jeu. Laissez le champ Text du Label vide pour n’afficher le message qu’une fois ses glyphes prêts :

function init(self)
    local text = "Hello 😀 🍎 🚀"
    local font_resource = go.get("#label", "font")
    -- Add the fallback once for this shared font resource.
    font.add_font(font_resource, "/fonts/NotoColorEmoji-Regular.ttf")
    font.prewarm_text(font_resource, text, function(self, request_id, result, err)
        if result then
            go.set("#label", "text", text)
        else
            print("Could not prepare label text:", err)
        end
    end)
end

Les lettres ordinaires utilisent la police d’origine, et les émojis utilisent la police couleur ajoutée. Si d’autres Labels ou nœuds de texte GUI partagent cette ressource de police, initialisez la police de repli à un seul endroit et réutilisez-la.

Propriétés du libellé

Outre les propriétés Id, Position, Rotation et Scale, les propriétés suivantes sont propres au composant :

Text

Le contenu textuel du libellé.

Size

La taille du rectangle englobant du texte. Si Line Break est activée, la largeur indique à quel endroit le texte doit passer à la ligne.

Color

La couleur du texte.

Outline

La couleur du contour.

Shadow

La couleur de l’ombre.

Leading

Un facteur d’échelle pour l’interligne. Une valeur de 0 supprime l’interligne. La valeur par défaut est 1.

Tracking

Un facteur d’échelle pour l’espacement entre les lettres. La valeur par défaut est 0.

Pivot

Le pivot du texte. Utilisez cette propriété pour modifier l’alignement du texte (voir ci-dessous).

Blend Mode

Le mode de fusion à utiliser pour le rendu du libellé.

Line Break

L’alignement du texte suit le réglage du pivot et l’activation de cette propriété permet au texte de s’étendre sur plusieurs lignes. La largeur du composant détermine l’endroit où le texte passe à la ligne. Notez que le texte doit contenir une espace pour pouvoir passer à la ligne.

Font

La ressource de police à utiliser pour ce libellé.

Material

Le matériau à utiliser pour le rendu de ce libellé. Sélectionnez un matériau correspondant au mode ou à la source de la police (Bitmap, SDF, Vector ou BMFont). Consultez Matériaux des polices pour les matériaux Label intégrés correspondants.

Modes de fusion

La propriété Blend Mode définit la façon dont les éléments graphiques du composant (component) doivent être fusionnés avec ceux qui se trouvent derrière lui. Voici les modes de fusion disponibles et leur calcul :

Alpha

Fusion normale : src.a * src.rgb + (1 - src.a) * dst.rgb

Add

Éclaircit l’arrière-plan avec les valeurs de couleur des pixels correspondants du composant : src.rgb + dst.rgb

Multiply

Assombrit l’arrière-plan avec les valeurs des pixels correspondants du composant : src.rgb * dst.rgb

Screen

Inverse de Multiply. Éclaircit l’arrière-plan et les valeurs des pixels correspondants du composant : src.rgb - dst.rgb * dst.rgb

Pivot et alignement

La propriété Pivot vous permet de modifier le mode d’alignement du texte.

Centré

Si le pivot est défini sur Center, North ou South, le texte est centré.

À gauche

Si le pivot est défini sur l’un des modes West, le texte est aligné à gauche.

À droite

Si le pivot est défini sur l’un des modes East, le texte est aligné à droite.

Manipulation à l’exécution

Vous pouvez manipuler les libellés à l’exécution en récupérant et en définissant leur texte ainsi que leurs diverses autres propriétés.

text

Le contenu textuel du label (string). Accessible avec go.get() et go.set().

color

La couleur du libellé (vector4)

outline

La couleur du contour du libellé (vector4)

shadow

La couleur de l’ombre du libellé (vector4)

scale

L’échelle du libellé, soit un number pour une mise à l’échelle uniforme, soit un vector3 pour une mise à l’échelle distincte sur chaque axe.

size

La taille du libellé (vector3)

function init(self)
    -- Set the text of the "my_label" component in the same game object
    -- as this script.
    go.set("#my_label", "text", "New text")
    local text = go.get("#my_label", "text")
    print(text) -- New text
end

function init(self)
    -- Set the color of the "my_label" component in the same game object
    -- as this script. Color is a RGBA value stored in a vector4.
    local grey = vmath.vector4(0.5, 0.5, 0.5, 1.0)
    go.set("#my_label", "color", grey)

    -- ...and remove the outline, by setting its alpha to 0...
    go.set("#my_label", "outline.w", 0)

    -- ...and scale it x2 along x axis.
    local scale_x = go.get("#my_label", "scale.x")
    go.set("#my_label", "scale.x", scale_x * 2)
end

Configuration du projet

Le fichier game.project comporte quelques paramètres du projet liés aux libellés.