roblox-teleport-matchmaking

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Teleports, places, and matchmaking

传送、地点与匹配

Structure

结构

A universe (experience) contains a start place plus sub-places. All places share DataStores, MemoryStores, MessagingService, developer products, and passes.
Typical layouts: Lobby (start place) → Match place (reserved servers) → back to Lobby; or a hub with separate world places. Keep shared code in packages or a shared Rojo tree.
Access Control for Places (Creator Dashboard):
```
Fully open
```
,
```
Limited to same universe
```
, or Secure within universe only
(only server-initiated teleports into non-start places — recommended for progression gates and test places). Clients can otherwise teleport themselves anywhere in the universe.

一个 universe（体验）包含一个起始 place 和多个子 place。所有 place 共享 DataStores、MemoryStores、MessagingService、开发者产品和 passes。
典型布局：Lobby（起始 place）→ Match place（保留服务器）→ 返回 Lobby；或者使用一个 hub，并搭配独立的 world places。将共享代码放在 packages 或共享的 Rojo tree 中。
Access Control for Places（Creator Dashboard）：
```
Fully open
```
、
```
Limited to same universe
```
，或 Secure within universe only
（仅允许由服务器发起到非起始 place 的传送——建议用于进度门槛和测试 place）。否则，客户端可以自行传送到 universe 中的任意 place。

Teleporting (server)

服务端传送

luau

--!strict
local TeleportService = game:GetService("TeleportService")

local ATTEMPTS = 5
local RETRY_DELAY = 1
local FLOOD_DELAY = 15

local function safeTeleport(placeId: number, players: { Player }, options: TeleportOptions?): (boolean, any)
	local ok: boolean, result: any = false, nil
	for _ = 1, ATTEMPTS do
		ok, result = pcall(function()
			return TeleportService:TeleportAsync(placeId, players, options)
		end)
		if ok then
			break
		end
		task.wait(RETRY_DELAY)
	end
	if not ok then
		warn("Teleport failed:", result)
	end
	return ok, result
end

-- A teleport can still fail after TeleportAsync succeeds: retry transient failures.
TeleportService.TeleportInitFailed:Connect(function(player, teleportResult, errorMessage, placeId, options)
	if teleportResult == Enum.TeleportResult.Flooded then
		task.wait(FLOOD_DELAY)
	elseif teleportResult == Enum.TeleportResult.Failure then
		task.wait(RETRY_DELAY)
	else
		warn(`Invalid teleport [{teleportResult.Name}]: {errorMessage}`)
		return
	end
	safeTeleport(placeId, { player }, options)
end)

return safeTeleport

TeleportOptions

```
ShouldReserveServer = true
```
→ a new reserved server (private, only reachable by access code) — ideal for matches, dungeons, and parties. Returns
```
TeleportAsyncResult
```
with
```
ReservedServerAccessCode
```
and
```
PrivateServerId
```
.
```
ReservedServerAccessCode = code
```
→ join an existing reserved server (from
```
ReserveServerAsync(placeId)
```
or a previous result).
```
ServerInstanceId = jobId
```
→ a specific public server (e.g. "join friend's server").
```
SetTeleportData(table)
```
→ non-secure data readable on arrival with
```
player:GetJoinData().TeleportData
```
(server) or
```
TeleportService:GetLocalPlayerTeleportData()
```
(client). Clients can tamper with it: never trust it for currency, items, or permissions — use DataStores/MemoryStores keyed by user ID or by the reserved server's
```
PrivateServerId
```
.

Deprecated:

Teleport

TeleportToPlaceInstance

TeleportToPrivateServer

TeleportPartyAsync

TeleportToSpawnByName

ReserveServer

→

TeleportAsync

TeleportOptions

ReserveServerAsync

luau

--!strict
local TeleportService = game:GetService("TeleportService")

local ATTEMPTS = 5
local RETRY_DELAY = 1
local FLOOD_DELAY = 15

