Événements et rappels à distance

Les expériences Roblox sont multijoueurs par défaut, de sorte que toutes les expériences communiquent par défaut entre le serveur et les clients connectés des joueurs.Dans le cas le plus simple, lorsque les joueurs déplacent leurs personnages, certaines propriétés Humanoid telles que les états sont communiquées au serveur, qui transmet cette information à d'autres clients connectés.

Les événements et les rappels à distance vous permettent de communiquer à travers la frontière client-serveur :

• RemoteEvents activer la communication unilatérale (en envoyant une demande et ne pas céder pour une réponse).
• UnreliableRemoteEvents activer la communication unidirectionnelle pour les données qui changent en continu ou ne sont pas critiques pour l'état du jeu.Ces événements échangent l'ordre d'achat et la fiabilité pour améliorer les performances réseau.
• RemoteFunctions activer la communication en deux sens (en envoyant une demande et en cédant jusqu'à ce qu'une réponse soit reçue du destinataire).

Contrairement aux événements bindables, qui ont une utilité plus limitée, les cas d'utilisation pour les événements et les fonctions à distance sont trop nombreux pour être listés :

• Jeu - Le partiede base, comme un joueur atteignant la fin d'un niveau, peut nécessiter un événement distant.Un script client informe le serveur, et les scripts du serveur réinitialisent la position du joueur.
• Vérification du serveur - Si un joueur essaie de boire une potion, a-t-il réellement cette potion ? Pour garantir l'équité, le serveur doit être la source de vérité pour une expérience.Un script client peut utiliser un événement distant pour informer le serveur que le joueur boit une potion, puis les scripts du serveur peuvent décider si le joueur a réellement cette potion et s'il doit en conférer des avantages.
• Mises à jour de l'interface utilisateur - Comme l'état du jeu change, les scripts du serveur peuvent utiliser des événements à distance pour informer les clients des modifications des scores, des objectifs, etc.
• Achats sur le marché expérimental - Pour une implémentation d'exemple qui utilise des fonctions à distance, voir achats d'abonnement rapides .

Référence rapide

Les tables suivantes servent de référence rapide pour savoir comment utiliser RemoteEvents et RemoteFunctions pour communiquer entre le client et le serveur.

Événements à distance

Un objet RemoteEvent asynchrone facilite la communication unilatérale à travers la frontière client-serveur sans produire de réponse.

Pour créer un nouveau RemoteEvent via la fenêtre Explorateur dans Studio :

1. Passez la souris sur le conteneur dans lequel vous voulez insérer le RemoteEvent .Afin de garantir l'accès du serveur et du client, il doit être dans un endroit où les deux parties peuvent le voir, comme ReplicatedStorage , bien que dans certains cas, il soit approprié de le stocker dans Workspace ou à l'intérieur d'un Tool .
2. Cliquez sur le bouton ⊕ qui apparaît à droite du nom du conteneur et insérez une instance Événement distant .
3. Renommez l'instance pour décrire son but.

Une fois que vous avez créé un RemoteEvent , il peut faciliter la communication unilatérale du client au serveur , du serveur au client ou du serveur à tous les clients.

>

>

>

Client → serveur

Vous pouvez utiliser un LocalScript pour déclencher un événement sur le serveur en appelant la méthode FireServer() sur un RemoteEvent.Si vous transmettez des arguments à FireServer() , ils passent au gestionnaire d'événements sur le serveur avec certaines limitations .Notez que le premier paramètre du gestionnaire d'événements sur le serveur est toujours l'objet Player du client qui l'appelle, et des paramètres supplémentaires s'abonner.

Le suivant Script connecte un gestionnaire d'événements à OnServerEvent qui crée un nouveau Part sur le serveur.L'accompagnement LocalScript appelle ensuite FireServer() sur l'instance RemoteEvent avec le désiré Color et Position pour la partie.

Connexion d'événement - Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Workspace = game:GetService("Workspace")

-- Obtenir une référence à l'instance d'événement à distance
local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

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

-- Fonction de connexion à l'événement
remoteEvent.OnServerEvent:Connect(onCreatePart)

