Acara jarak jauh dan callback

Game Roblox adalah multiplayer secara default, jadi semua game secara inheren berkomunikasi antara server dan klien yang terhubung dengan pemain. Dalam kasus yang paling sederhana, saat pemain menggerakkan karakter mereka, properti Humanoid tertentu, seperti status, dikomunikasikan ke server, yang meneruskan informasi ini ke klien lain yang terhubung.

Acara jarak jauh dan callback memungkinkan Anda berkomunikasi melalui batas klien-server:

• RemoteEvents memungkinkan komunikasi satu arah (mengirim permintaan dan tidak menunggu respons).
• UnreliableRemoteEvents memungkinkan komunikasi satu arah untuk data yang berubah terus-menerus atau tidak kritis untuk status game. Acara ini mengorbankan urutan dan keandalan demi meningkatkan kinerja jaringan.
• RemoteFunctions memungkinkan komunikasi dua arah (mengirim permintaan dan menunggu hingga respons diterima dari penerima).

Berbeda dengan acara yang dapat diikat, yang memiliki utilitas yang lebih terbatas, kasus penggunaan untuk acara jarak jauh dan fungsi terlalu banyak untuk dicantumkan:

• Gameplay - Gameplay dasar, seperti seorang pemain mencapai akhir level, dapat memerlukan acara jarak jauh. Skrip klien memberi tahu server, dan skrip server mengatur ulang posisi pemain.
• Verifikasi server - Jika seorang pemain mencoba meminum ramuan, apakah mereka benar-benar memiliki ramuan itu? Untuk memastikan keadilan, server harus menjadi sumber kebenaran untuk sebuah game. Skrip klien dapat menggunakan acara jarak jauh untuk memberi tahu server bahwa pemain sedang meminum ramuan, dan kemudian skrip server dapat memutuskan apakah pemain benar-benar memiliki ramuan itu dan apakah akan memberikan manfaat.
• Pembaruan antarmuka pengguna - Saat status game berubah, skrip server dapat menggunakan acara jarak jauh untuk memberi tahu klien tentang perubahan skor, tujuan, dll.
• Pembelian di Marketplace dalam game - Untuk implementasi contoh yang menggunakan fungsi jarak jauh, lihat Pembelian langganan prompt.

Referensi cepat

Tabel berikut berfungsi sebagai referensi cepat tentang cara menggunakan RemoteEvents dan RemoteFunctions untuk berkomunikasi antara klien dan server.

Acara jarak jauh

Objek RemoteEvent memfasilitasi komunikasi satu arah yang asinkron di seluruh batas klien-server tanpa menunggu respons.

Untuk membuat RemoteEvent baru melalui jendela Explorer di Studio:

1. Arahkan kursor ke wadah tempat Anda ingin menyisipkan RemoteEvent. Untuk memastikan akses baik server maupun klien, itu harus berada di tempat yang dapat dilihat oleh kedua sisi, seperti ReplicatedStorage, meskipun dalam beberapa kasus adalah hal yang tepat untuk menyimpannya di Workspace atau di dalam Tool.
2. Klik tombol ⊕ yang muncul di sebelah kanan nama wadah dan sisipkan instance RemoteEvent.
3. Ganti nama instance untuk menggambarkan tujuannya.

Setelah Anda membuat RemoteEvent, itu dapat memfasilitasi komunikasi satu arah dari klien ke server, dari server ke klien, atau dari server ke semua klien.

Klien → server

Anda dapat menggunakan LocalScript untuk memicu acara di server dengan memanggil metode FireServer() pada RemoteEvent. Jika Anda mengirimkan argumen ke FireServer(), argumen tersebut akan diteruskan ke penangan acara di server dengan batasan tertentu. Perhatikan bahwa parameter pertama dari penangan acara di server selalu merupakan objek Player dari klien yang memanggilnya, dan parameter tambahan mengikuti.

Skrip Script berikut menghubungkan penangan acara ke OnServerEvent yang membuat Part baru di server. Skrip LocalScript yang menyertainya kemudian memanggil FireServer() pada instance RemoteEvent dengan Color dan Position yang diinginkan untuk bagian tersebut.

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Workspace = game:GetService("Workspace")

