Sự kiện và callback có thể kết nối | Tài liệu

BindableEvent và BindableFunction cho phép bạn liên kết các hành vi giữa các script ở cùng một bên của ranh giới client-server và giao tiếp một kết quả mong muốn cụ thể cho các hành động trong trò chơi.

Trường hợp sử dụng phổ biến nhất cho các sự kiện có thể kết nối là cho các trò chơi có cấu trúc dựa trên vòng. Ví dụ, bạn có thể có một sự kiện "trận đấu đã bắt đầu" cho phép các script khác bắt đầu một bộ đếm thời gian và hiển thị bảng xếp hạng, với một sự kiện "trận đấu đã kết thúc" tương ứng cho phép các script khác biết khi nào chuyển người chơi trở lại sảnh chờ và hiển thị những người chiến thắng.

Vì chúng phối hợp các hoạt động giữa các script, các sự kiện có thể kết nối thường được sử dụng trên máy chủ, nhưng bạn cũng có thể sử dụng chúng trên client.

Tùy thuộc vào cách trò chơi của bạn hoạt động, các sự kiện có thể kết nối có thể giúp làm cho mã của bạn trở nên mô-đun hơn, nhưng module scripts thường là một lựa chọn tốt hơn cho những tình huống mà bạn cần chia sẻ dữ liệu giữa các script. Bạn cũng có thể sử dụng các sự kiện có thể kết nối cùng với các module scripts để có cú pháp rõ ràng hơn, như đã lưu ý trong Sự kiện tùy chỉnh.

Để giao tiếp giữa các script qua ranh giới client-server, hãy xem Remote events.

Các sự kiện có thể kết nối

Đối tượng BindableEvent cho phép các sự kiện tùy chỉnh thông qua giao tiếp bất đồng bộ, một chiều giữa các script.

Khi bạn kích hoạt một BindableEvent thông qua phương thức Fire(), script kích hoạt không chờ, và hàm mục tiêu nhận các đối số đã truyền với một số giới hạn nhất định. Giống như tất cả các sự kiện, BindableEvents tạo các luồng cho mỗi hàm kết nối, nên ngay cả khi một hàm xảy ra lỗi, các hàm khác vẫn sẽ tiếp tục.

Để tạo một BindableEvent mới bằng cách sử dụng cửa sổ Explorer trong Studio:

Di chuột qua container mà bạn muốn chèn BindableEvent vào. Chúng tôi khuyên bạn nên sử dụng ServerScriptService để giao tiếp giữa các script máy chủ và ReplicatedStorage để giao tiếp giữa các script client.
Nhấn nút ⊕ xuất hiện ở bên phải tên container và chèn một instance BindableEvent.
Đổi tên instance thành TestBindableEvent.

Sau khi bạn đã tạo một BindableEvent, hãy kết nối một hàm với sự kiện Event của nó trong một script, và sau đó Fire() sự kiện từ một script khác.

Kết Nối Sự Kiện
local ServerScriptService = game:GetService("ServerScriptService")

-- Lấy tham chiếu đến instance bindable event
local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

-- Kết nối hàm ẩn danh với sự kiện
bindableEvent.Event:Connect(function(data)
	print(data)  --> Trận đấu đã bắt đầu!
end)

Kích Hoạt Sự Kiện
local ServerScriptService = game:GetService("ServerScriptService")

-- Lấy tham chiếu đến instance bindable event
local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

-- Kích hoạt sự kiện bindable
bindableEvent:Fire("Trận đấu đã bắt đầu!")

Bạn có thể kết nối nhiều hàm với cùng một BindableEvent, nhưng Luau thực hiện chúng theo một thứ tự không thể đoán trước. Để đảm bảo rằng các hàm thực thi theo một thứ tự cụ thể, kết hợp chúng thành một hàm duy nhất và kết nối nó với sự kiện.

Callback tùy chỉnh

Đối tượng BindableFunction cho phép giao tiếp đồng bộ, hai chiều giữa các script. Bạn có thể sử dụng nó để định nghĩa một hàm callback tùy chỉnh và gọi nó bằng cách gọi BindableFunction:Invoke(). Mã gọi hàm sẽ chờ cho đến khi callback tương ứng được tìm thấy, và callback nhận các đối số mà bạn đã truyền cho Invoke(). Nếu callback chưa bao giờ được thiết lập, script gọi nó sẽ không tiếp tục thực thi.

Để tạo một BindableFunction mới bằng cách sử dụng cửa sổ Explorer trong Studio:

Di chuột qua container mà bạn muốn chèn BindableFunction vào. Chúng tôi khuyên bạn nên sử dụng ServerScriptService để giao tiếp giữa các script máy chủ và ReplicatedStorage để giao tiếp giữa các script client.
Nhấn nút ⊕ xuất hiện ở bên phải tên container và chèn một instance BindableFunction.
Đổi tên instance thành TestBindableFunction.

Khi bạn đã tạo một BindableFunction, bạn có thể kết nối đến callback OnInvoke của nó trong một script, sau đó Invoke() hàm callback từ một script khác.

Kết Nối Callback
local ServerScriptService = game:GetService("ServerScriptService")

-- Lấy tham chiếu đến bindable function
local bindableFunction = ServerScriptService:WaitForChild("TestBindableFunction")

-- Hàm callback
local function addTwoNumbers(a, b)
	return a + b
end

-- Đặt hàm làm callback cho bindable function
bindableFunction.OnInvoke = addTwoNumbers

Gọi Sự Kiện
local ServerScriptService = game:GetService("ServerScriptService")