Tir d'événement - LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")

-- Obtenir une référence à l'instance d'événement à distance
local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

-- Lancez l'événement distant et passez des arguments supplémentaires
remoteEvent:FireServer(Color3.fromRGB(255, 0, 0), Vector3.new(0, 25, -20))

Serveur → client

Vous pouvez utiliser un Script pour déclencher un événement sur un client en appelant la méthode FireClient() sur un RemoteEvent .Le premier argument pour est l'objet du client auquel vous souhaitez répondre à l'événement, et des arguments supplémentaires sont transmis au client avec certaines restrictions .Notez que le gestionnaire d'événements n'a pas besoin d'inclure l'objet Player comme premier argument car vous pouvez déterminer le joueur sur le client avec Players.LocalPlayer .

Le suivant LocalScript connecte un gestionnaire d'événements à l'événement OnClientEvent.L'accompagnant Script écoute ensuite les joueurs entrants vers le serveur et appelle FireClient() pour chacun avec des données arbitraires.

Connexion d'événement - LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

-- Obtenir une référence à l'instance d'événement à distance
local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

local player = Players.LocalPlayer

local function onNotifyPlayer(maxPlayers, respawnTime)
   print("[Client] Event received by player", player.Name)
   print(maxPlayers, respawnTime)
end

-- Fonction de connexion à l'événement
remoteEvent.OnClientEvent:Connect(onNotifyPlayer)

Tir d'événement - Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

-- Obtenir une référence à l'instance d'événement à distance
local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

-- Écouter les joueurs entrants et envoyer un événement distant à chacun
local function onPlayerAdded(player)
   print("[Server] Firing event to player", player.Name)
   remoteEvent:FireClient(player, Players.MaxPlayers, Players.RespawnTime)
end
Players.PlayerAdded:Connect(onPlayerAdded)

Serveur → tous les clients

Vous pouvez utiliser un Script pour déclencher un événement sur tous les clients en appelant la méthode FireAllClients() sur un RemoteEvent .Contrairement à FireClient() , la méthode FireAllClients() n'exige pas d'objet Player car elle lance le RemoteEvent à tous les clients.

Le suivant LocalScript connecte un gestionnaire d'événements à l'événement OnClientEvent qui produit un temps de compte à rebours restant.L'accompagnement Script appelle ensuite FireAllClients() dans une boucle toutes les secondes pour déclencher le RemoteEvent pour tous les clients.

Connexion d'événement - LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")

-- Obtenir une référence à l'instance d'événement à distance
local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

local function onTimerUpdate(seconds)
	print(seconds)
end

-- Fonction de connexion à l'événement
remoteEvent.OnClientEvent:Connect(onTimerUpdate)

Tir d'événement - Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

-- Obtenir une référence à l'instance d'événement à distance
local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

local countdown = 5

-- Tirer l'événement distant toutes les secondes jusqu'à l'expiration du temps
for timeRemaining = -1, countdown do
	remoteEvent:FireAllClients(countdown - timeRemaining)
	task.wait(1)
end

Appels de rappel à distance

Un objet RemoteFunction facilite la communication synchronique, deux sens, à travers la frontière client-serveur.L'expéditeur d'une fonction à distance produira jusqu'à ce qu'il reçoive une réponse du destinataire.

Pour créer un nouveau RemoteFunction via la fenêtre Explorateur dans Studio :

1. Passez la souris sur le conteneur dans lequel vous voulez insérer le RemoteFunction .Afin de garantir l'accès du serveur et du client, il doit être dans un endroit où les deux parties peuvent le voir, comme ReplicatedStorage , bien que dans certains cas, il soit approprié de le stocker dans Workspace ou à l'intérieur d'un Tool .
2. Cliquez sur le bouton ⊕ qui apparaît à droite du nom du conteneur et insérez une instance RemoteFunction .
3. Renommez l'instance pour décrire son but.

Une fois que vous avez créé un RemoteFunction , il peut faciliter la communication entre client et serveur ou entre serveur et client .

>

>

