Animation d'interface / tweens | Documentation

Dans l'animation, le tweening est le processus de génération de frames intermédiaires entre deux points clés dans une séquence. Lors de la conception d'une interface utilisateur, vous pouvez utiliser le tweening pour faire passer en douceur un GuiObject d'un état à un autre, comme :

Augmenter en douceur la taille d'un bouton lorsqu'un utilisateur le sélectionne.
Faire glisser les menus de l'interface utilisateur sur et hors des bords de l'écran.
Animer progressivement une barre de santé entre deux largeurs lorsque l'utilisateur reçoit un bonus de santé.

Tweens pour une seule propriété

Position

Pour tweener la position d'un GuiObject :

Définissez le AnchorPoint de l'objet.
Déterminez les coordonnées UDim2 pour la position cible de l'objet, en utilisant les paramètres scale de UDim2 au lieu des valeurs de pixels exactes afin que l'objet se déplace vers le centre exact de l'écran.
Passez un TweenInfo et la position cible à TweenService:Create().
Jouez le tween avec Tween:Play().

Le code suivant déplace un ImageLabel dans un ScreenGui vers le centre exact de l'écran :

UI Tween - Position
local TweenService = game:GetService("TweenService")
local Players = game:GetService("Players")

local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
local ScreenGui = PlayerGui:WaitForChild("ScreenGui")
local object = ScreenGui:WaitForChild("ImageLabel")

object.AnchorPoint = Vector2.new(0.5, 0.5)

local targetPosition = UDim2.new(0.5, 0, 0.5, 0)

local tweenInfo = TweenInfo.new(2)
local tween = TweenService:Create(object, tweenInfo, {Position = targetPosition})

tween:Play()

Taille

Pour tweener la taille d'un GuiObject :

Déterminez les coordonnées UDim2 pour la taille cible de l'objet, en utilisant les paramètres scale de UDim2 au lieu des valeurs de pixels exactes afin que l'objet se redimensionne à un pourcentage relatif de la taille de l'écran.
Attachez un UIAspectRatioConstraint à l'objet pour maintenir son rapport d'aspect conçu lors du tweening.
Passez un TweenInfo et la taille cible à TweenService:Create().
Jouez le tween avec Tween:Play().

Le code suivant redimensionne un ImageLabel dans un ScreenGui à 40 % de la largeur ou de la hauteur de l'écran (selon ce qui est le plus petit) depuis le point d'ancrage central de l'objet :

UI Tween - Size
local TweenService = game:GetService("TweenService")
local Players = game:GetService("Players")

local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
local ScreenGui = PlayerGui:WaitForChild("ScreenGui")
local object = ScreenGui:WaitForChild("ImageLabel")

object.AnchorPoint = Vector2.new(0.5, 0.5)

local aspectRatioConstraint = Instance.new("UIAspectRatioConstraint")
aspectRatioConstraint.Parent = object

local targetSize = UDim2.new(0.4, 0, 0.4, 0)

local tweenInfo = TweenInfo.new(2)
local tween = TweenService:Create(object, tweenInfo, {Size = targetSize})

tween:Play()

Rotation

Pour tweener la rotation d'un GuiObject :

Définissez le AnchorPoint pour l'objet à faire tourner.
Déterminez la Rotation cible pour l'objet.
Passez un TweenInfo et la rotation cible à TweenService:Create().
Jouez le tween avec Tween:Play().

UI Tween - Size
local TweenService = game:GetService("TweenService")
local Players = game:GetService("Players")

local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
local ScreenGui = PlayerGui:WaitForChild("ScreenGui")
local object = ScreenGui:WaitForChild("ImageLabel")

object.AnchorPoint = Vector2.new(0.5, 0.5)

local targetRotation = 45

local tweenInfo = TweenInfo.new(2)
local tween = TweenService:Create(object, tweenInfo, {Rotation = targetRotation})

tween:Play()

Transparence

Plusieurs propriétés contrôlent la transparence de l'interface utilisateur, selon le type d'objet. Vous pouvez tweener chacune de ces propriétés individuellement ou combinées à travers un tween multi-propriété. Alternativement, vous pouvez tweener la transparence globale d'un objet en le plaçant à l'intérieur d'un CanvasGroup et en tweenant la GroupTransparency du groupe.

Objet UI	Propriétés
Frame	BackgroundTransparency
TextLabel	BackgroundTransparency, TextTransparency, TextStrokeTransparency
TextButton	BackgroundTransparency, TextTransparency, TextStrokeTransparency
ImageLabel	BackgroundTransparency, ImageTransparency
ImageButton	BackgroundTransparency, ImageTransparency

