Modèles de debounce | Documentation

Un modèle de debounce est une technique de codage qui empêche une fonction de s'exécuter trop de fois ou une entrée de déclencher plusieurs fois. Les scénarios de script suivants illustrent le debounce comme une bonne pratique.

Détecter les collisions

Supposons que vous souhaitiez créer une pièce de piège dangereux qui inflige 10 dégâts lorsqu'elle est touchée. Une première implémentation pourrait utiliser une connexion de base BasePart.Touched et une fonction damagePlayer comme ceci :

Script - Dommages au joueur
local part = script.Parent

local function damagePlayer(otherPart)
	print(part.Name .. " a percuté " .. otherPart.Name)

	local humanoid = otherPart.Parent:FindFirstChildWhichIsA("Humanoid")
	if humanoid then
		humanoid.Health -= 10  -- Réduire la santé du joueur
	end
end

part.Touched:Connect(damagePlayer)

Bien que cela semble logique à première vue, les tests montreront que l'événement Touched se déclenche plusieurs fois rapidement en fonction de collisions physiques subtiles.

Pour éviter de causer des dégâts excessifs lors du premier contact, vous pouvez ajouter un système de debounce qui impose une période de recharge sur les dommages à l'aide d'un attribut d'instance.

Script - Dommages au joueur avec debounce
local part = script.Parent

local RESET_TIME = 1

local function damagePlayer(otherPart)
	print(part.Name .. " a percuté " .. otherPart.Name)

	local humanoid = otherPart.Parent:FindFirstChildWhichIsA("Humanoid")
	if humanoid then
		if not part:GetAttribute("Touched") then
			part:SetAttribute("Touched", true)  -- Définir l'attribut sur vrai
			humanoid.Health -= 10  -- Réduire la santé du joueur
			task.wait(RESET_TIME)  -- Attendre la durée de réinitialisation
			part:SetAttribute("Touched", false)  -- Réinitialiser l'attribut
		end
	end
end

part.Touched:Connect(damagePlayer)

Déclencher des sons

Le debounce est également utile lorsque vous travaillez avec des effets sonores, comme jouer un son lorsque deux pièces entrent en collision (Touched), ou jouer un son lors de l'événement Activated lorsqu'un utilisateur interagit avec un bouton à l'écran. Dans les deux cas, appeler Sound:Play() commence la lecture depuis le début de sa piste et — sans un système de debounce — le son peut être joué plusieurs fois rapidement.

Pour empêcher le chevauchement des sons, vous pouvez utiliser le debounce avec la propriété IsPlaying de l'objet Sound :

Script - Jouer un son de collision avec debounce
local projectile = script.Parent

local function playSound()
	-- Trouver le son enfant sur la pièce
	local sound = projectile:FindFirstChild("Impact")
	-- Jouer le son seulement s'il ne joue pas déjà
	if sound and not sound.IsPlaying then
		sound:Play()
	end
end

projectile.Touched:Connect(playSound)

Script - Jouer clic de bouton avec debounce
local button = script.Parent

local function onButtonActivated()
	-- Trouver le son enfant sur le bouton
	local sound = button:FindFirstChild("Click")
	-- Jouer le son seulement s'il ne joue pas déjà
	if sound and not sound.IsPlaying then
		sound:Play()
	end
end

button.Activated:Connect(onButtonActivated)

Effets de ramassage

Les jeux incluent souvent des objets collectables dans le monde 3D tels que des trousses de soins, des paquets de munitions, et plus encore. Si vous concevez ces objets pour rester dans le monde afin que les joueurs puissent les ramasser encore et encore, un temps de "recharge" devrait être ajouté avant que l'objet ne se rafraîchisse et ne se réactive.

Similaire à détecter les collisions, vous pouvez gérer l'état de debounce avec un attribut d'instance, et visualiser la période de recharge en changeant la Transparency de la pièce.

Script - Ramassage de santé avec debounce
local part = script.Parent
part.Anchored = true
part.CanCollide = false

local COOLDOWN_TIME = 5

local function healPlayer(otherPart)
	local humanoid = otherPart.Parent:FindFirstChildWhichIsA("Humanoid")
	if humanoid then
		if not part:GetAttribute("CoolingDown") then
			part:SetAttribute("CoolingDown", true)  -- Définir l'attribut sur vrai
			humanoid.Health += 25  -- Augmenter la santé du joueur
			part.Transparency = 0.75  -- Rendre la pièce semi-transparente pour indiquer l'état de recharge
			task.wait(COOLDOWN_TIME)  -- Attendre la durée de recharge
			part.Transparency = 0  -- Réinitialiser la pièce pour qu'elle soit complètement opaque
			part:SetAttribute("CoolingDown", false)  -- Réinitialiser l'attribut
		end
	end
end

part.Touched:Connect(healPlayer)

Ce concept de recharge peut être appliqué à d'autres scénarios également, comme créer un temps de "rechargement" pour un lance-roquettes afin de limiter à quelle fréquence les joueurs peuvent tirer des roquettes.