Client → serveur → client

Vous pouvez utiliser un LocalScript pour appeler une fonction sur le serveur en appelant la méthode InvokeServer() sur un RemoteFunction.Contrairement à un événement distant , le qui invoque le rend jusqu'à ce que le rappel soit retourné.Les arguments que vous passez à InvokeServer() passent au rappel de OnServerInvoke du RemoteFunction avec certaines limitations .Notez que si vous définissez plusieurs rappels à la même RemoteFunction, seule la dernière définition s'exécute.

La fonction de rappel suivante Script définit la fonction de rappel via OnServerInvoke et renvoie la demande Part via sa valeur return.L'accompagnement LocalScript appelle ensuite InvokeServer() avec des arguments supplémentaires définissant la couleur et la position de la partie demandée.

Connexion de rappel - Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Workspace = game:GetService("Workspace")

-- Obtenir une référence à l'instance de fonction à distance
local remoteFunction = ReplicatedStorage:FindFirstChildOfClass("RemoteFunction")

-- Fonction de rappel
local function createPart(player, partColor, partPosition)
	print(player.Name .. " requested a new part")
	local newPart = Instance.new("Part")
	newPart.Color = partColor
	newPart.Position = partPosition
	newPart.Parent = Workspace
	return newPart
end

-- Définir la fonction comme rappel de fonction à distance
remoteFunction.OnServerInvoke = createPart

Invocation d'événement - LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")

-- Obtenir une référence à l'instance de fonction à distance
local remoteFunction = ReplicatedStorage:FindFirstChildOfClass("RemoteFunction")

-- Passez une couleur et une position lors de l'invocation du rappel
local newPart = remoteFunction:InvokeServer(Color3.fromRGB(255, 0, 0), Vector3.new(0, 25, -20))

-- Afficher la référence de pièce retournée
print("The server created the requested part:", newPart)

Serveur → client → serveur

Vous pouvez utiliser un Script pour appeler une fonction sur le client en appelant la méthode InvokeClient() sur un RemoteFunction, mais il a des risques sérieux comme suit :

• Si le client lance une erreur, le serveur lance également l'erreur.
• Si le client se déconnecte pendant qu'il est invoqué, InvokeClient() lance une erreur.
• Si le client ne renvoie pas de valeur, le serveur produit à jamais.

Pour les actions qui ne nécessitent pas de communications en sens inverse, telles que la mise à jour d'une interface utilisateur graphique, utilisez un RemoteEvent et communiquez du serveur au client .

Limites d'argumentation

Lorsque vous tirez un RemoteEvent ou que vous invoquez un RemoteFunction, il transmet tous les arguments que vous passez avec l'événement ou à la fonction de rappel.Tout type d'objet Roblox tel qu'un Enum , Instance ou d'autres peut être passé, ainsi que les types Luau tels que les nombres, les chaînes et les bouleaux, bien que vous deviez explorer soigneusement les limites suivantes.

Index non-texte

Si aucun indice d'une table passée n'est de type chaîne comme un Instance, données utilisateur, ou fonction, Roblox convertit automatiquement ces index en chaîne.

Connexion d'événement - LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

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

-- Fonction de connexion à l'événement
remoteEvent.OnClientEvent:Connect(onEventFire)

Tir d'événement - Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")
local Workspace = game:GetService("Workspace")

local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

-- Écouter les joueurs entrants et envoyer un événement distant à chacun
local function onPlayerAdded(player)
	remoteEvent:FireClient(player,
		{
			[Workspace.Baseplate] = true
		}
	)
end
Players.PlayerAdded:Connect(onPlayerAdded)

Fonctions passées

Les fonctions incluses en tant qu'arguments pour un ou seront non répliquées à travers la frontière client-serveur, ce qui rend impossible de passer des fonctions à distance.Au lieu de cela, l'argument résultant du côté récepteur sera nil .

Connexion d'événement - LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

local function onClientEvent(func)
	print(func)  --> zéro
end

remoteEvent.OnClientEvent:Connect(onClientEvent)

Tir d'événement - Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

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

