Padrões de Debounce | Documentação - Central de Criadores Roblox

Um padrão de debounce é uma técnica de codificação que impede que uma função seja executada muitas vezes ou que uma entrada cause múltiplas ativações. Os seguintes cenários de script ilustram o debounce como uma boa prática.

Detectar colisões

Suponha que você queira criar uma parte de armadilha perigosa que inflige 10 de dano ao ser tocada. Uma implementação inicial pode usar uma conexão básica BasePart.Touched e uma função damagePlayer assim:

Script - Dano ao Jogador
local part = script.Parent

local function damagePlayer(otherPart)
	print(part.Name .. " colidiu com " .. otherPart.Name)

	local humanoide = otherPart.Parent:FindFirstChildWhichIsA("Humanoid")
	if humanoide then
		humanoide.Health -= 10  -- Reduzir a saúde do jogador
	end
end

part.Touched:Connect(damagePlayer)

Embora lógico à primeira vista, os testes mostrarão que o evento Touched dispara múltiplas vezes em rápida sucessão com base em colisões físicas sutis.

Para evitar causar dano excessivo no contato inicial, você pode adicionar um sistema de debounce que impõe um período de espera no dano através de um atributo de instância.

Script - Dano ao Jogador Usando Debounce
local part = script.Parent

local RESET_TIME = 1

local function damagePlayer(otherPart)
	print(part.Name .. " colidiu com " .. otherPart.Name)

	local humanoide = otherPart.Parent:FindFirstChildWhichIsA("Humanoid")
	if humanoide then
		if not part:GetAttribute("Touched") then
			part:SetAttribute("Touched", true)  -- Definir atributo como verdadeiro
			humanoide.Health -= 10  -- Reduzir a saúde do jogador
			task.wait(RESET_TIME)  -- Aguardar a duração do reset
			part:SetAttribute("Touched", false)  -- Resetar atributo
		end
	end
end

part.Touched:Connect(damagePlayer)

Acionar sons

O debounce também é útil ao trabalhar com efeitos sonoros, como tocar um som quando duas partes colidem (Touched), ou tocar um som no evento Activated quando um usuário interage com um botão na tela. Em ambos os casos, chamar Sound:Play() inicia a reprodução do início de sua faixa e — sem um sistema de debounce — o som pode tocar várias vezes em rápida sucessão.

Para prevenir sobreposição de som, você pode usar debounce utilizando a propriedade IsPlaying do objeto Sound:

Script - Tocar Som de Colisão Usando Debounce
local projectile = script.Parent

local function playSound()
	-- Encontrar som filho na parte
	local sound = projectile:FindFirstChild("Impact")
	-- Tocar o som somente se não estiver tocando
	if sound and not sound.IsPlaying then
		sound:Play()
	end
end

projectile.Touched:Connect(playSound)

Script - Tocar Clique do Botão Usando Debounce
local button = script.Parent

local function onButtonActivated()
	-- Encontrar som filho no botão
	local sound = button:FindFirstChild("Click")
	-- Tocar o som somente se não estiver tocando
	if sound and not sound.IsPlaying then
		sound:Play()
	end
end

button.Activated:Connect(onButtonActivated)

Efeitos de Coleta

Os jogos costumam incluir itens colecionáveis no mundo 3D, como kits de saúde, pacotes de munição e mais. Se você projetar esses itens para permanecer no mundo para que os jogadores possam pegá-los repetidamente, um tempo de "cooldown" deve ser adicionado antes que o item seja renovado e reativado.

Semelhante a detecção de colisões, você pode gerenciar o estado de debounce com um atributo de instância, e visualizar o período de cooldown alterando a Transparency da parte.

Script - Coleta de Saúde Usando Debounce
local part = script.Parent
part.Anchored = true
part.CanCollide = false

local COOLDOWN_TIME = 5

local function healPlayer(otherPart)
	local humanoide = otherPart.Parent:FindFirstChildWhichIsA("Humanoid")
	if humanoide then
		if not part:GetAttribute("CoolingDown") then
			part:SetAttribute("CoolingDown", true)  -- Definir atributo como verdadeiro
			humanoide.Health += 25  -- Aumentar a saúde do jogador
			part.Transparency = 0.75  -- Tornar a parte semi-transparente para indicar estado de cooldown
			task.wait(COOLDOWN_TIME)  -- Aguardar a duração do cooldown
			part.Transparency = 0  -- Resetar parte para totalmente opaco
			part:SetAttribute("CoolingDown", false)  -- Resetar atributo
		end
	end
end

part.Touched:Connect(healPlayer)

Esse conceito de cooldown pode ser aplicado a outros cenários também, como criar um tempo de "recarga" para um lançador de foguetes para limitar a frequência com que os jogadores podem disparar foguetes.