-- Dapatkan referensi ke instance acara jarak jauh
local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

local function onCreatePart(player, partColor, partPosition)
	print(player.Name .. " memicu RemoteEvent")
	local newPart = Instance.new("Part")
	newPart.Color = partColor
	newPart.Position = partPosition
	newPart.Parent = Workspace
end

-- Hubungkan fungsi ke acara
remoteEvent.OnServerEvent:Connect(onCreatePart)

local ReplicatedStorage = game:GetService("ReplicatedStorage")

-- Dapatkan referensi ke instance acara jarak jauh
local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

-- Memicu acara jarak jauh dan mengirimkan argumen tambahan
remoteEvent:FireServer(Color3.fromRGB(255, 0, 0), Vector3.new(0, 25, -20))

Server → klien

Anda dapat menggunakan Script untuk memicu acara di klien dengan memanggil metode FireClient() pada RemoteEvent. Argumen pertama untuk FireClient() adalah objek Player dari klien yang ingin Anda respons terhadap acara, dan argumen tambahan diteruskan ke klien dengan batasan tertentu. Perhatikan bahwa penangan acara tidak perlu menyertakan objek Player sebagai argumen pertamanya karena Anda dapat menentukan pemain di klien dengan Players.LocalPlayer.

Skrip LocalScript berikut menghubungkan penangan acara ke acara OnClientEvent. Skrip Script yang menyertainya kemudian mendengarkan pemain yang masuk ke server dan memanggil FireClient() untuk masing-masing dengan data sembarang.

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

-- Dapatkan referensi ke instance acara jarak jauh
local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

local player = Players.LocalPlayer

local function onNotifyPlayer(maxPlayers, respawnTime)
   print("[Klien] Acara diterima oleh pemain", player.Name)
   print(maxPlayers, respawnTime)
end

-- Hubungkan fungsi ke acara
remoteEvent.OnClientEvent:Connect(onNotifyPlayer)

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

-- Dapatkan referensi ke instance acara jarak jauh
local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

-- Mendengarkan pemain yang masuk dan mengirimkan acara jarak jauh ke masing-masing
local function onPlayerAdded(player)
   print("[Server] Memicu acara ke pemain", player.Name)
   remoteEvent:FireClient(player, Players.MaxPlayers, Players.RespawnTime)
end
Players.PlayerAdded:Connect(onPlayerAdded)

Server → semua klien

Anda dapat menggunakan Script untuk memicu acara di semua klien dengan memanggil metode FireAllClients() pada RemoteEvent. Berbeda dengan FireClient(), metode FireAllClients() tidak memerlukan objek Player karena itu memicu RemoteEvent ke semua klien.

Skrip LocalScript berikut menghubungkan penangan acara ke acara OnClientEvent yang mengeluarkan waktu hitung mundur yang tersisa. Skrip Script yang menyertainya kemudian memanggil FireAllClients() dalam loop setiap detik untuk memicu RemoteEvent untuk semua klien.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

-- Dapatkan referensi ke instance acara jarak jauh
local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

local function onTimerUpdate(seconds)
	print(seconds)
end

-- Hubungkan fungsi ke acara
remoteEvent.OnClientEvent:Connect(onTimerUpdate)

local ReplicatedStorage = game:GetService("ReplicatedStorage")

-- Dapatkan referensi ke instance acara jarak jauh
local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

local countdown = 5

-- Memicu RemoteEvent setiap detik hingga waktu habis
for timeRemaining = -1, countdown do
	remoteEvent:FireAllClients(countdown - timeRemaining)
	task.wait(1)
end

Callback jarak jauh

Objek RemoteFunction memfasilitasi komunikasi dua arah yang sinkron di seluruh batas klien-server. Pengirim fungsi jarak jauh akan menunggu hingga menerima respons dari penerima.

Untuk membuat RemoteFunction baru melalui jendela Explorer di Studio:

1. Arahkan kursor ke wadah tempat Anda ingin menyisipkan RemoteFunction. Untuk memastikan akses baik server maupun klien, itu harus berada di tempat yang dapat dilihat oleh kedua sisi, seperti ReplicatedStorage, meskipun dalam beberapa kasus adalah hal yang tepat untuk menyimpannya di Workspace atau di dalam Tool.
2. Klik tombol ⊕ yang muncul di sebelah kanan nama wadah dan sisipkan instance RemoteFunction.
3. Ganti nama instance untuk menggambarkan tujuannya.

Setelah Anda membuat RemoteFunction, itu dapat memfasilitasi komunikasi dua arah antara klien dan server atau antara server dan klien.

Klien → server → klien

Anda dapat menggunakan LocalScript untuk memanggil fungsi di server dengan memanggil metode InvokeServer() pada RemoteFunction. Berbeda dengan acara jarak jauh, LocalScript yang memanggil RemoteFunction akan menunggu hingga callback mengembalikan nilai. Argumen yang Anda kirimkan ke InvokeServer() akan diteruskan ke callback OnServerInvoke dari RemoteFunction dengan batasan tertentu. Perhatikan bahwa jika Anda mendefinisikan beberapa callback untuk RemoteFunction yang sama, hanya definisi terakhir yang akan dieksekusi.

Skrip Script berikut mendefinisikan fungsi callback melalui OnServerInvoke dan mengembalikan Part yang diminta melalui nilai return-nya. Skrip LocalScript yang menyertainya kemudian memanggil InvokeServer() dengan argumen tambahan yang mendefinisikan warna dan posisi bagian yang diminta.

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Workspace = game:GetService("Workspace")

-- Dapatkan referensi ke instance fungsi jarak jauh
local remoteFunction = ReplicatedStorage:FindFirstChildOfClass("RemoteFunction")

-- Fungsi callback
local function createPart(player, partColor, partPosition)
	print(player.Name .. " meminta bagian baru")
	local newPart = Instance.new("Part")
	newPart.Color = partColor
	newPart.Position = partPosition
	newPart.Parent = Workspace
	return newPart
end

-- Tetapkan fungsi sebagai callback fungsi jarak jauh
remoteFunction.OnServerInvoke = createPart

local ReplicatedStorage = game:GetService("ReplicatedStorage")

-- Dapatkan referensi ke instance fungsi jarak jauh
local remoteFunction = ReplicatedStorage:FindFirstChildOfClass("RemoteFunction")

-- Kirim warna dan posisi saat memanggil callback
local newPart = remoteFunction:InvokeServer(Color3.fromRGB(255, 0, 0), Vector3.new(0, 25, -20))

-- Keluarkan referensi bagian yang dikembalikan
print("Server telah membuat bagian yang diminta:", newPart)

Server → klien → server

Anda dapat menggunakan Script untuk memanggil fungsi di klien dengan memanggil metode InvokeClient() pada RemoteFunction, tetapi ini memiliki risiko serius sebagai berikut:

• Jika klien menghasilkan kesalahan, server juga akan menghasilkan kesalahan.
• Jika klien terputus saat sedang dipanggil, InvokeClient() akan menghasilkan kesalahan.
• Jika klien tidak mengembalikan nilai, server akan menunggu selamanya.

Untuk tindakan yang tidak memerlukan komunikasi dua arah, seperti memperbarui GUI, gunakan RemoteEvent dan berkomunikasi dari server ke klien.

Jaminan pengiriman

Setiap jenis jarak jauh membuat janji yang berbeda tentang apakah pesan tiba dan dalam urutan apa. Janji ini hanya berlaku untuk satu koneksi dalam satu arah, artinya dari server ke satu klien tertentu, atau dari satu klien tertentu ke server.

RemoteEvents

RemoteEvents dapat diandalkan dan terurut:

• Jika pesan hilang dalam perjalanan, Roblox mengirimkannya kembali hingga tiba, selama penerima tetap terhubung.
• Pesan tiba dalam urutan Anda memicunya, termasuk di seluruh instance RemoteEvent yang berbeda. Misalnya, jika server memicu acara A, kemudian B, kemudian A lagi ke klien yang sama, klien tersebut menerima A, B, A. Ini berlaku baik Anda menggunakan FireClient() atau FireAllClients().
• Jika klien memicu acara lebih cepat daripada batas throttling, server memproses acara yang berlebih nanti alih-alih menjatuhkannya, dan mereka mempertahankan urutannya.

