바인드 가능한 이벤트 및 콜백 | 설명서

BindableEvent 및 BindableFunction 객체를 사용하면 동일한 쪽의 클라이언트-서버 경계에서 스크립트 간의 동작을 바인딩하고 게임 내에서의 행동에 대한 특정 원하는 결과를 전달할 수 있습니다.

바인드 가능한 이벤트의 가장 일반적인 사용 사례는 라운드 기반 구조를 가진 게임입니다. 예를 들어, 다른 스크립트가 타이머를 시작하고 리더보드를 표시할 수 있게 해주는 "매치 시작" 이벤트와, 다른 스크립트에게 플레이어를 로비로 되돌려 보내고 우승자를 표시할 시점을 알려주는 "매치 종료" 이벤트가 있을 수 있습니다.

바인드 가능한 이벤트는 스크립트 간의 활동을 조정하기 때문에 일반적으로 서버에서 사용되지만, 클라이언트에서도 사용할 수 있습니다.

게임의 작동 방식에 따라 바인드 가능한 이벤트는 코드의 모듈화를 개선하는 데 도움을 줄 수 있지만, 모듈 스크립트가 스크립트 간에 데이터를 공유해야 하는 경우 더 나은 대안일 때가 많습니다. 또한, 사용자 정의 이벤트에서 언급하듯이, 바인드 가능한 이벤트를 모듈 스크립트와 함께 사용하여 더 깔끔한 구문을 만들 수 있습니다.

클라이언트-서버 경계를 넘어 스크립트 간 통신을 하려면 원격 이벤트를 참고하세요.

바인드 가능한 이벤트

BindableEvent 객체는 스크립트 간의 비동기, 일방향 통신을 통해 사용자 정의 이벤트를 가능하게 합니다.

BindableEvent를 Fire() 메서드를 사용하여 발동할 경우, 발동하는 스크립트는 대기하지 않으며, 대상 함수는 특정한 제한과 함께 전달된 인수를 받습니다. 모든 이벤트와 마찬가지로 BindableEvents는 연결된 각 함수의 스레드를 생성하므로, 하나의 함수에 에러가 발생해도 다른 함수는 계속 진행됩니다.

Studio의 탐색기 창을 사용하여 새로운 BindableEvent를 생성하려면:

BindableEvent를 삽입할 컨테이너 위에 마우스를 올립니다. 서버 스크립트 간 통신을 위해 ServerScriptService를, 클라이언트 스크립트 간 통신을 위해 ReplicatedStorage를 사용하는 것이 좋습니다.
컨테이너 이름 오른쪽에 나타나는 ⊕ 버튼을 클릭하여 BindableEvent 인스턴스를 삽입합니다.
인스턴스의 이름을 TestBindableEvent로 변경합니다.

BindableEvent를 생성한 후, 하나의 스크립트에서 해당 Event 이벤트에 함수를 연결하고, 또 다른 스크립트에서 Fire()로 이벤트를 발동합니다.

이벤트 연결
local ServerScriptService = game:GetService("ServerScriptService")

-- 바인드 가능한 이벤트 인스턴스에 대한 참조 가져오기
local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

-- 이벤트에 익명 함수 연결
bindableEvent.Event:Connect(function(data)
	print(data)  --> 라운드 시작됨!
end)

이벤트 발동
local ServerScriptService = game:GetService("ServerScriptService")

-- 바인드 가능한 이벤트 인스턴스에 대한 참조 가져오기
local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

-- 바인드 가능한 이벤트 발동
bindableEvent:Fire("라운드 시작됨!")

동일한 BindableEvent에 여러 개의 함수를 연결할 수 있지만, Luau는 이를 예측할 수 없는 순서로 실행합니다. 함수를 특정 순서로 실행해야 하는 경우, 이를 하나의 함수로 결합하여 이벤트에 연결하세요.

BindableFunction 객체는 스크립트 간의 동기적, 양방향 통신을 가능하게 합니다. 이를 통해 사용자 정의 콜백 함수를 정의하고 BindableFunction:Invoke()를 호출하여 수동으로 호출할 수 있습니다. 함수를 호출하는 코드는 해당 콜백이 발견될 때까지 대기하며, 콜백은 Invoke()에 전달한 인수를 받습니다. 콜백이 설정되지 않은 경우, 이를 호출하는 스크립트는 실행이 재개되지 않습니다.

Studio의 탐색기 창을 사용하여 새로운 BindableFunction을 생성하려면:

BindableFunction을 삽입할 컨테이너 위에 마우스를 올립니다. 서버 스크립트 간 통신을 위해 ServerScriptService를, 클라이언트 스크립트 간 통신을 위해 ReplicatedStorage를 사용하는 것이 좋습니다.
컨테이너 이름 오른쪽에 나타나는 ⊕ 버튼을 클릭하여 BindableFunction 인스턴스를 삽입합니다.
인스턴스의 이름을 TestBindableFunction으로 변경합니다.

BindableFunction을 생성한 후, 하나의 스크립트에서 OnInvoke 콜백에 연결하고, 다른 스크립트에서 Invoke()로 콜백 함수를 호출할 수 있습니다.

콜백 연결
local ServerScriptService = game:GetService("ServerScriptService")

-- 바인드 가능한 함수 참조 가져오기
local bindableFunction = ServerScriptService:WaitForChild("TestBindableFunction")

-- 콜백 함수
local function addTwoNumbers(a, b)
	return a + b
end

-- 함수를 바인드 가능한 함수의 콜백으로 설정
bindableFunction.OnInvoke = addTwoNumbers

이벤트 호출
local ServerScriptService = game:GetService("ServerScriptService")