En tant qu'alternative moderne à TextLabel.TextStrokeTransparency et TextButton.TextStrokeTransparency, vous pouvez tweener la transparence du contour sur un objet UIStroke comme décrit dans Stroke.

UI Tween - Image Transparency
local TweenService = game:GetService("TweenService")
local Players = game:GetService("Players")

local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
local ScreenGui = PlayerGui:WaitForChild("ScreenGui")
local object = ScreenGui:WaitForChild("ImageLabel")

local targetTransparency = 0.8

local tweenInfo = TweenInfo.new(2)
local tween = TweenService:Create(object, tweenInfo, {ImageTransparency = targetTransparency})

tween:Play()

UI Tween - Canvas Group Transparency
local TweenService = game:GetService("TweenService")
local Players = game:GetService("Players")

local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
local ScreenGui = PlayerGui:WaitForChild("ScreenGui")
local canvasGroup = ScreenGui:WaitForChild("CanvasGroup")

local targetTransparency = 0.8

local tweenInfo = TweenInfo.new(2)
local tween = TweenService:Create(canvasGroup, tweenInfo, {GroupTransparency = targetTransparency})

tween:Play()

Couleur

Plusieurs propriétés contrôlent la couleur de l'interface utilisateur, selon le type d'objet. Vous pouvez tweener chacune de ces propriétés individuellement ou combinées à travers un tween multi-propriété. Alternativement, vous pouvez tweener la couleur globale d'un objet en le plaçant à l'intérieur d'un CanvasGroup et en tweenant la GroupColor3 du groupe.

Objet UI	Propriétés
Frame	BackgroundColor3, BorderColor3
TextLabel	BackgroundColor3, BorderColor3, TextColor3, TextStrokeColor3
TextButton	BackgroundColor3, BorderColor3, TextColor3, TextStrokeColor3
ImageLabel	BackgroundColor3, BorderColor3, ImageColor3
ImageButton	BackgroundColor3, BorderColor3, ImageColor3

En tant qu'alternative moderne à GuiObject.BorderColor3, TextLabel.TextStrokeColor3 et TextButton.TextStrokeColor3, vous pouvez tweener la couleur du contour sur un objet UIStroke comme décrit dans Stroke.

UI Tween - Image Color
local TweenService = game:GetService("TweenService")
local Players = game:GetService("Players")

local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
local ScreenGui = PlayerGui:WaitForChild("ScreenGui")
local object = ScreenGui:WaitForChild("ImageLabel")

local targetColor = Color3.fromRGB(255, 0, 0)

local tweenInfo = TweenInfo.new(2)
local tween = TweenService:Create(object, tweenInfo, {ImageColor3 = targetColor})

tween:Play()

UI Tween - Canvas Group Color
local TweenService = game:GetService("TweenService")
local Players = game:GetService("Players")

local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
local ScreenGui = PlayerGui:WaitForChild("ScreenGui")
local canvasGroup = ScreenGui:WaitForChild("CanvasGroup")

local targetColor = Color3.fromRGB(255, 0, 0)

local tweenInfo = TweenInfo.new(2)
local tween = TweenService:Create(canvasGroup, tweenInfo, {GroupColor3 = targetColor})

tween:Play()

Contours

Plusieurs propriétés contrôlent les bordures de l'interface utilisateur, selon le type d'objet.

Objet UI	Propriétés
Frame	BorderSizePixel, BorderColor3
TextLabel	BorderSizePixel, BorderColor3, TextStrokeColor3, TextStrokeTransparency
TextButton	BorderSizePixel, BorderColor3, TextStrokeColor3, TextStrokeTransparency
ImageLabel	BorderSizePixel, BorderColor3
ImageButton	BorderSizePixel, BorderColor3

Alternativement, vous pouvez appliquer un enfant de UIStroke et tweener son épaisseur, sa couleur, et/ou sa transparence.

Objet UI	Propriétés
UIStroke	Color, Thickness, Transparency

UI Tween - UIStroke Color & Thickness
local TweenService = game:GetService("TweenService")
local Players = game:GetService("Players")

local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
local ScreenGui = PlayerGui:WaitForChild("ScreenGui")
local object = ScreenGui:WaitForChild("TextLabel")

local stroke = Instance.new("UIStroke")
stroke.Color = Color3.fromRGB(255, 255, 255)
stroke.Thickness = 5
stroke.Parent = object

