BindableEvent e BindableFunction objetos permitem que você vincule comportamentos entre scripts no mesmo lado da fronteira cliente-servidor e comunique um resultado específico desejado para ações dentro do jogo.
O caso de uso mais comum para eventos vinculáveis é para jogos que têm uma estrutura baseada em rodadas. Por exemplo, você pode ter um evento "partida iniciada" que permite que outros scripts iniciem um temporizador e exibam um placar, com um correspondente evento "partida encerrada" que informa outros scripts quando mover os jogadores de volta para um saguão e exibir os vencedores.
Como eles coordenam atividades entre scripts, eventos vinculáveis são tipicamente usados no servidor, mas você também pode usá-los no cliente.
Dependendo de como seu jogo funciona, eventos vinculáveis podem ajudar a tornar seu código mais modular, mas scripts de módulo muitas vezes são uma alternativa melhor para situações em que você precisa compartilhar dados entre scripts. Você também pode usar eventos vinculáveis em conjunto com scripts de módulo para uma sintaxe mais limpa, conforme observado em Eventos personalizados.
Para comunicar entre scripts através da fronteira cliente-servidor, consulte Eventos Remotos.
Eventos vinculáveis
O objeto BindableEvent habilita eventos personalizados através de comunicação assíncrona e unidirecional entre scripts.
Quando você dispara um BindableEvent através do método Fire(), o script que dispara não bloqueia, e a função alvo recebe os argumentos passados com certas limitações. Como todos os eventos, BindableEvents criam threads de cada função conectada, então mesmo que uma delas falhe, as outras continuam.
Para criar um novo BindableEvent usando a janela Explorer no Studio:
- Passe o mouse sobre o container onde você deseja inserir o BindableEvent. Recomendamos usar ServerScriptService para comunicação entre scripts do servidor e ReplicatedStorage para comunicação entre scripts do cliente.
- Clique no botão ⊕ que aparece à direita do nome do container e insira uma instância de BindableEvent.
- Renomeie a instância para TestBindableEvent.
Depois de criar um BindableEvent, conecte uma função ao seu evento Event em um script, e então dispare Fire() o evento a partir de outro script.
Conexão de Evento
local ServerScriptService = game:GetService("ServerScriptService")
-- Obter referência à instância do evento vinculável
local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")
-- Conectar função anônima ao evento
bindableEvent.Event:Connect(function(data)
print(data) --> Rodada iniciada!
end)
Disparo de Evento
Você pode conectar múltiplas funções ao mesmo BindableEvent, mas Luau as executa em uma ordem imprevisível. Para garantir que as funções sejam executadas em uma determinada ordem, combine-as em uma única função e conecte-a ao evento.
Callbacks personalizados
O objeto BindableFunction permite comunicação síncrona e bidirecional entre scripts. Você pode usá-lo para definir uma função de callback personalizada e invocá-la manualmente chamando BindableFunction:Invoke(). O código que invoca a função bloqueia até que o callback correspondente seja encontrado, e o callback recebe os argumentos que você passou para Invoke(). Se o callback nunca tiver sido definido, o script que o invoca não retoma a execução.
Para criar um novo BindableFunction usando a janela Explorer no Studio:
- Passe o mouse sobre o container onde você deseja inserir o BindableFunction. Recomendamos usar ServerScriptService para comunicação entre scripts do servidor e ReplicatedStorage para comunicação entre scripts do cliente.
- Clique no botão ⊕ que aparece à direita do nome do container e insira uma instância de BindableFunction.
- Renomeie a instância para TestBindableFunction.
Uma vez que você tenha criado um BindableFunction, você pode conectar-se ao seu callback OnInvoke em um script, e então Invoke() o callback a partir de outro script.
Conexão de Callback
local ServerScriptService = game:GetService("ServerScriptService")
-- Obter referência à função vinculável
local bindableFunction = ServerScriptService:WaitForChild("TestBindableFunction")
-- Função de callback
local function addTwoNumbers(a, b)
return a + b
end
-- Definir função como callback da função vinculável
bindableFunction.OnInvoke = addTwoNumbers
Invocação de Evento
Cada BindableFunction pode utilizar apenas um callback OnInvoke. Se você fizer múltiplas definições, apenas a última atribuída será executada. Além disso, note que se o callback OnInvoke não tiver uma instrução return, a invocação retornará nil.
Limitações de argumentos
Quando você dispara um BindableEvent ou invoca um BindableFunction, ele encaminha quaisquer argumentos que você passa com o evento ou para a função de callback. Você pode passar qualquer tipo de objeto Roblox (Enum, Instance, etc.), bem como tipos Luau como números, strings e booleanos, embora deva considerar cuidadosamente as seguintes limitações.
Índices não-string
Se quaisquer índices de uma tabela passada forem tipos não-string, como uma Instance, userdata ou function, o Roblox automaticamente converte esses índices para strings.
Conexão de Evento
local ServerScriptService = game:GetService("ServerScriptService")
local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")
local function onEventFire(passedTable)
for k, v in passedTable do
print(typeof(k)) --> string
end
end
-- Conectar função ao evento
bindableEvent.Event:Connect(onEventFire)
Disparo de Evento
Indexação de Tabela
Se você passar uma tabela de dados, não passe uma tabela mista com chaves numéricas e string. Isso pode resultar na remoção de elementos durante a transferência. Em vez disso, passe uma tabela que consiste exclusivamente de pares chave-valor (um dicionário) ou exclusivamente de índices numéricos (uma matriz).
Em ambos os casos, ao passar uma tabela dicionário ou uma tabela indexada numericamente, evite valores nil para qualquer índice.
Conexão de Evento
local ServerScriptService = game:GetService("ServerScriptService")
local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")
local function onEventFire(passedTable)
for k, v in passedTable do
print(k .. " = " .. v)
--> 1 = Espada
--> 2 = Arco
--> CharName = Diva Dragonslayer
--> CharClass = Rogue
end
end
-- Conectar função ao evento
bindableEvent.Event:Connect(onEventFire)
Disparo de Evento
Identidades de Tabela
Tabelas passadas como argumentos para eventos vinculáveis e callbacks são copiadas, significando que não serão exatamente equivalentes àquelas fornecidas ao disparar o evento ou invocar o callback. As tabelas retornadas ao invocador também não serão exatamente equivalentes às fornecidas. Você pode demonstrar isso executando o seguinte script em um BindableFunction e observando como as identidades da tabela diferem.
Conexão de Callback
local ServerScriptService = game:GetService("ServerScriptService")
local bindableFunction = ServerScriptService:WaitForChild("TestBindableFunction")
-- Função de callback
local function returnTable(passedTable)
-- Saída da identidade da tabela na invocação
print(tostring(passedTable)) --> table: 0x48eb7aead27563d9
return passedTable
end
-- Definir função como callback da função vinculável
bindableFunction.OnInvoke = returnTable
Invocação de Evento
Metatables
Se uma tabela tem uma metatable, todas as informações da metatable são perdidas na transferência. No seguinte código de exemplo, a propriedade NumWheels é parte da metatable Car. Quando o servidor recebe a tabela a seguir, a tabela truck tem a propriedade Name, mas não a propriedade NumWheels.
Conexão de Evento
local ServerScriptService = game:GetService("ServerScriptService")
local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")
local function onEvent(param)
print(param) --> {["Name"] = "MeuCaminhão"}
end
-- Conectar função ao evento
bindableEvent.Event:Connect(onEvent)
Disparo de Evento