SetTeleportGui

Function of:

Description:

This function sets the custom ScreenGui|teleport GUI that will be shown to the local user during teleportation, prior to the teleport being invoked.

Note, the ScreenGui|teleport GUI will not be used if the destination place is in a different game. It will also not persist across multiple teleports and will need to be set prior to each one.

This function should only be used on the client. If the teleportation function is called from the server (as is the case with TeleportService/TeleportAsync) then this function should be called on the client prior to this. One way of doing this is listening to a RemoteEvent that fires several seconds before teleportation.

Loading screen

During a teleport, whilst the destination place is loading, the customLoadingScreen is parented to the CoreGui. Once the place has loaded the ScreenGui|loading screen is Instance/Parent|parented to nil.

This ScreenGui can be fetched at the destination place using TeleportService/GetArrivingTeleportGui, allowing you to parent it to the PlayerGui and perform your own transitions.

You are advised to also Instance/Parent|parent the ScreenGui to the PlayerGui in the start place whilst the teleport is initiating.

Studio Limitation

This service does not work during playtesting in Roblox Studio — To test aspects of your game using it, you must publish the game and play it in the Roblox application.

Parameters

Name	Type	Default	Description
Name gui	Type Instance	Default	Summary The loading `ScreenGui` that is to be displayed during teleportation

Returns

Return Type	Summary
Return Type void	Summary This function does not return anything!

Code Samples

Setting a teleport Gui

This snippet demonstrates how TeleportService can be used to teleport a player from the server.

It also shows how TeleportService/SetTeleportGui can be used to define a custom loading GUI. Note, this ScreenGui will need to be retrieved at the destination place using TeleportService/GetArrivingTeleportGui and be parented to the PlayerGui.

-- Client

-- Services
local TeleportService = game:GetService("TeleportService")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local player = Players.LocalPlayer
local PlayerGui = player:WaitForChild("PlayerGui")
local TeleportGui = Instance.new("ScreenGui") -- for demonstration purposes

-- This RemoteEvent needs to be created on the server and fired before teleporting
local TeleportEvent = ReplicatedStorage:WaitForChild("TeleportEvent")

-- Set the teleport Gui so we are ready
TeleportService:SetTeleportGui(TeleportGui)

TeleportEvent.OnClientEvent:Connect(function()
    -- Show the Gui prior to the teleport
    TeleportGui.Parent = PlayerGui
end)

-- Server

-- Services
local TeleportService = game:GetService("TeleportService")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

-- Create a RemoteEvent on the server to communicate with client
local TeleportEvent = Instance.new("RemoteEvent")
TeleportEvent.Name = "TeleportEvent"
TeleportEvent.Parent = ReplicatedStorage

teleportEvent:FireClient(player)
wait(5) -- Allow time for Gui to be displayed

-- Teleport the player (you will need player)
local teleportResult = TeleportService:TeleportAsync(game.PlaceId, {player})