Pesan yang dapat diandalkan dan terurut masih dapat gagal mencapai kode Anda dalam kasus berikut:

• Tidak ada penangan yang terhubung. Jika tidak ada yang terhubung ke OnServerEvent atau OnClientEvent saat pesan tiba, Roblox mengantri dan mengirimkannya, dalam urutan, segera setelah penangan terhubung. Antrian dibatasi dalam jumlah dan memori. Setelah penuh, Roblox membuang pesan lebih lanjut dan mencatat kesalahan Remote event invocation di jendela Output.
• Penerima terputus. Pesan yang belum dikirim saat klien meninggalkan akan hilang.

Urutan berlaku untuk saat setiap penangan dimulai, bukan saat selesai. Jika penangan menunggu, seperti dengan memanggil task.wait() atau WaitForChild(), Roblox dapat mulai menangani pesan berikutnya sebelum penangan sebelumnya dilanjutkan.

RemoteFunctions

RemoteFunctions mengirimkan pemanggilan dan respons dengan andal, jadi Roblox mengirim ulang pesan yang hilang selama kedua sisi tetap terhubung. Karena InvokeServer() dan InvokeClient() menunggu hingga respons tiba, satu utas tidak dapat memiliki lebih dari satu pemanggilan yang sedang berlangsung. Utas terpisah dapat memanggil secara bersamaan, meskipun, dan jika callback menunggu, respons dapat kembali dalam urutan yang berbeda dari pemanggilan yang dikirim.

Jika tidak ada callback yang ditetapkan untuk OnServerInvoke atau OnClientInvoke, Roblox mengantri pemanggilan hingga satu ada. Antrian ini memiliki batasan yang sama dengan antrian RemoteEvent.

UnreliableRemoteEvents

UnreliableRemoteEvents tidak menjamin pengiriman maupun urutan. Mereka juga tidak memiliki hubungan urutan dengan RemoteEvents atau RemoteFunctions. Roblox mungkin menjatuhkan pesan dalam salah satu kasus berikut, tanpa mengirim ulang:

• Pesan hilang dalam perjalanan.
• Jaringan macet dan pesan menunggu terlalu lama untuk dikirim.
• Payload lebih besar dari 1.000 byte.
• Klien memicu lebih cepat daripada batas throttling. Berbeda dengan RemoteEvent, server menjatuhkan pesan yang berlebih alih-alih menundanya.
• Tidak ada yang terhubung ke OnServerEvent atau OnClientEvent saat pesan tiba. Berbeda dengan RemoteEvent, Roblox langsung membuang pesan alih-alih mengantrinya.

Roblox juga tidak menunggu pesan sebelumnya tiba sebelum memproses pesan yang lebih baru, jadi pesan dapat tiba di luar urutan. Jika urutan penting, sertakan cap waktu atau nomor urutan di setiap pesan dan abaikan pesan yang lebih lama dari yang terbaru yang telah Anda tangani.

Throttling dan batas ukuran

Pesan dari klien ke server tunduk pada batas laju yang dibagikan setiap jenis jarak jauh di seluruh semua instance-nya. Untuk batas saat ini, lihat bagian Throttling dari RemoteEvent dan batas payload di UnreliableRemoteEvent.

Batasan argumen

Saat Anda memicu RemoteEvent atau memanggil RemoteFunction, itu meneruskan argumen apa pun yang Anda kirimkan dengan acara atau ke fungsi callback. Jenis objek Roblox apa pun seperti Enum, Instance, atau lainnya dapat diteruskan, serta tipe Luau seperti angka, string, dan boolean, meskipun Anda harus dengan hati-hati menjelajahi batasan berikut.

Indeks non-string

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

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

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

-- Hubungkan fungsi ke acara
remoteEvent.OnClientEvent:Connect(onEventFire)

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")
local Workspace = game:GetService("Workspace")