local function safeTeleport(placeId: number, players: { Player }, options: TeleportOptions?): (boolean, any)
	local ok: boolean, result: any = false, nil
	for _ = 1, ATTEMPTS do
		ok, result = pcall(function()
			return TeleportService:TeleportAsync(placeId, players, options)
		end)
		if ok then
			break
		end
		task.wait(RETRY_DELAY)
	end
	if not ok then
		warn("Teleport failed:", result)
	end
	return ok, result
end

-- A teleport can still fail after TeleportAsync succeeds: retry transient failures.
TeleportService.TeleportInitFailed:Connect(function(player, teleportResult, errorMessage, placeId, options)
	if teleportResult == Enum.TeleportResult.Flooded then
		task.wait(FLOOD_DELAY)
	elseif teleportResult == Enum.TeleportResult.Failure then
		task.wait(RETRY_DELAY)
	else
		warn(`Invalid teleport [{teleportResult.Name}]: {errorMessage}`)
		return
	end
	safeTeleport(placeId, { player }, options)
end)

return safeTeleport

TeleportOptions

：

```
ShouldReserveServer = true
```
→ 创建一个新的 reserved server（保留服务器，私有，只能通过访问码进入）——非常适合比赛、副本和组队。返回
```
TeleportAsyncResult
```
，其中包含
```
ReservedServerAccessCode
```
和
```
PrivateServerId
```
。
```
ReservedServerAccessCode = code
```
→ 加入现有的 reserved server（来自
```
ReserveServerAsync(placeId)
```
或之前的结果）。
```
ServerInstanceId = jobId
```
→ 指定的公开服务器（例如“加入好友的服务器”）。
```
SetTeleportData(table)
```
→ 到达后可读取的非安全数据，可通过
```
player:GetJoinData().TeleportData
```
（服务端）或
```
TeleportService:GetLocalPlayerTeleportData()
```
（客户端）获取。客户端可以篡改这些数据：绝不能将其用于货币、物品或权限校验——应使用以 user ID 或 reserved server 的
```
PrivateServerId
```
为键的 DataStores/MemoryStores。

已弃用：

Teleport

、

TeleportToPlaceInstance

、

TeleportToPrivateServer

、

TeleportPartyAsync

、

TeleportToSpawnByName

、

ReserveServer

→ 改用

TeleportAsync

TeleportOptions

ReserveServerAsync

。

Data handoff between places

地点之间的数据交接

Save the player's data before teleporting (ProfileStore: end the session / wait for save).
The destination loads with session locking (ProfileStore retries while the old server releases).
For match parameters (mode, map, team assignments), write a MemoryStore/DataStore entry keyed by the reserved server's
```
PrivateServerId
```
(or the access code) before teleporting; the match server reads
```
game.PrivateServerId
```
on start and loads its config.
On arrival,
```
TeleportService:SetTeleportGui(gui)
```
(client, before teleport) keeps a loading screen up across the transition; use
```
ReplicatedFirst
```
loading screens on arrival.

在传送前保存玩家数据（ProfileStore：结束会话/等待保存完成）。
目标 place 在会话锁定机制下加载（ProfileStore 会持续重试，直到旧服务器释放锁）。
对于比赛参数（模式、地图、队伍分配），在传送前将一条 MemoryStore/DataStore 记录写入，以 reserved server 的
```
PrivateServerId
```
（或访问码）为键；比赛服务器启动时读取
```
game.PrivateServerId
```
并加载其配置。
到达后，
```
TeleportService:SetTeleportGui(gui)
```
（客户端，在传送前调用）可让加载界面在场景切换期间保持显示；到达后使用
```
ReplicatedFirst
```
加载界面。

Detecting server type

检测服务器类型

Server	`game.PrivateServerId`	`game.PrivateServerOwnerId`
Public	`""`	`0`
Reserved ( `ReserveServerAsync` / `ShouldReserveServer` )	non-empty	`0`
Private (VIP) server	non-empty	owner's user id

服务器	`game.PrivateServerId`	`game.PrivateServerOwnerId`
公开	`""`	`0`
Reserved（ `ReserveServerAsync` / `ShouldReserveServer` ）	非空	`0`
Private（VIP）服务器	非空	所有者的 user id

