Debounce

Up one category:
Tutorials

Introduction

A debounce system is a system that keeps a function from running too many times. It usually is used in a listener because a listener can be called many times while it's still working.

A Debounce system is a set of code that keeps a function from running too many times. It comes from the idea of someone bouncing against a wall and triggering an event many times. You don't always want your code to run again and again, so Debounces are used to keep this from happening.

The Theory

Let's say you have a button on the floor. When you jump on the button, it prints a message to the output. Your code would look like this:

function OnTouch(hit)					--Creating the function
	print ("Button pressed")			--Print the message
	wait(1)						--Wait for 1 second
	print ("Hi :D")					--Print another message
end

game.Workspace.Button.Touched:connect(OnTouch)		--Connect the Event to the Function

This will put this message in the output:

Button pressed
Hi :D

The problem is that the physics engine, because of the way bricks touch each other, will not register just one collision, it may cause several Touched events to fire. So your output will look more like this:

Button pressed
Button pressed
Button pressed
Button pressed
Button pressed
Hi :D
Hi :D
Hi :D
Hi :D
Hi :D

Now if you're using a button for a Regeneration Script then it will make 5 of whatever you are regenerating. This is an issue because all 5 will be in the same spot causing all kinds of problems. So you can see the problem when you have a script without Debounce.

Debounce is a system that prevents this kind of problem. When an action happens, such as someone pressing your floor button, the script locks any new actions from that event until a time passes or the action is complete. It can be used for much more than just buttons, think of different ways you can use it for your scripts.

Setting up scripts

It's fairly simple to convert an existing script to using debounce. Lets use the same script we had above, and add a couple of lines. In this case we will put in a time limit to wait for until the function can be run again.

Template:CodeExample enabled = true

function OnTouch(hit)

if not enabled then return end

enabled = false

print ("Button pressed")

wait(1)

print ("Hi :D")

enabled = true

end

game.Workspace.Button.Touched:connect(OnTouch)

|}

1. The first blue line that we added was enabled = true. This line creates a global variable called enabled. This is the flag that we will use to let the function know if it is allowed to run or not.
2. The second line if not enabled then return end is what's called a check. It checks to see if the script is allowed to run. if the function is not true (enabled) then return nothing and end.
3. The third line enabled = false sets the variable enabled to false. This flags the script, letting it know not to run. This is how the check works.
4. The fourth line enabled = true tells the script at the end of the function that it is ok to run the function again, because the function has ended. The flag is set to go.

This will cause your output to look like this:

Button pressed
Hi :D

That's more like it! You can use this same concept, by adding the same 4 lines to different scripts, in most any script involving functions. It doesn't even have to just be touched objects, it can be used to keep people from pressing a button more than once, firing a weapon more often than you want, or preventing a new event from happening before the old one is done. Take a look at the next example.

Debounce in a real script

Here's the Local Gui script of the Rocket Launcher tool:

enabled = true
function onButton1Down(mouse)
	if not enabled then
		return
	end

	enabled = false
	mouse.Icon = "rbxasset://textures\\GunWaitCursor.png"

	wait(12)
	mouse.Icon = "rbxasset://textures\\GunCursor.png"
	enabled = true

end

When you fire a rocket, the script shows the reload icon. Then the function waits for 12 seconds. During this time, enabled is false, so if the player tries to fire another rocket, the script won't run because the function will just return right away. After the 12 seconds are up, the reload cursor goes away and enabled becomes true again, allowing the user to fire another rocket.