Event dan callback yang dapat diikat | Dokumentasi

BindableEvent dan BindableFunction memungkinkan Anda untuk mengikat perilaku antara skrip di sisi yang sama dari batas klien-server dan mengkomunikasikan hasil yang diinginkan untuk tindakan dalam permainan.

Kasus penggunaan paling umum untuk event yang dapat diikat adalah untuk permainan yang memiliki struktur berbasis ronde. Misalnya, Anda mungkin memiliki event "pertandingan dimulai" yang memungkinkan skrip lain memulai timer dan menampilkan papan peringkat, dengan event "pertandingan berakhir" yang sesuai yang memberi tahu skrip lain kapan harus memindahkan pemain kembali ke lobi dan menampilkan para pemenang.

Karena mereka mengoordinasikan aktivitas antara skrip, event yang dapat diikat biasanya digunakan di server, tetapi Anda juga bisa menggunakannya di klien.

Tergantung pada bagaimana permainan Anda bekerja, event yang dapat diikat dapat membantu membuat kode Anda lebih modular, tetapi skrip modul sering kali merupakan alternatif yang lebih baik untuk situasi di mana Anda perlu berbagi data antar skrip. Anda juga dapat menggunakan event yang dapat diikat bersamaan dengan skrip modul untuk sintaks yang lebih bersih, seperti yang dijelaskan dalam Event kustom.

Untuk berkomunikasi antar skrip lintas batas klien-server, lihat Event Jarak Jauh.

Event yang dapat diikat

Objek BindableEvent memungkinkan event kustom melalui komunikasi satu arah yang asinkron antar skrip.

Ketika Anda memicu BindableEvent melalui metode Fire(), skrip yang memicu tidak menunggu, dan fungsi target menerima argumen yang disertakan dengan batasan tertentu. Seperti semua event, BindableEvents membuat utas untuk setiap fungsi yang terhubung, jadi meskipun salah satu mengalami kesalahan, yang lain tetap berlanjut.

Untuk membuat BindableEvent baru menggunakan jendela Explorer di Studio:

Arahkan kursor ke wadah tempat Anda ingin menyisipkan BindableEvent. Kami merekomendasikan menggunakan ServerScriptService untuk komunikasi antar skrip server dan ReplicatedStorage untuk komunikasi antar skrip klien.
Klik tombol ⊕ yang muncul di sebelah kanan nama wadah dan sisipkan sebuah instance BindableEvent.
Ganti nama instance menjadi TestBindableEvent.

Setelah Anda membuat BindableEvent, sambungkan sebuah fungsi ke event Event di satu skrip, dan kemudian Fire() event dari skrip lain.

Koneksi Event
local ServerScriptService = game:GetService("ServerScriptService")

-- Dapatkan referensi ke instance event yang dapat diikat
local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

-- Hubungkan fungsi anonim ke event
bindableEvent.Event:Connect(function(data)
	print(data)  --> Ronde dimulai!
end)

Pemicu Event
local ServerScriptService = game:GetService("ServerScriptService")

-- Dapatkan referensi ke instance event yang dapat diikat
local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

-- Memicu event yang dapat diikat
bindableEvent:Fire("Ronde dimulai!")

Anda dapat menghubungkan beberapa fungsi ke BindableEvent yang sama, tetapi Luau mengeksekusinya dalam urutan yang tidak terduga. Untuk memastikan bahawa fungsi dieksekusi dalam urutan tertentu, kombinasikan mereka menjadi satu fungsi dan sambungkan ke event.

Callback Kustom

Objek BindableFunction memungkinkan komunikasi dua arah yang sinkron antar skrip. Anda dapat menggunakannya untuk mendefinisikan fungsi callback kustom dan memanggilnya secara manual dengan memanggil BindableFunction:Invoke(). Kode yang memanggil fungsi menunggu sampai callback yang sesuai ditemukan, dan callback menerima argumen yang Anda berikan ke Invoke(). Jika callback tidak pernah diatur, skrip yang memanggilnya tidak melanjutkan eksekusi.

Untuk membuat BindableFunction baru menggunakan jendela Explorer di Studio:

Arahkan kursor ke wadah tempat Anda ingin menyisipkan BindableFunction. Kami merekomendasikan menggunakan ServerScriptService untuk komunikasi antar skrip server dan ReplicatedStorage untuk komunikasi antar skrip klien.
Klik tombol ⊕ yang muncul di sebelah kanan nama wadah dan sisipkan sebuah instance BindableFunction.
Ganti nama instance menjadi TestBindableFunction.

Setelah Anda membuat BindableFunction, Anda dapat terhubung ke callback OnInvoke di satu skrip, lalu Invoke() fungsi callback dari skrip lain.

Koneksi Callback
local ServerScriptService = game:GetService("ServerScriptService")

-- Dapatkan referensi ke fungsi yang dapat diikat
local bindableFunction = ServerScriptService:WaitForChild("TestBindableFunction")

-- Fungsi callback
local function addTwoNumbers(a, b)
	return a + b
end

-- Atur fungsi sebagai callback fungsi yang dapat diikat
bindableFunction.OnInvoke = addTwoNumbers

Pemanggilan Event
local ServerScriptService = game:GetService("ServerScriptService")