Lobby → match flow

Lobby → 比赛流程

Players queue in the lobby (party leader invites; party members stored server-side).
Queue in a MemoryStoreQueue / sorted map by mode and rating (see
```
roblox-data-stores
```
), or use Roblox matchmaking to fill public servers.
When a match forms: write match config to MemoryStore keyed by a new id,
```
TeleportAsync
```
all players with
```
ShouldReserveServer = true
```
, store the returned
```
PrivateServerId
```
↔ match id mapping.
Match server: waits for expected players (timeout), runs the round, saves results, teleports everyone back to the lobby place (a public server, or the party's lobby via
```
ServerInstanceId
```
).

玩家在大厅中排队（队伍队长邀请成员；队伍成员存储在服务端）。
按模式和评分在 MemoryStoreQueue / sorted map 中排队（参见
```
roblox-data-stores
```
），或使用 Roblox matchmaking 填充公开服务器。
比赛组建完成后：将比赛配置写入以新 id 为键的 MemoryStore，使用
```
ShouldReserveServer = true
```
通过
```
TeleportAsync
```
传送所有玩家，并存储返回的
```
PrivateServerId
```
↔ 比赛 id 映射。
比赛服务器：等待预期玩家加入（设置超时）、运行回合、保存结果，再将所有玩家传送回大厅 place（公开服务器，或通过
```
ServerInstanceId
```
返回队伍所在的大厅）。

Roblox matchmaking (which server a joining player gets)

Roblox 匹配（加入的玩家会被分配到哪个服务器）

Default matchmaking scores eligible public servers by signals (friends, latency, language, age group, occupancy...) and picks the highest weighted sum. You can customize it per place in Creator Hub:

Adjust weights of Roblox signals, or add custom signals based on custom attributes:
- Player attributes: values stored in a DataStore (e.g.
```
PlayerElo
```
  ), configured in the matchmaking settings.
- Server attributes: set at runtime with
```
MatchmakingService:SetServerAttribute(name, value)
```
  (e.g.
```
GameMode
```
  ,
```
ServerLevel
```
  );
```
InitializeServerAttributesForStudio
```
  for testing.
Preview scores against mock servers before applying, then apply the configuration to places. Use it for skill-based public servers; use reserved servers when you need exact team composition.

默认 matchmaking 会根据多项 signals（好友、延迟、语言、年龄组、占用率……）为符合条件的公开服务器评分，并选择加权总分最高的服务器。可在 Creator Hub 中按 place 自定义：

调整 Roblox signals 的权重，或基于 custom attributes 添加 custom signals：
- 玩家 attributes：值存储在 DataStore 中（例如
```
PlayerElo
```
  ），并在 matchmaking 设置中配置。
- 服务器 attributes：在运行时通过
```
MatchmakingService:SetServerAttribute(name, value)
```
  设置（例如
```
GameMode
```
  、
```
ServerLevel
```
  ）；可使用
```
InitializeServerAttributesForStudio
```
  进行测试。
在应用前对照模拟服务器预览评分，然后将配置应用到各 place。将它用于基于水平的公开服务器；当需要精确的队伍组成时，使用 reserved servers。

Server lifecycle

服务器生命周期

```
game:BindToClose
```
for shutdown saves;
```
game.JobId
```
identifies the server; soft shutdowns after updates (Open Cloud
```
:restartServers
```
or "Restart servers for updates") teleport players to fresh servers.
Server browsers: each server heartbeats
```
{ jobId, players, mode }
```
into a MemoryStore sorted map (TTL) — see
```
roblox-data-stores
```
.

```
game:BindToClose
```
用于关闭时保存数据；
```
game.JobId
```
标识服务器；更新后的软关闭（Open Cloud
```
:restartServers
```
或“Restart servers for updates”）会将玩家传送到新的服务器。
服务器浏览器：每个服务器将
```
{ jobId, players, mode }
```
心跳上报到 MemoryStore sorted map（TTL）中——参见
```
roblox-data-stores
```
。