BindableEvent and BindableFunction objects allow you to bind behaviors between scripts on the same side of the client-server boundary and communicate a specific desired outcome for in-experience actions.
Bindable events do not allow for communication between the server and clients. If you're looking for this functionality, see Remote Events and Callbacks.
Custom Events
The BindableEvent object enables custom events through asynchronous one-way communication between scripts. When you fire a BindableEvent through the Fire() method, the firing script does not yield and the target function receives the passed arguments with certain limitations. Like all events, BindableEvents create threads of each connected function, so even if one errors, others continue.
To create a new BindableEvent using the Explorer window in Studio:
- Hover over the container into which you want to insert the BindableEvent. It's recommended to use ServerScriptService for communication between Scripts, or ReplicatedStorage for communication between LocalScripts.
- Click the ⊕ button that appears to the right of the container's name and insert a BindableEvent instance.
- Rename the instance to describe its purpose.
Once you've created a BindableEvent, you can connect a function to its Event event in one script, then Fire() the event from another script.
Event Connection
local ServerScriptService = game:GetService("ServerScriptService")
-- Get reference to bindable event instance
local bindableEvent = ServerScriptService:FindFirstChildOfClass("BindableEvent")
-- Connect anonymous function to event
bindableEvent.Event:Connect(function(data)
print(data) --> Round started!
end)
Event Firing
You can connect multiple functions to the same BindableEvent, but Luau executes them in an unpredictable order. To ensure that functions execute in a particular order, combine their bodies or calls into a single function and connect it to the event.
Custom Callbacks
The BindableFunction object allows for synchronous two-way communication between scripts. You can use it to define a custom callback function and invoke it manually by calling BindableFunction:Invoke(). The code invoking the function yields until the corresponding callback is found, and the callback receives the arguments that you passed to Invoke(). If the callback was never set, the script that invokes it will not resume execution.
To create a new BindableFunction via the Explorer window in Studio:
- Hover over the container into which you want to insert the BindableFunction. It's recommended to use ServerScriptService for communication between Scripts, or ReplicatedStorage for communication between LocalScripts.
- Click the ⊕ button that appears to the right of the container's name and insert a BindableFunction instance.
- Rename the instance to describe its purpose.
Once you've created a BindableFunction, you can connect to its OnInvoke callback in one script, then Invoke() the callback function from another script.
Callback Connection
local ServerScriptService = game:GetService("ServerScriptService")
-- Get reference to bindable function instance
local bindableFunction = ServerScriptService:FindFirstChildOfClass("BindableFunction")
-- Callback function
local function addTwoNumbers(a, b)
return a + b
end
-- Set function as bindable function's callback
bindableFunction.OnInvoke = addTwoNumbers
Event Invocation
Each BindableFunction can only utilize one OnInvoke callback. If you make multiple definitions, only the last one assigned will run. Also note that if the OnInvoke callback does not have a return statement, the invocation will return nil.
Argument Limitations
When you fire a BindableEvent or invoke a BindableFunction, it forwards any arguments that you pass with the event or to the callback function. Any type of Roblox object such as an Enum, Instance, or others can be passed, as well as Luau types such as numbers, strings, and booleans, although you should carefully explore the following limitations.
Non-String Indices
If any indices of a passed table are non-string types such as an Instance, userdata, or function, Roblox automatically converts those indices to strings.
Event Connection
local ServerScriptService = game:GetService("ServerScriptService")
local bindableEvent = ServerScriptService:FindFirstChildOfClass("BindableEvent")
local function onEventFire(passedTable)
for k, v in passedTable do
print(typeof(k)) --> string
end
end
-- Connect function to event
bindableEvent.Event:Connect(onEventFire)
Event Firing
Table Indexing
If you pass a table of data, do not pass a mixed table of numeric and string keys. Instead, pass a table that consists entirely of key-value pairs (dictionary) or entirely of numeric indices.
Whether passing a dictionary table or a numerically indexed table, avoid nil values for any index.
Event Connection
local ServerScriptService = game:GetService("ServerScriptService")
local bindableEvent = ServerScriptService:FindFirstChildOfClass("BindableEvent")
local function onEventFire(passedTable)
for k, v in passedTable do
print(k .. " = " .. v)
--> 1 = Sword
--> 2 = Bow
--> CharName = Diva Dragonslayer
--> CharClass = Rogue
end
end
-- Connect function to event
bindableEvent.Event:Connect(onEventFire)
Event Firing
Table Identities
Tables passed as arguments to bindable events/callbacks are copied, meaning they will not be exactly equivalent to those provided when firing the event or invoking the callback. Nor will tables returned to the invoker be exactly equivalent to those provided. You can demonstrate this by running the following script on a BindableFunction and observing how the table identities differ.
Callback Connection
local ServerScriptService = game:GetService("ServerScriptService")
local bindableFunction = ServerScriptService:FindFirstChildOfClass("BindableFunction")
-- Callback function
local function returnTable(passedTable)
-- Output table identity on invocation
print(tostring(passedTable)) --> table: 0x48eb7aead27563d9
return passedTable
end
-- Set function as bindable function's callback
bindableFunction.OnInvoke = returnTable
Event Invocation
Metatables
If a table has a metatable, all of the metatable information is lost in the transfer. In the following code sample, the NumWheels property is part of the Car metatable. When the server receives the following table, the truck table has the Name property but not the NumWheels property.
Event Connection
local ServerScriptService = game:GetService("ServerScriptService")
local bindableEvent = ServerScriptService:FindFirstChildOfClass("BindableEvent")
local function onEvent(param)
print(param) --> {["Name"] = "MyTruck"}
end
-- Connect function to event
bindableEvent.Event:Connect(onEvent)
Event Firing