-- Dapatkan referensi ke fungsi yang dapat diikat
local bindableFunction = ServerScriptService:WaitForChild("TestBindableFunction")

-- Panggil fungsi callback dan keluarkan nilai yang dikembalikan
local sum = bindableFunction:Invoke(2, 4)
print(sum)  --> 6

Setiap BindableFunction hanya dapat menggunakan satu callback OnInvoke. Jika Anda membuat beberapa definisi, hanya yang terakhir yang ditetapkan yang akan dijalankan. Juga perhatikan bahwa jika callback OnInvoke tidak memiliki pernyataan return, pemanggilan akan mengembalikan nil.

Batasan Argumen

Ketika Anda memicu BindableEvent atau memanggil BindableFunction, ia meneruskan argumen apa pun yang Anda berikan dengan event atau kepada fungsi callback. Anda dapat memberikan jenis objek Roblox apa pun (Enum, Instance, dll.), serta tipe Luau seperti angka, string, dan boolean, meskipun Anda harus mempertimbangkan batasan berikut dengan hati-hati.

Indeks Non-string

Jika ada indeks dari tabel yang diberikan adalah tipe non-string, seperti Instance, userdata, atau fungsi, Roblox secara otomatis mengonversi indeks tersebut menjadi string.

Koneksi Event
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

-- Hubungkan fungsi ke event
bindableEvent.Event:Connect(onEventFire)

Pemicu Event
local ServerScriptService = game:GetService("ServerScriptService")

local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

-- Memicu event dengan tabel yang berisi instance workspace sebagai kunci
bindableEvent:Fire({
	[workspace.Baseplate] = true
})

Indeks Tabel

Jika Anda memberikan tabel data, jangan memberikan tabel campuran dengan kunci numerik dan string. Melakukannya dapat mengakibatkan elemen yang dihapus selama transfer. Sebaliknya, berikan tabel yang terdiri entirely dari pasangan kunci-nilai (kamus) atau entirely dari indeks numerik (array).

Dalam kedua kasus, baik memberikan tabel kamus atau tabel yang diindeks secara numerik, hindari nilai nil untuk indeks mana pun.

Koneksi Event
local ServerScriptService = game:GetService("ServerScriptService")

local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

local function onEventFire(passedTable)
	for k, v in passedTable do
		print(k .. " = " .. v)
		--> 1 = Pedang
		--> 2 = Busur
		--> CharName = Diva Pembantai Naga
		--> CharClass = Penjahat
	end
end

-- Hubungkan fungsi ke event
bindableEvent.Event:Connect(onEventFire)

Pemicu Event
local ServerScriptService = game:GetService("ServerScriptService")

local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

-- Tabel yang diindeks secara numerik
local inventoryData = {
	"Pedang", "Busur"
}
-- Tabel kamus
local characterData = {
	CharName = "Diva Pembantai Naga",
	CharClass = "Penjahat"
}

-- Memicu event dengan tabel yang diindeks secara konsisten
bindableEvent:Fire(inventoryData)
bindableEvent:Fire(characterData)

Identitas Tabel

Tabel yang diberikan sebagai argumen untuk event dan callback yang dapat diikat disalin, yang berarti mereka tidak akan persis sama dengan yang diberikan saat memicu event atau memanggil callback. Demikian pula, tabel yang dikembalikan kepada pemanggil tidak akan persis sama dengan yang diberikan. Anda dapat menunjukkan ini dengan menjalankan skrip berikut pada BindableFunction dan mengamati bagaimana identitas tabel berbeda.

Koneksi Callback
local ServerScriptService = game:GetService("ServerScriptService")

local bindableFunction = ServerScriptService:WaitForChild("TestBindableFunction")

-- Fungsi callback
local function returnTable(passedTable)
	-- Keluarkan identitas tabel saat pemanggilan
	print(tostring(passedTable))  --> tabel: 0x48eb7aead27563d9
	return passedTable
end

-- Atur fungsi sebagai callback fungsi yang dapat diikat
bindableFunction.OnInvoke = returnTable

Pemanggilan Event
local ServerScriptService = game:GetService("ServerScriptService")

local bindableFunction = ServerScriptService:WaitForChild("TestBindableFunction")

local inventoryData = {
	"Pedang", "Busur"
}
-- Keluarkan identitas tabel asli
print(tostring(inventoryData))  --> tabel: 0x059bcdbb2b576549

local invokeReturn = bindableFunction:Invoke(inventoryData)

-- Keluarkan identitas tabel saat kembali
print(tostring(invokeReturn))  --> tabel: 0x9fcae7919563a0e9

Metatables

Jika sebuah tabel memiliki metatable, semua informasi metatable hilang dalam transfer. Dalam contoh kode berikut, properti NumWheels adalah bagian dari metatable Car. Ketika server menerima tabel berikut, tabel truck memiliki properti Name tetapi tidak memiliki properti NumWheels.

Koneksi Event
local ServerScriptService = game:GetService("ServerScriptService")

local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

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

-- Hubungkan fungsi ke event
bindableEvent.Event:Connect(onEvent)

Pemicu Event
local ServerScriptService = game:GetService("ServerScriptService")

local bindableEvent = ServerScriptService:WaitForChild("TestBindableEvent")

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

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

-- Memicu event dengan tabel termasuk metatable
bindableEvent:Fire(truck)