roblox-teleport-matchmaking

传送、场所与匹配

结构

• 一个 universe（体验）包含一个起始场所及子场所。所有场所共享 DataStores、 MemoryStores、MessagingService、开发者产品和通行证。
• 典型布局：大厅（起始场所）→ 对局场所（预留服务器）→ 返回大厅；或一个带有 独立世界场所的枢纽。将共享代码放在包或共享的 Rojo 树中。
• 场所访问控制（Creator Dashboard）：Fully open、Limited to same universe 或 Secure within universe only（仅允许由服务器发起的传送进入非起始场所——推荐 用于进度门槛和测试场所）。否则客户端可以将自己传送到 universe 中的任何位置。

传送（服务器）

--!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 → 一个新的 预留服务器（私有，只能通过访问代码进入）—— 非常适合对局、副本和队伍。返回带有 ReservedServerAccessCode 和 PrivateServerId 的 TeleportAsyncResult。
• ReservedServerAccessCode = code → 加入一个现有的预留服务器（来自 ReserveServerAsync(placeId) 或之前的结果）。
• ServerInstanceId = jobId → 一个特定的公共服务器（例如"加入好友的服务器"）。
• SetTeleportData(table) → 非安全数据，到达时可通过 player:GetJoinData().TeleportData （服务器）或 TeleportService:GetLocalPlayerTeleportData()（客户端）读取。客户端可以篡改它： 绝不要将其用于货币、物品或权限——请使用以用户 ID 或预留服务器的 PrivateServerId 为键的 DataStores/MemoryStores。

已弃用：Teleport、TeleportToPlaceInstance、TeleportToPrivateServer、TeleportPartyAsync、 TeleportToSpawnByName、ReserveServer → TeleportAsync + TeleportOptions / ReserveServerAsync。

场所之间的数据交接

1. 在传送之前保存玩家的数据（ProfileStore：结束会话 / 等待保存完成）。
2. 目标服务器通过会话锁定加载（旧服务器释放期间 ProfileStore 会重试）。
3. 对于对局参数（模式、地图、队伍分配），在传送前将以预留服务器的 PrivateServerId （或访问代码）为键的 MemoryStore/DataStore 条目写入；对局服务器在启动时读取 game.PrivateServerId 并加载其配置。
4. 到达时，TeleportService:SetTeleportGui(gui)（客户端，在传送前）会在整个过渡期间 保持显示加载界面；到达后使用 ReplicatedFirst 加载界面。

检测服务器类型

服务器	game.PrivateServerId	game.PrivateServerOwnerId
公共	""	0
预留（ReserveServerAsync/ShouldReserveServer）	非空	0
私有（VIP）服务器	非空	拥有者的用户 ID

大厅 → 对局流程

1. 玩家在大厅中排队（队长邀请；队员信息存储在服务器端）。
2. 按模式和评分在 MemoryStoreQueue / 有序映射中排队（参见 roblox-data-stores），或使用 Roblox 匹配系统填充公共服务器。
3. 当对局形成时：将以新 id 为键的对局配置写入 MemoryStore，使用 ShouldReserveServer = true 对所有玩家执行 TeleportAsync，存储返回的 PrivateServerId ↔ 对局 id 映射。
4. 对局服务器：等待预期玩家（超时），运行回合，保存结果，将所有人 传送回大厅场所（一个公共服务器，或通过 ServerInstanceId 传送到队伍的大厅）。

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

默认匹配会根据各种信号（好友、延迟、语言、年龄段、占用率……）为符合条件的公共服务器评分，并选择加权总和最高的服务器。你可以在 Creator Hub 中按 place 自定义：

• 调整 Roblox 信号的权重，或基于自定义属性添加自定义信号：
  • 玩家属性：存储在 DataStore 中的值（例如 PlayerElo），在匹配设置中配置。
  • 服务器属性：在运行时通过 MatchmakingService:SetServerAttribute(name, value) 设置（例如 GameMode、ServerLevel）；测试时使用 InitializeServerAttributesForStudio。
• 在应用之前，针对模拟服务器预览评分，然后将配置应用到各个 place。 用于基于技能的公共服务器；当你需要精确的队伍组成时，请使用预留服务器。

服务器生命周期

• 使用 game:BindToClose 进行关停保存；game.JobId 标识服务器；更新后的软关停 （Open Cloud :restartServers 或 "Restart servers for updates"）会将玩家传送到新服务器。
• 服务器浏览器：每个服务器将 { jobId, players, mode } 心跳写入 MemoryStore 有序映射 （TTL）——参见 roblox-data-stores。

相关技能

roblox-data-stores（会话锁定、MemoryStore 队列）、roblox-security（访问控制）、 roblox-game-systems（回合循环）、roblox-open-cloud（服务器重启）。