BindableEvent y BindableFunction permiten vincular comportamientos entre scripts en el mismo lado de la frontera del cliente-servidor y comunicar un resultado específico deseado para las acciones dentro del juego.
El caso de uso más común para los eventos vinculables es para juegos que tienen una estructura basada en rondas. Por ejemplo, podrías tener un evento de "partida iniciada" que permite a otros scripts iniciar un temporizador y mostrar una tabla de posiciones, junto con un evento correspondiente de "partida terminada" que informa a otros scripts de cuándo volver a mover a los jugadores a un vestíbulo y mostrar a los ganadores.
Debido a que coordinan actividades entre scripts, los eventos vinculables se utilizan típicamente en el servidor, pero también puedes usarlos en el cliente.
Dependiendo de cómo funcione tu juego, los eventos vinculables pueden ayudar a hacer que tu código sea más modular, pero los scripts de módulo suelen ser una mejor alternativa para situaciones en las que necesitas compartir datos entre scripts. También puedes usar eventos vinculables junto con scripts de módulo para una sintaxis más limpia, como se menciona en Eventos personalizados.
Para comunicarte entre scripts a través de la frontera cliente-servidor, consulta Eventos remotos.
Eventos vinculables
El objeto BindableEvent habilita eventos personalizados a través de comunicación asíncrona unidireccional entre scripts.
Cuando activas un BindableEvent a través del método Fire(), el script que activa no se suspende, y la función objetivo recibe los argumentos pasados con ciertas limitaciones. Como todos los eventos, BindableEvents crean hilos de cada función conectada, por lo que incluso si una falla, las demás continúan.
Para crear un nuevo BindableEvent utilizando la ventana del Explorador en Studio:
- Pasa el cursor sobre el contenedor en el que deseas insertar el BindableEvent. Recomendamos usar ServerScriptService para la comunicación entre scripts del servidor y ReplicatedStorage para la comunicación entre scripts del cliente.
- Haz clic en el botón ⊕ que aparece a la derecha del nombre del contenedor e inserta una instancia de BindableEvent.
- Cambia el nombre de la instancia a TestBindableEvent.
Después de crear un BindableEvent, conecta una función a su evento Event en un script y luego Fire() el evento desde otro script.
Conexión de evento
local ServerScriptService = game:GetService("ServerScriptService")
-- Obtener referencia a la instancia de evento vinculable
local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")
-- Conectar función anónima al evento
bindableEvent.Event:Connect(function(data)
print(data) --> ¡Ronda iniciada!
end)
Activación del evento
Puedes conectar múltiples funciones al mismo BindableEvent, pero Luau las ejecuta en un orden impredecible. Para asegurar que las funciones se ejecuten en un orden específico, combínalas en una sola función y conéctala al evento.
Callbacks personalizados
El objeto BindableFunction permite la comunicación sincrónica bidireccional entre scripts. Puedes usarlo para definir una función de callback personalizada e invocarla manualmente llamando a BindableFunction:Invoke(). El código que invoca la función se suspende hasta que se encuentra el callback correspondiente, y el callback recibe los argumentos que pasaste a Invoke(). Si el callback nunca se establece, el script que lo invoca no reanuda su ejecución.
Para crear un nuevo BindableFunction utilizando la ventana del Explorador en Studio:
- Pasa el cursor sobre el contenedor en el que deseas insertar el BindableFunction. Recomendamos usar ServerScriptService para la comunicación entre scripts del servidor y ReplicatedStorage para la comunicación entre scripts del cliente.
- Haz clic en el botón ⊕ que aparece a la derecha del nombre del contenedor e inserta una instancia de BindableFunction.
- Cambia el nombre de la instancia a TestBindableFunction.
Una vez que has creado un BindableFunction, puedes conectarte a su callback OnInvoke en un script, luego Invoke() la función de callback desde otro script.
Conexión de Callback
local ServerScriptService = game:GetService("ServerScriptService")
-- Obtener referencia a la función vinculable
local bindableFunction = ServerScriptService:WaitForChild("TestBindableFunction")
-- Función de callback
local function addTwoNumbers(a, b)
return a + b
end
-- Establecer la función como callback de la función vinculable
bindableFunction.OnInvoke = addTwoNumbers
Invocación del evento
Cada BindableFunction solo puede utilizar un callback OnInvoke. Si realizas múltiples definiciones, solo se ejecutará la última asignada. También ten en cuenta que si el callback OnInvoke no tiene una declaración return, la invocación devuelve nil.
Limitaciones de argumentos
Cuando activas un BindableEvent o invocas un BindableFunction, se reenvían cualquier argumento que pases con el evento o a la función de callback. Puedes pasar cualquier tipo de objeto de Roblox (Enum, Instance, etc.), así como tipos de Luau como números, cadenas y booleanos, aunque debes considerar cuidadosamente las siguientes limitaciones.
Índices no string
Si alguno de los índices de una tabla pasada son tipos no string, como una Instance, userdata, o función, Roblox convierte automáticamente esos índices a strings.
Conexión 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 función al evento
bindableEvent.Event:Connect(onEventFire)
Activación del evento
Indexación de tablas
Si pasas una tabla de datos, no pases una tabla mixta de claves numéricas y cadenas. Hacerlo puede resultar en elementos eliminados durante la transferencia. En su lugar, pasa una tabla que consista totalmente en pares clave-valor (un diccionario) o totalmente de índices numéricos (un array).
En ambos casos, al pasar una tabla de diccionario o una tabla indexada numéricamente, evita valores nil para cualquier índice.
Conexión 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 = Pícaro
end
end
-- Conectar función al evento
bindableEvent.Event:Connect(onEventFire)
Activación del evento
Identidades de tablas
Las tablas pasadas como argumentos a eventos vinculables y callbacks se copian, lo que significa que no serán exactamente equivalentes a las que se proporcionaron al activar el evento o invocar el callback. Tampoco las tablas devueltas al invocador serán exactamente equivalentes a las que se proporcionaron. Puedes demostrar esto ejecutando el siguiente script en un BindableFunction y observando cómo difieren las identidades de las tablas.
Conexión de Callback
local ServerScriptService = game:GetService("ServerScriptService")
local bindableFunction = ServerScriptService:WaitForChild("TestBindableFunction")
-- Función de callback
local function returnTable(passedTable)
-- Mostrar identidad de la tabla en invocación
print(tostring(passedTable)) --> table: 0x48eb7aead27563d9
return passedTable
end
-- Establecer función como callback de la función vinculable
bindableFunction.OnInvoke = returnTable
Invocación del evento
Metatables
Si una tabla tiene un metatable, toda la información del metatable se pierde en la transferencia. En el siguiente ejemplo de código, la propiedad NumWheels es parte del metatable de Car. Cuando el servidor recibe la siguiente tabla, la tabla truck tiene la propiedad Name pero no la propiedad NumWheels.
Conexión de evento
local ServerScriptService = game:GetService("ServerScriptService")
local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")
local function onEvent(param)
print(param) --> {["Name"] = "MyTruck"}
end
-- Conectar función al evento
bindableEvent.Event:Connect(onEvent)
Activación del evento