mirror of
https://github.com/rojo-rbx/rojo.git
synced 2026-10-25 04:54:07 +00:00
update docs
This commit is contained in:
Joe
parent
0b1e8c89dc
commit
7b73720143
586 changed files with 5616 additions and 1325 deletions
|
|
@ -3,44 +3,80 @@ title: Teleport between places
|
|||
description: Explains how to use TeleportService to teleport users between different places in your experience.
|
||||
---
|
||||
|
||||
If you want to build an experience with many distinct places, such as a fantasy world with multiple towns, castles, dungeons, and a vast forest, you can use `Class.TeleportService` to enable users to teleport between places in a universe, servers, or even to another experience.
|
||||
Many experiences are subdivided into multiple [places](../production/publishing/publish-experiences-and-places.md#create-additional-places), such as a fantasy world with towns, castles, dungeons, and a vast forest. Use `Class.TeleportService` to teleport users between places, to different servers, or even to other experiences.
|
||||
|
||||
<Alert severity="warning">
|
||||
`Class.TeleportService` doesn't support playtesting in Roblox Studio. You must publish the experience and use it on the Roblox application for testing.
|
||||
`Class.TeleportService` doesn't support playtesting in Roblox Studio. You must publish the experience and test in the Roblox client.
|
||||
</Alert>
|
||||
|
||||
## Set up teleportation
|
||||
## Teleport players
|
||||
|
||||
To enable teleportation in your experience, use `Class.TeleportService:TeleportAsync()`. The method accepts three parameters:
|
||||
To teleport players, use `Class.TeleportService:TeleportAsync()`. This method accepts three parameters:
|
||||
|
||||
- The `Class.DataModel.PlaceId|PlaceId` for users to teleport to.
|
||||
- An array containing the `Class.Player` instances representing the users to teleport.
|
||||
- An array containing the `Class.Player` instances you want to teleport.
|
||||
- An optional `Class.TeleportOptions` instance that contains custom properties for the `Class.TeleportService:TeleportAsync()|TeleportAsync()` call.
|
||||
|
||||
```lua
|
||||
local Players = game:GetService("Players")
|
||||
local TeleportService = game:GetService("TeleportService")
|
||||
|
||||
local TARGET_PLACE_ID = 1234 -- replace with your own place ID
|
||||
|
||||
local TARGET_PLACE_ID = 12345678901234 -- replace with your own
|
||||
local playerToTeleport = Players:GetPlayers()[1] -- get the first user in the experience
|
||||
|
||||
TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport}, teleportOptions)
|
||||
TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport})
|
||||
```
|
||||
|
||||
<Alert severity="warning">
|
||||
You can only call `Class.TeleportService:TeleportAsync()|TeleportAsync()` from server-side scripts. This limitation reduces client-side exploitation. If necessary, you can call `Class.TeleportService:Teleport()|Teleport()` from client-side scripts, but `Class.TeleportService:TeleportAsync()|TeleportAsync()` is the recommended method.
|
||||
To get the appropriate players to teleport, you might use a `Class.BasePart.Touched` or a `Class.ProximityPrompt.Triggered` event to get an individual `Class.Player`. Then you can check if the player is part of a team (`Class.Player.Team`) or party (`Class.Player.PartyId`). Finally, you can use `Class.Team:GetPlayers()` or `Class.SocialService:GetPlayersByPartyId()` if you want to teleport the entire group rather than just the individual.
|
||||
|
||||
<Alert severity="info">
|
||||
To reduce client-side exploits, you can only call `Class.TeleportService:TeleportAsync()|TeleportAsync()` from server scripts. If necessary, client scripts can call `Class.TeleportService:Teleport()|Teleport()`, but we don't recommend it. For more information, see [Configure secure teleportation](#configure-secure-teleportation).
|
||||
</Alert>
|
||||
|
||||
If you want to take precautions of handling errors when setting up teleportation, see how to [handle failed teleports](#handle-failed-teleports).
|
||||
## Configure secure teleportation
|
||||
|
||||
### Enable cross experience teleportation
|
||||
Three settings handle teleport security.
|
||||
|
||||
For security purposes, teleporting a user from your experience to another experience owned by others fails by default. To enable cross experience teleportation, open the **Security** section of Studio's **File** ⟩ **Experience Settings** window and enable **Allow Third Party Teleports**.
|
||||
Setting | Description
|
||||
:--- | :---
|
||||
(Creator Dashboard) **Experience** > **Access Settings** > **Access Control for Places** | Controls whether players can join any place in your experience or must first join the [start place](../production/publishing/publish-experiences-and-places.md#create-experiences).
|
||||
(Creator Dashboard) **Place** > **Access** > **Direct Access Control** | Overrides your experience-level **Access Control for Places** setting for a non-start place.
|
||||
(Studio) **File** > **Experience Settings** > **Security** > **Allow Third Party Teleports** | Controls teleports from your experience to **experiences that you don't own**. You can leave this setting disabled and still teleport players between published experiences you own.
|
||||
|
||||
**Access Control for Places** controls players teleporting **into** your experience and is the most critical setting for preventing teleport-based exploits.
|
||||
|
||||
|
||||
|
||||
- If you choose **Fully open**, players can join any place in your experience through teleports from any experience, including deep links, game invites, joining a connection, and more.
|
||||
|
||||
This is a good choice if your experience has several places and you want friends to be able to easily join each other no matter which place they're in.
|
||||
|
||||
- If you choose **Limited to same universe**, players can only join non-start places through teleports within your experiences. This setting allows both client- and server-initiated teleports.
|
||||
|
||||
This is a good choice if you have a legacy experience that you don't want to [migrate to secure teleports](#migrate-to-secure-teleports).
|
||||
|
||||
- If you choose **Secure within universe only**, players can only join non-start places through server-initiated teleports within this experience.
|
||||
|
||||
This is a good choice if your experience has a strict progression system before players can access certain areas. It's also a good choice if your experience has a test place that players shouldn't have access to or for places that exclusively use reserved servers.
|
||||
|
||||
<Alert severity="success">
|
||||
Ultimately, your **Access Control for Places** setting depends on the type of experience you want to build. Many experiences don't need secure teleports.
|
||||
</Alert>
|
||||
|
||||
### Migrate to secure teleports
|
||||
|
||||
If you have an existing experience that uses client-side teleports and want to require server-initiated teleports, the goal is to move all teleport logic out of client scripts and into server scripts:
|
||||
|
||||
1. Find all client scripts that call `Class.TeleportService:Teleport()|Teleport()`.
|
||||
1. Change these calls to instead fire [remote events](../scripting/events/remote.md). Alternatively, you can change the calls to instead use `Class.ProximityPrompt|ProximityPrompts`, `Class.ClickDetector|ClickDetectors`, or even just the `Class.BasePart.Touched` event.
|
||||
1. Reimplement the teleport in a server script using `Class.TeleportService:TeleportAsync()|TeleportAsync()`.
|
||||
1. When no more `Class.TeleportService:Teleport()|Teleport()` calls exist, change **Access Control for Places** to **Secure**.
|
||||
|
||||
## Create custom teleport screens
|
||||
|
||||
When a user triggers a teleport, they see the standard Roblox loading screen as they wait for the new place to load in. You can add a custom teleport screen to improve immersion for users by calling `Class.TeleportService:SetTeleportGui()` on the client and pass through the `Class.ScreenGui` to use before teleporting the user. The following example sets a customized `Class.ScreenGui` located in `Class.ReplicatedStorage` as the loading screen when a teleport happens. It doesn't run any scripts inside of the `Class.ScreenGui`.
|
||||
When a user triggers a teleport, they see the standard Roblox loading screen as they wait for the new place to load. If desired, you can add a custom teleport screen by calling `Class.TeleportService:SetTeleportGui()` on the client.
|
||||
|
||||
The following example sets a customized `Class.ScreenGui` from `Class.ReplicatedStorage`. Any scripts within the `Class.ScreenGui` do **not** run.
|
||||
|
||||
```lua
|
||||
local TeleportService = game:GetService("TeleportService")
|
||||
|
|
@ -57,7 +93,7 @@ You can customize teleportations, such as [teleporting users to a specific serve
|
|||
|
||||
### Teleport to specific servers
|
||||
|
||||
To teleport users to specific servers, set the target server using `Class.TeleportOptions` and pass it to the `Class.TeleportService:TeleportAsync()` method. If you don't specify a server, users are teleported into a matchmade public server. The information of the first user in the list is used to matchmake to that public server.
|
||||
To teleport users to specific servers, set the target server using `Class.TeleportOptions` and pass it to the `Class.TeleportService:TeleportAsync()|TeleportAsync()` method. If you don't specify a server, users are teleported into a public server; the information of the first user in the list is used for matchmaking.
|
||||
|
||||
To teleport users to a specific public server, set the `Class.TeleportOptions.ServerInstanceId` property as a valid instance ID, which is a unique identifier for a public server.
|
||||
|
||||
|
|
@ -82,15 +118,11 @@ teleportOptions.ShouldReserveServer = true
|
|||
|
||||
### Send user data along with teleports
|
||||
|
||||
Teleporting a user between places discards any local data associated with that user. You can use the following approaches to handle data persistence between places.
|
||||
Teleporting a user between places discards any local data associated with that user. You can use the following approaches to handle data persistence between places:
|
||||
|
||||
- If your experience utilizes **secure** user data like in-experience currency or inventory, implement [data stores](../cloud-services/data-stores) or [memory stores](../cloud-services/memory-stores/index.md) to maintain data from place to place.
|
||||
|
||||
- To send basic **non-secure** data from place to place, call `Class.TeleportOptions:SetTeleportData()` before passing it to `Class.TeleportService:TeleportAsync()|TeleportAsync()`.
|
||||
|
||||
<Alert severity="warning">
|
||||
Don't pass secure data using `Class.TeleportOptions:SetTeleportData()` because it has the risk of exploitation.
|
||||
</Alert>
|
||||
- To send basic **non-secure** data from place to place, call `Class.TeleportOptions:SetTeleportData()` before passing it to `Class.TeleportService:TeleportAsync()|TeleportAsync()`. **Don't** pass secure data using this method; the data is visible to the client and unencrypted.
|
||||
|
||||
```lua
|
||||
local teleportData = {
|
||||
|
|
@ -101,7 +133,7 @@ local teleportOptions = Instance.new("TeleportOptions")
|
|||
teleportOptions:SetTeleportData(teleportData)
|
||||
```
|
||||
|
||||
To get all data of a user arriving from a teleport on the server, use the `Class.Player:GetJoinData()` function, which returns a dictionary including the data associated with the user.
|
||||
To retrieve all data when a user arrives at the new place after a teleport, use the `Class.Player:GetJoinData()` function, which returns a dictionary with a `TeleportData` key.
|
||||
|
||||
```lua
|
||||
local Players = game:GetService("Players")
|
||||
|
|
@ -111,7 +143,7 @@ local function onPlayerAdded(player)
|
|||
local teleportData = joinData.TeleportData
|
||||
local randomNumber = teleportData.randomNumber
|
||||
|
||||
print(player.Name .. "joined with the number" .. randomNumber)
|
||||
print(player.Name .. " joined with the number " .. randomNumber)
|
||||
end
|
||||
|
||||
Players.PlayerAdded:Connect(onPlayerAdded)
|
||||
|
|
@ -121,11 +153,11 @@ To retrieve only the teleport data on the client, you can use `Class.TeleportSer
|
|||
|
||||
## Handle failed teleports
|
||||
|
||||
Like any API call that involves network requests, teleports can fail and throw an error. Wrap them in protected calls (`Global.LuaGlobals.pcall()`). Some failures benefit from retries, particularly those involving reserved servers, so we recommend retrying some number of times on failures.
|
||||
Like any API call that involves network requests, teleports can fail and throw an error. Wrap them in protected calls (`Global.LuaGlobals.pcall()`). Some failures benefit from retries, particularly those involving reserved servers, so we recommend retrying some number of times on failure.
|
||||
|
||||
Even if a call succeeds and the teleport initiates, it can still fail at the last moment without throwing an error and leave the user in the server. When this happens, it triggers the `Class.TeleportService.TeleportInitFailed` event.
|
||||
|
||||
The following example `Class.ModuleScript` defines a `SafeTeleport` function to teleport the user in a protected call with retry logic. It also has a `handleFailedTeleport` function to deal with situations in which the call was successful, but the teleport didn't occur.
|
||||
The following example `Class.ModuleScript` returns a single `SafeTeleport` function that teleports players in a protected call with retry logic. It also has a `handleFailedTeleport` function to deal with situations in which the call was successful, but the teleport didn't occur.
|
||||
|
||||
```lua
|
||||
local TeleportService = game:GetService("TeleportService")
|
||||
|
|
@ -173,17 +205,24 @@ TeleportService.TeleportInitFailed:Connect(handleFailedTeleport)
|
|||
return SafeTeleport
|
||||
```
|
||||
|
||||
The `SafeTeleport` function receives the same arguments as the `Class.TeleportService:TeleportAsync()|TeleportAsync()` function. You can use the following `Class.ModuleScript` with the `SafeTeleport` function to perform teleports from anywhere in your experience to reduce failed teleports.
|
||||
The `SafeTeleport` function receives the same arguments as the `Class.TeleportService:TeleportAsync()|TeleportAsync()` function. You can use the following script with the `SafeTeleport` function to perform teleports from anywhere in your experience:
|
||||
|
||||
```lua
|
||||
local Players = game:GetService("Players")
|
||||
local TeleportService = game:GetService("TeleportService")
|
||||
local ServerScriptService = game:GetService("ServerScriptService")
|
||||
|
||||
local SafeTeleport = require(ServerScriptService.SafeTeleport)
|
||||
|
||||
local TARGET_PLACE_ID = 1818 -- replace with your own place ID
|
||||
local PLACE_TO_TELEPORT_TO = 12345678
|
||||
|
||||
local playerToTeleport = Players:GetPlayers()[1] -- get the first user in the game
|
||||
local function teleport(touchPart)
|
||||
local playerToTeleport = game.Players:GetPlayerFromCharacter(touchPart.Parent)
|
||||
|
||||
SafeTeleport(TARGET_PLACE_ID, {playerToTeleport}, teleportOptions)
|
||||
if playerToTeleport then
|
||||
SafeTeleport(PLACE_TO_TELEPORT_TO, {playerToTeleport})
|
||||
end
|
||||
end
|
||||
|
||||
script.Parent.Touched:Connect(teleport)
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue