OnInvoke

Unsafe

For thread safety, this property is not safe to read in an unsynchronized thread.

Expected return type: Tuple

Description:

This callback can be set multiple times, but cannot be called directly. It is called when the BindableFunction/Invoke method is called, using the same arguments as parameters.

Limitations

Invocations will yield until the corresponding callback is found. If the callback was never set, the script that invokes it will not resume execution.

Subscription

Only one function can be bound to BindableFunction/Invoke at a time. If you assign multiple functions, only the last one assigned will be used.

Parameter Limitations

Any type of Roblox object such as an Enumeration, Instance, or userdata can be passed as a parameter when a RemoteEvent is fired or a RemoteFunction invoked. Lua types such as numbers, strings, and booleans can also be passed, although there are some limitations on how data can be passed.

Table Identity

Copies of tables are produced when passed as arguments to or returned from the OnInvoke callback. This means that means that tables passed as arguments will not be exactly equivalent to those provided on invocation, and tables returned to the invoker will not be exactly equivalent to the ones returned by the OnInvoke callback. You can demonstrate this by running the following script in a BindableFunction:

local bindableFunction = script.Parent

bindableFunction.OnInvoke = function (t)
  print("OnInvoke", tostring(t), t)
  t = {bar = "foo"}
  print("OnInvoke2", tostring(t), t)
  return t
end

local t = {foo = "bar"}
print("Subscriber", tostring(t), t)
local retVal = script.Parent:Invoke(t)
print("return", tostring(retVal), retVal)

The above code may produce the following results in the output. Notice how the memory addresses of every table printed are completely different from each other, indicating they each represent different tables:

  13:55:22.228  Subscriber table: 0xc7daaba4d5307f10  ▶ {...} - Publisher:11
  13:55:22.229  OnInvoke table: 0x2ee92a7818e7d210  ▶ {...} - Publisher:4
  13:55:22.229  OnInvoke2 table: 0xfa4ee529ddadf290  ▶ {...} - Publisher:6
  13:55:22.229  return table: 0x35b7bc1bc323d510  ▶ {...} - Publisher:13

Mixed Tables

Avoid passing a mixed table (some values indexed by number and others by key), as only the data indexed by number will be passed. For example, when the server receives the colorData table illustrated below, it only sees indices 1 and 2 containing "Blue" and "Yellow" while the other data is lost in the transfer. Note, however, that sub-tables do not need to be indexed in the same way as their parent — in other words, as long as each individual sub-table is indexed with the same type, all of the data is preserved.

Metatables are not preserved.

Non-String Indices

If any indices of a passed table are non-string type (Instance, userdata, function, another table, etc.), those indices will be converted to a string.

-- Mixed table
local colorData = {}
colorData[1] = "Blue"
colorData[2] = "Yellow"
colorData["Color1"] = "Green"
colorData["Color2"] = "Red"

-- Table with two key-indexed sub-tables
local playerData = {}
playerData["CharData"] = {
	-- All children indexed by key
	CharName = "Diva Dragonslayer",
	CharClass = "Knight"
}
playerData["Inventory"] = {
	-- All children numerically indexed
	"Sword",
	"Bow",
	"Rope"
}

Functions

Functions passed as parameters will not be replicated, therefore making it impossible to use these objects to pass functions between scripts.

Parameters

Name	Type	Default	Description
Name arguments	Type Tuple	Default	Summary These are the parameters sent when the BindableFunction is Invoked.

Expected return type:

Return Type	Summary
Return Type Tuple	Summary

Code Samples

BindableFunction Valid Values

This code sample shows the kinds of values that can be sent to and from BindableFunctions via Invoke/OnInvoke. Test this code by placing a Script within a BindableFunction inside the Workspace or ServerScriptService. It will raise errors on the values that cannot be sent.

			
				BindableFunction Valid Values

				Expected Output
			
				Expand
				
			local bf = script.Parent

-- Dummy function
bf.OnInvoke = function (...) return ... end

-- These values CAN be sent to/from BindableFunctions
bf:Invoke()           -- nil
bf:Invoke(25)         -- numbers
bf:Invoke("hello")    -- strings
bf:Invoke(true)       -- booleans
bf:Invoke("buy", 25)  -- multiple values are OK
bf:Invoke{1, 2, 3}    -- tables as arrays with no gaps
                      -- note the curly braces
bf:Invoke{            -- tables with string keys only
	hello = "world";
	goodbye = "world";
}
bf:Invoke{            -- tables with string keys
	point = {1, 2};   -- whose values are also valid
	point2 = {3, 4};
}
bf:Invoke{            -- tables as arrays
	{1, 2, 3};        -- whose values also are valid
	{hello = "world";};
}