local targetColor = Color3.fromRGB(255, 0, 0)
local targetThickness = 10

local tweenInfo = TweenInfo.new(2)
local tween = TweenService:Create(stroke, tweenInfo, {Color = targetColor, Thickness = targetThickness})

tween:Play()

Tweens multi-propriétés

Vous pouvez combiner n'importe quel des tweens pour une seule propriété en des tweens plus complexes en passant plusieurs propriétés cibles à TweenService:Create(), par exemple position + rotation ou taille + transparence.

UI Tween - Position & Rotation
local TweenService = game:GetService("TweenService")
local Players = game:GetService("Players")

local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
local ScreenGui = PlayerGui:WaitForChild("ScreenGui")
local object = ScreenGui:WaitForChild("ImageLabel")

object.AnchorPoint = Vector2.new(0.5, 0.5)

local targetPosition = UDim2.new(0.5, 0, 0.5, 0)
local targetRotation = 45

local tweenInfo = TweenInfo.new(2)
local tween = TweenService:Create(object, tweenInfo, {Position = targetPosition, Rotation = targetRotation})

tween:Play()

UI Tween - Size & Transparency
local TweenService = game:GetService("TweenService")
local Players = game:GetService("Players")

local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
local ScreenGui = PlayerGui:WaitForChild("ScreenGui")
local object = ScreenGui:WaitForChild("ImageLabel")

object.AnchorPoint = Vector2.new(0.5, 0.5)

local aspectRatioConstraint = Instance.new("UIAspectRatioConstraint")
aspectRatioConstraint.Parent = object

local targetSize = UDim2.new(0.4, 0, 0.4, 0)
local targetTransparency = 0.8

local tweenInfo = TweenInfo.new(2)
local tween = TweenService:Create(object, tweenInfo, {Size = targetSize, ImageTransparency = targetTransparency})

tween:Play()

Séquences de tweens

Vous pouvez enchaîner des animations d'interface utilisateur pour qu'elles se produisent l'une après l'autre en jouant des tweens subséquents à la suite de l'événement Completed du tween précédent. Par exemple, le script suivant déplace un objet au centre de l'écran, puis le fait tourner de 45°.

UI Tween Sequence
local TweenService = game:GetService("TweenService")
local Players = game:GetService("Players")

local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
local ScreenGui = PlayerGui:WaitForChild("ScreenGui")
local object = ScreenGui:WaitForChild("ImageLabel")

object.AnchorPoint = Vector2.new(0.5, 0.5)

local targetPosition = UDim2.new(0.5, 0, 0.5, 0)
local targetRotation = 45

local tweenInfo = TweenInfo.new(2)
local positionTween = TweenService:Create(object, tweenInfo, {Position = targetPosition})
local rotationTween = TweenService:Create(object, tweenInfo, {Rotation = targetRotation})

-- Jouez d'abord le tween de position
positionTween:Play()

-- Jouez le tween de rotation à la fin du tween de position
positionTween.Completed:Connect(function()
	rotationTween:Play()
end)

Transitions de style

Cette fonctionnalité est actuellement en beta. Activez-la via Fichier ⟩ Fonctionnalités Bêta ⟩ Transitions de Style.

Les objets UI peuvent également être animés à travers des transitions de style, comparables aux transitions CSS, où une ou plusieurs propriétés UI sont tweenées à travers des définitions de StyleRule. Consultez le guide sur l'Éditeur de Styles pour plus de détails.

Règle d'état stylé final dans l'Éditeur de Styles.

Options d'assouplissement

En utilisant les options d'assouplissement de TweenInfo, vous pouvez contrôler le style et la direction de l'assouplissement des animations UI.

Style

Enum.EasingStyle définit le taux d'interpolation du début à la fin. Par défaut, le style d'assouplissement est défini sur Enum.EasingStyle.Quad.

Style	Description
Linéaire	Se déplace à une vitesse constante.
Sinusoidal	La vitesse est déterminée par une onde sinusoïdale pour un mouvement d'assouplissement doux.
Quad	Semblable à Sinusoidal mais avec une courbe légèrement plus acérée basée sur l'interpolation quadratique.
Cubique	Semblable à Quad mais avec une courbe légèrement plus acérée basée sur l'interpolation cubique.
Quartique	Semblable à Cubique mais avec une courbe encore plus acérée basée sur l'interpolation quartique.
Quintique	Semblable à Quartique mais avec une courbe encore plus acérée basée sur l'interpolation quintique.
Exponentielle	La courbe la plus acérée basée sur l'interpolation exponentielle.
Circulaire	Suit un arc circulaire, de sorte que l'accélération est plus soudaine et la décélération plus progressive par rapport à Quint ou Exponentielle.
Retour	Dépasser légèrement la cible, puis revenir en place.
Rebond	Rebondit plusieurs fois en arrière après avoir atteint la cible, avant de finalement se stabiliser.
Élastique	Se déplace comme s'il était attaché à un élastique, dépassant la cible plusieurs fois.