local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

-- Mendengarkan pemain yang masuk dan mengirimkan acara jarak jauh ke masing-masing
local function onPlayerAdded(player)
	remoteEvent:FireClient(player,
		{
			[Workspace.Baseplate] = true
		}
	)
end
Players.PlayerAdded:Connect(onPlayerAdded)

Fungsi yang diteruskan

Fungsi yang disertakan sebagai argumen untuk RemoteEvent atau RemoteFunction tidak akan direplikasi di seluruh batas klien-server, sehingga tidak mungkin untuk mengirim fungsi secara jarak jauh. Sebagai gantinya, argumen yang dihasilkan di sisi penerima akan menjadi nil.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

local function onClientEvent(func)
	print(func)  --> nil
end

remoteEvent.OnClientEvent:Connect(onClientEvent)

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

local function testFunction()
	print("Hello world!")
end

-- Memicu acara jarak jauh dengan fungsi sebagai argumen
remoteEvent:FireAllClients(testFunction)

Indeks tabel

Jika Anda mengirimkan tabel data, jangan mengirimkan tabel campuran dengan kunci numerik dan string. Sebagai gantinya, kirimkan tabel yang terdiri sepenuhnya dari pasangan kunci-nilai (kamus) atau sepenuhnya dari indeks numerik.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

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

-- Hubungkan fungsi ke acara
remoteEvent.OnServerEvent:Connect(onEventFire)

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

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

remoteEvent:FireServer(inventoryData)
remoteEvent:FireServer(characterData)

Identitas tabel

Tabel yang diteruskan sebagai argumen ke acara jarak jauh/callback disalin, artinya mereka tidak akan persis sama dengan yang diberikan saat memicu acara atau memanggil callback. Begitu juga tabel yang dikembalikan kepada pemanggil tidak akan persis sama dengan yang diberikan. Anda dapat menunjukkan ini dengan menjalankan skrip berikut pada RemoteFunction dan mengamati bagaimana identitas tabel berbeda.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteFunction = ReplicatedStorage:FindFirstChildOfClass("RemoteFunction")

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

-- Tetapkan fungsi sebagai callback fungsi jarak jauh
remoteFunction.OnServerInvoke = returnTable

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteFunction = ReplicatedStorage:FindFirstChildOfClass("RemoteFunction")

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

local invokeReturn = remoteFunction:InvokeServer(inventoryData)

-- Keluarkan identitas tabel saat kembali
print(tostring(invokeReturn))  --> table: 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.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

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

-- Hubungkan fungsi ke acara
remoteEvent.OnServerEvent:Connect(onEvent)

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

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

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

-- Memicu acara dengan tabel yang menyertakan metatable
remoteEvent:FireServer(truck)

Instance yang tidak direplikasi

Jika sebuah RemoteEvent atau RemoteFunction mengirimkan nilai yang hanya terlihat oleh pengirim, Roblox tidak mereplikasinya di seluruh batas klien-server dan mengirimkan nil sebagai gantinya. Misalnya, jika sebuah Script mengirimkan keturunan dari ServerStorage, klien yang mendengarkan acara akan menerima nilai nil karena objek itu tidak dapat direplikasi untuk klien.

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ServerStorage = game:GetService("ServerStorage")
local Players = game:GetService("Players")

local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

-- Akan diterima sebagai "nil" karena klien tidak dapat mengakses ServerStorage
local storedPart = Instance.new("Part")
storedPart.Parent = ServerStorage

local function onPlayerAdded(player)
	remoteEvent:FireClient(player, storedPart)
end
Players.PlayerAdded:Connect(onPlayerAdded)

Demikian pula, jika Anda membuat sebuah bagian dalam LocalScript dan mencoba mengirimkannya ke Script, server akan melihat nil karena bagian tersebut tidak dapat direplikasi untuk server.

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Workspace = game:GetService("Workspace")

local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

-- Akan diterima sebagai "nil" karena server tidak mengetahui bagian ini
local clientPart = Instance.new("Part")
clientPart.Parent = Workspace

remoteEvent:FireServer(clientPart)