-- These are some values you CANNOT send to/from BindableFunctions
bf:Invoke{1, nil, 3}  -- tables as arrays cannot have nil gaps
bf:Invoke{
	[{}] = "hello";   -- table keys can only be numbers OR strings
}
bf:Invoke{            -- tables keys cannot be BOTH numbers AND strings  
	[1] = "apple";
	hello = "world";
}
		
				Copy Code
			
				Light Theme

BindableFunction Addition

This code sample sets the OnInvoke callback of the parent BindableFunction to a function that returns the sum of two numbers. Test this code sample by pasting this code inside a Script within a BindableFunction. You’ll then be able to use Invoke on the BindableFunction from other scripts.

			
				BindableFunction Addition

				Expected Output
			
				Expand
				
			local bf = script.Parent

-- Define a function for use with the BindableFunction
local function AddTwoNumbers(a, b)
	return a + b
end

-- Set the OnInvoke callback to be our function
bf.OnInvoke = AddTwoNumbers

-- Invoke the BindableFunction
print(bf:Invoke(25, 44))
		
				Copy Code
			
				Light Theme

Temporary DataStore

This code sample demonstrates one possible usage of BindableFunction|BindableFunctions, temporary datastores, in combination with ClickDetector|ClickDetectors. It also demonstrates why BindableFunctions are important, since they allow multiple server Script|Scripts to communicate with each other.

Note that this can also be achieved through the use of a ModuleScript.

This example creates a datastore using a table in a Script. Since it does not utilize Roblox’s GlobalDataStore|DataStores, it is temporary and player data is erased when the player leaves or the server shuts down. For persistent DataStores, take a look at this article.

The code below contains two parts:

###TempDataStore Script
The script containing the BindableFunction/OnInvoke callback. Since this is a callback, the Invoke() function will wait for and receive the results of the invoked function. This is the TempDataStore script in the code below.

This script maintains a table called PlayerData that tracks players’ data while they are in the game. When a player enters the game, they are added to the table with a balance of 0 using their Player/UserId|UserId as the table key. When a player exits the game, their key is removed from the table. The script creates two BindableFunctions to interact with the ActivateButton script named GetData and SetData.

When GetData’s OnInvoke event fires, the script returns the player’s balance in PlayerData.

When SetData’s OnInvoke event fires, the script set’s the player’s balance in PlayerData to the value passed as an argument and returns the updated value.

###ActivateButton Script
The script containing the BindableFunction/Invoke function. This is the ActivateButton script in the code below.

It creates a ClickDetector that allows the player to retrieve and increment their balance in the temporary datastore in TempDataStore. When the player left mouse clicks on the parent part the SetData BindableFunction is Invoked, which increases the player’s balance by 1. When the player right mouse clicks on the part the GetData BindableFunction is invoked, which retrieves and prints the player’s balance.

			
				Temporary DataStore

				Expected Output
			
				Expand
				
			-- TempDataStore (Script 1)
local GetData = Instance.new("BindableFunction", game.ServerStorage)
GetData.Name = "GetData"

local SetData = Instance.new("BindableFunction", game.ServerStorage)
SetData.Name = "SetData"

local PlayerData = {}

local function getData(player)
	return PlayerData[player.UserId]
end

local function setData(player, value)
	PlayerData[player.UserId] = value
	return PlayerData[player.UserId]
end

local function addPlayerData(player)
	table.insert(PlayerData, player.UserId, 0)
end

local function removePlayerData(player)
	table.remove(PlayerData, player.UserId)
end

GetData.OnInvoke = getData
SetData.OnInvoke = setData

game.Players.PlayerAdded:Connect(addPlayerData)
game.Players.PlayerRemoving:Connect(removePlayerData)

-- ActivateButton (Script 2)
local GetData = game.ServerStorage:WaitForChild("GetData")
local SetData = game.ServerStorage:WaitForChild("SetData")

local ClickDetector = Instance.new("ClickDetector", script.Parent)

local function getData(player)
	print(player.Name.."'s Current Balance: "..GetData:Invoke(player))
end

local function setData(player)
	local value = 100
	print("Set "..player.Name.."'s Balance to: "..SetData:Invoke())
end

local function incrementData(player)
	local balance = GetData:Invoke(player)
	print("Set "..player.Name.."'s Balance to: "..SetData:Invoke(player, balance+1))
end

ClickDetector.MouseClick:Connect(incrementData)
ClickDetector.RightMouseClick:Connect(getData)
		
				Copy Code
			
				Light Theme