-- Événement à distance de feu avec une fonction en tant qu'argument
remoteEvent:FireAllClients(testFunction)

Indexation de table

Si vous passez une table de données, ne passez pas une table mixte de clés numériques et de chaînes.Au lieu de cela, passez une table qui se compose entièrement de paires clé-valeur (dictionnaire) ou entièrement d'index numériques.

Connexion d'événement - Script
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 = Épée
		--> 2 = Arc
		--> CharName = Diviseur de dragons Diva
		--> CharClass = Voleur
	end
end

-- Fonction de connexion à l'événement
remoteEvent.OnServerEvent:Connect(onEventFire)

Tir d'événement - LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

-- Table numérotée indexée
local inventoryData = {
	"Sword", "Bow"
}
-- Tableau de dictionnaire
local characterData = {
	CharName = "Diva Dragonslayer",
	CharClass = "Rogue"
}

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

Identités de table

Les tables transmises en tant qu'arguments à des événements/appels à distance sont copiées, ce qui signifie qu'elles ne seront pas exactement équivalentes à celles fournies lors du tir de l'événement ou de l'invocation de l'rappel.Les tables retournées à l'invocateur ne seront pas exactement équivalentes à celles fournies.Vous pouvez le démontrer en exécutant le script suivant sur un RemoteFunction et en observant comment les identités de table diffèrent.

Connexion de rappel - Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteFunction = ReplicatedStorage:FindFirstChildOfClass("RemoteFunction")

-- Fonction de rappel
local function returnTable(player, passedTable)
	-- Identité de table de sortie lors de l'invocation
	print(tostring(passedTable))  --> table : 0x48eb7aead27563d9
	return passedTable
end

-- Définir la fonction comme rappel de fonction à distance
remoteFunction.OnServerInvoke = returnTable

Invocation d'événement - LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteFunction = ReplicatedStorage:FindFirstChildOfClass("RemoteFunction")

local inventoryData = {
	"Sword", "Bow"
}
-- Identité de table d'origine de sortie
print(tostring(inventoryData))  --> table : 0x059bcdbb2b576549

local invokeReturn = remoteFunction:InvokeServer(inventoryData)

-- Identité de table de sortie lors du renvoyer
print(tostring(invokeReturn))  --> table: 0x9fcae7919563a0e9

Tableaux métriques

Si une table a un métadonnées, toutes les informations métadonnées sont perdues lors de la transmission.Dans l'exemple de code suivant, la propriété NumWheels fait partie du Car métatable.Lorsque le serveur reçoit la table suivante, la table a la propriété mais pas la propriété .

Connexion d'événement - Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

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

-- Fonction de connexion à l'événement
remoteEvent.OnServerEvent:Connect(onEvent)

Tir d'événement - LocalScript
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)

-- Événement de feu avec table incluant une métatable
remoteEvent:FireServer(truck)

Instances non répliquées

Si un RemoteEvent ou RemoteFunction passe une valeur qui n'est visible que pour l'expéditeur, Roblox ne la réplique pas à travers la frontière client-serveur et passe nil à la place de la valeur.Par exemple, si un Script passe un descendant de ServerStorage , le client qui écoute l'événement recevra une valeur nil car cet objet n'est pas réplicable pour le client.

Tir d'événement - Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ServerStorage = game:GetService("ServerStorage")
local Players = game:GetService("Players")

local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

-- Sera reçu comme "néant" car le client ne peut pas accéder à ServerStorage
local storedPart = Instance.new("Part")
storedPart.Parent = ServerStorage

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

De même, si vous créez une partie dans un LocalScript et essayez de la transmettre à un Script , le serveur verra nil parce que la partie n'est pas réplicable pour le serveur.

Tir d'événement - LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Workspace = game:GetService("Workspace")

local remoteEvent = ReplicatedStorage:FindFirstChildOfClass("RemoteEvent")

-- Sera reçu comme "néant" car le serveur ne sait pas à propos de cette partie
local clientPart = Instance.new("Part")
clientPart.Parent = Workspace

remoteEvent:FireServer(clientPart)