-- Lấy tham chiếu đến bindable function
local bindableFunction = ServerScriptService:WaitForChild("TestBindableFunction")

-- Gọi hàm callback và xuất kết quả trả về
local sum = bindableFunction:Invoke(2, 4)
print(sum)  --> 6

Mỗi BindableFunction chỉ có thể sử dụng một OnInvoke callback. Nếu bạn tạo nhiều định nghĩa, chỉ định nghĩa cuối cùng được gán sẽ chạy. Cũng lưu ý rằng nếu callback OnInvoke không có câu lệnh return, thì lệnh gọi sẽ trả về nil.

Giới hạn đối số

Khi bạn kích hoạt một BindableEvent hoặc gọi một BindableFunction, nó chuyển tiếp mọi đối số mà bạn truyền cùng với sự kiện hoặc đến hàm callback. Bạn có thể truyền bất kỳ loại đối tượng Roblox nào (Enum, Instance, v.v.), cũng như các loại Luau như số, chuỗi, và boolean, mặc dù bạn nên cân nhắc cẩn thận các giới hạn sau.

Chỉ số không phải chuỗi

Nếu bất kỳ chỉ số nào của một bảng đã truyền là các loại không phải chuỗi, chẳng hạn như một Instance, userdata, hoặc function, Roblox sẽ tự động chuyển đổi các chỉ số đó thành chuỗi.

Kết Nối Sự Kiện
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

-- Kết nối hàm với sự kiện
bindableEvent.Event:Connect(onEventFire)

Kích Hoạt Sự Kiện
local ServerScriptService = game:GetService("ServerScriptService")

local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

-- Kích hoạt sự kiện với bảng chứa một instance workspace làm khóa
bindableEvent:Fire({
	[workspace.Baseplate] = true
})

Đánh chỉ số bảng

Nếu bạn truyền một bảng dữ liệu, hãy không truyền một bảng hỗn hợp của các khóa số và chuỗi. Điều này có thể dẫn đến việc loại bỏ các phần tử trong quá trình chuyển. Thay vào đó, hãy truyền một bảng bao gồm hoàn toàn các cặp khóa-giá trị (một từ điển) hoặc hoàn toàn các chỉ số số (một mảng).

Trong cả hai trường hợp, dù là truyền một bảng từ điển hay bảng đã được đánh chỉ số số, hãy tránh các giá trị nil cho bất kỳ chỉ số nào.

Kết Nối Sự Kiện
local ServerScriptService = game:GetService("ServerScriptService")

local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

local function onEventFire(passedTable)
	for k, v in passedTable do
		print(k .. " = " .. v)
		--> 1 = Sword
		--> 2 = Bow
		--> CharName = Diva Dragonslayer
		--> CharClass = Rogue
	end
end

-- Kết nối hàm với sự kiện
bindableEvent.Event:Connect(onEventFire)

Kích Hoạt Sự Kiện
local ServerScriptService = game:GetService("ServerScriptService")

local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

-- Bảng đã được đánh chỉ số số
local inventoryData = {
	"Sword", "Bow"
}
-- Bảng từ điển
local characterData = {
	CharName = "Diva Dragonslayer",
	CharClass = "Rogue"
}

-- Kích hoạt sự kiện với các bảng đã được đánh chỉ số một cách đồng nhất
bindableEvent:Fire(inventoryData)
bindableEvent:Fire(characterData)

Định danh bảng

Các bảng được truyền dưới dạng đối số cho các sự kiện có thể kết nối và callback sẽ được sao chép, có nghĩa là chúng sẽ không hoàn toàn tương đương với những bảng đã được cung cấp khi kích hoạt sự kiện hoặc gọi hàm callback. Các bảng trả về cho người gọi cũng sẽ không hoàn toàn tương đương với những bảng đã được cung cấp. Bạn có thể chứng minh điều này bằng cách chạy mã sau trên một BindableFunction và quan sát cách các định danh bảng khác nhau.

Kết Nối Callback
local ServerScriptService = game:GetService("ServerScriptService")

local bindableFunction = ServerScriptService:WaitForChild("TestBindableFunction")

-- Hàm callback
local function returnTable(passedTable)
	-- Xuất định danh bảng khi được gọi
	print(tostring(passedTable))  --> table: 0x48eb7aead27563d9
	return passedTable
end

-- Đặt hàm làm callback cho bindable function
bindableFunction.OnInvoke = returnTable

Gọi Sự Kiện
local ServerScriptService = game:GetService("ServerScriptService")

local bindableFunction = ServerScriptService:WaitForChild("TestBindableFunction")

local inventoryData = {
	"Sword", "Bow"
}
-- Xuất định danh bảng gốc
print(tostring(inventoryData))  --> table: 0x059bcdbb2b576549

local invokeReturn = bindableFunction:Invoke(inventoryData)

-- Xuất định danh bảng khi trả về
print(tostring(invokeReturn))  --> table: 0x9fcae7919563a0e9

Metatables

Nếu một bảng có một metatable, tất cả thông tin về metatable sẽ bị mất trong quá trình chuyển. Trong đoạn mã mẫu sau, thuộc tính NumWheels là một phần của metatable Car. Khi máy chủ nhận bảng sau, bảng truck có thuộc tính Name nhưng không có thuộc tính NumWheels.

Kết Nối Sự Kiện
local ServerScriptService = game:GetService("ServerScriptService")

local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

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

-- Kết nối hàm với sự kiện
bindableEvent.Event:Connect(onEvent)

Kích Hoạt Sự Kiện
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)

-- Kích hoạt sự kiện với bảng bao gồm một metatable
bindableEvent:Fire(truck)