Easing Style - Cubic
local tweenInfo = TweenInfo.new(2, Enum.EasingStyle.Cubic)
local tween = TweenService:Create(object, tweenInfo, {Rotation = 45})

Direction

Enum.EasingDirection définit comment l'assouplissement s'applique à un objet, avec un défaut de Sortie. Notez qu'un tween avec un style d'assouplissement Linéaire n'est pas affecté, car l'interpolation linéaire est constante du début à la fin.

Direction	Description
In	Le style d'assouplissement s'applique dans une direction vers l'avant.
Sortie	Le style d'assouplissement s'applique dans une direction inverse.
InOut	Le style d'assouplissement s'applique vers l'avant pour la première moitié et en arrière pour la seconde moitié.

Easing direction - InOut
local tweenInfo = TweenInfo.new(2, Enum.EasingStyle.Cubic, Enum.EasingDirection.InOut)
local tween = TweenService:Create(object, tweenInfo, {Rotation = 45})

Effet dactylographie sur le texte

Vous pouvez facilement améliorer l'interface utilisateur basée sur le texte, telle que les bannières de scène, les instructions aux joueurs et les invites, avec des effets animés. L'effet "dactylographie" est idéal pour TextLabels qui racontent une histoire, sortent des dialogues de PNJ, etc.

Créez un nouveau ModuleScript dans ReplicatedStorage.
Renommez le nouveau script AnimateUI.

Collez le code suivant dans le script :

ModuleScript - AnimateUI
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")

local SOURCE_LOCALE = "en"
local translator = nil

local AnimateUI = {}

function AnimateUI.loadTranslator()
	pcall(function()
		translator = LocalizationService:GetTranslatorForPlayerAsync(Players.LocalPlayer)
	end)
	if not translator then
		pcall(function()
			translator = LocalizationService:GetTranslatorForLocaleAsync(SOURCE_LOCALE)
		end)
	end
end

function AnimateUI.typeWrite(guiObject, text, delayBetweenChars)
	guiObject.Visible = true
	guiObject.AutoLocalize = false
	local displayText = text

	-- Traduire le texte si possible
	if translator then
		displayText = translator:Translate(guiObject, text)
	end

	-- Remplacer les balises de saut de ligne afin que la boucle des graphemes ne manque pas ces caractères
	displayText = displayText:gsub("<br%s*/>", "\n")
 	-- Supprimer les balises RichText car l'animation caractère par caractère cassera les balises
	displayText = displayText:gsub("<[^<>]->", "")

	-- Définir le texte traduit/modifié sur le parent
	guiObject.Text = displayText

	local index = 0
	for first, last in utf8.graphemes(displayText) do
		index += 1
		guiObject.MaxVisibleGraphemes = index
		task.wait(delayBetweenChars)
	end
end

return AnimateUI

Si la langue source de votre expérience n'est pas l'anglais ("en"), changez le code de langue pour SOURCE_LOCALE pour correspondre à la langue source dans les paramètres de localisation.

Créez un TextLabel à un endroit approprié, tel qu'à l'intérieur d'un ScreenGui parenté à StarterGui.

Insérez un nouveau LocalScript comme enfant direct de l'étiquette et collez le code suivant. Notez que chaque message est affiché en appelant AnimateUI.typeWrite() avec des paramètres pour l'objet parent, la chaîne à afficher, et le délai entre les caractères.

LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local AnimateUI = require(ReplicatedStorage:WaitForChild("AnimateUI"))

local label = script.Parent

-- Charger le traducteur si l'expérience est localisée
--AnimateUI.loadTranslator()

local message1 = [[Derrière cette porte se trouve le<br /><font size="46" color="rgb(255,50,25)">Grand Zorgoth...</font> <font size="40">🗡</font>]]
AnimateUI.typeWrite(label, message1, 0.05)

task.wait(1)

local message2 = [[...qui règne dans ce donjon <font color="rgb(255,200,50)">sans défi !</font> <font size="30">😈</font>]]
AnimateUI.typeWrite(label, message2, 0.05)