-- 바인드 가능한 함수 참조 가져오기
local bindableFunction = ServerScriptService:WaitForChild("TestBindableFunction")

-- 콜백 함수 호출 및 반환된 값 출력
local sum = bindableFunction:Invoke(2, 4)
print(sum)  --> 6

각 BindableFunction은 오직 하나의 OnInvoke 콜백만 사용할 수 있습니다. 여러 정의를 하면 마지막으로 할당된 것만 실행됩니다. 또한, OnInvoke 콜백이 return 문이 없으면 호출 결과는 nil입니다.

인수 제한 사항

BindableEvent를 발동하거나 BindableFunction을 호출할 때, 전달한 모든 인수를 이벤트나 콜백 함수에 전달합니다. Enum, Instance 등과 같은 Roblox 객체뿐만 아니라 숫자, 문자열 및 부울과 같은 Luau 유형도 전달할 수 있습니다. 하지만 다음 제한 사항을 신중히 고려해야 합니다.

비문자열 인덱스

전달된 테이블의 인덱스가 Instance, userdata, 또는 function과 같이 비문자열 유형이라면, Roblox는 이러한 인덱스를 자동으로 문자열로 변환합니다.

이벤트 연결
local ServerScriptService = game:GetService("ServerScriptService")

local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

local function onEventFire(passedTable)
	for k, v in passedTable do
		print(typeof(k))  --> 문자열
	end
end

-- 이벤트에 함수 연결
bindableEvent.Event:Connect(onEventFire)

이벤트 발동
local ServerScriptService = game:GetService("ServerScriptService")

local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

-- 키가 워크스페이스 인스턴스를 포함하는 테이블로 이벤트 발동
bindableEvent:Fire({
	[workspace.Baseplate] = true
})

테이블 인덱싱

데이터 테이블을 전달할 경우, 숫자 키와 문자열 키가 혼합된 테이블을 전달하지 마십시오. 이렇게 하면 전송 중에 요소가 제거될 수 있습니다. 대신, 전적으로 키-값 쌍(사전) 또는 전적으로 숫자 인덱스로 구성된 테이블(배열)을 전달해야 합니다.

사전 테이블을 전달하든 숫자로 인덱싱된 테이블을 전달하든, 어떤 인덱스에 대해서도 nil 값을 피하십시오.

이벤트 연결
local ServerScriptService = game:GetService("ServerScriptService")

local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

local function onEventFire(passedTable)
	for k, v in passedTable do
		print(k .. " = " .. v)
		--> 1 = 검
		--> 2 = 활
		--> CharName = 디바 드래곤슬레이어
		--> CharClass = 로그
	end
end

-- 이벤트에 함수 연결
bindableEvent.Event:Connect(onEventFire)

이벤트 발동
local ServerScriptService = game:GetService("ServerScriptService")

local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

-- 숫자로 인덱싱된 테이블
local inventoryData = {
	"검", "활"
}
-- 사전 테이블
local characterData = {
	CharName = "디바 드래곤슬레이어",
	CharClass = "로그"
}

-- 일관된 인덱스 테이블로 이벤트 발동
bindableEvent:Fire(inventoryData)
bindableEvent:Fire(characterData)

테이블 아이덴티티

바인드 가능한 이벤트 및 콜백에 인수로 전달된 테이블은 복사되므로, 이벤트를 발동하거나 콜백을 호출할 때 제공된 것과 정확하게 동일하지 않습니다. 또한 반환된 테이블도 호출자에게 제공된 것과 정확하게 동일하지 않습니다. BindableFunction에서 다음 스크립트를 실행하여 테이블의 아이덴티티가 어떻게 다른지 확인할 수 있습니다.

콜백 연결
local ServerScriptService = game:GetService("ServerScriptService")

local bindableFunction = ServerScriptService:WaitForChild("TestBindableFunction")

-- 콜백 함수
local function returnTable(passedTable)
	-- 호출 시 테이블 아이덴티티 출력
	print(tostring(passedTable))  --> table: 0x48eb7aead27563d9
	return passedTable
end

-- 함수를 바인드 가능한 함수의 콜백으로 설정
bindableFunction.OnInvoke = returnTable

이벤트 호출
local ServerScriptService = game:GetService("ServerScriptService")

local bindableFunction = ServerScriptService:WaitForChild("TestBindableFunction")

local inventoryData = {
	"검", "활"
}
-- 원본 테이블 아이덴티티 출력
print(tostring(inventoryData))  --> table: 0x059bcdbb2b576549

local invokeReturn = bindableFunction:Invoke(inventoryData)

-- 반환 시 테이블 아이덴티티 출력
print(tostring(invokeReturn))  --> table: 0x9fcae7919563a0e9

메타테이블

테이블에 메타테이블이 있는 경우, 전송 중 모든 메타테이블 정보가 손실됩니다. 다음 코드 샘플에서 NumWheels 속성은 Car 메타테이블의 일부입니다. 서버가 다음 테이블을 수신할 때, truck 테이블은 Name 속성은 가지지만 NumWheels 속성은 가지지 않습니다.

이벤트 연결
local ServerScriptService = game:GetService("ServerScriptService")

local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

local function onEvent(param)
	print(param)  --> {["Name"] = "MyTruck"}
end

-- 이벤트에 함수 연결
bindableEvent.Event:Connect(onEvent)

이벤트 발동
local ServerScriptService = game:GetService("ServerScriptService")

local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

local Car = {}
Car.NumWheels = 4
Car.__index = Car

local truck = {}
truck.Name = "MyTruck"
setmetatable(truck, Car)

-- 메타테이블을 포함하는 테이블로 이벤트 발동
bindableEvent:Fire(truck)