TeleportService

概览

字段	值
Kind	Service · 服务 Service
Realm	server

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • [TeleportService]（5 函数 / 1 事件）

> Service 继承 Unit 仅表示运行时类型关系；作者可用 API 以当前 Service 页面显式列出的成员为准，不自动包含 Unit 的创建、层级或销毁能力。

TeleportService 负责服务端侧的跨地图传送与服务器调度：它能把一组玩家送往指定地图、预留独立的私有服务器、按匹配系统把玩家分配到对局服务器，也能让单个玩家迁移到新的服务器实例。它还提供创建传送选项的入口，并在传送初始化失败时通过事件回报失败码、错误信息与目标地图。

适用场景

常用于大厅把玩家送入关卡地图、为队伍开一局私有房间，或在对局结束后把玩家迁移到其它服务器；典型链路是服务端监听客户端请求后执行传送，并把结果通过事件回推。

使用要点

先通过 game:GetService("TeleportService") 获取服务实例；需要携带传送数据时先调用 CreateTeleportOptions() 取得传送选项，再调用 TeleportAsync(mapId, players, teleportOptions) 把玩家列表送入目标地图。需要独立房间时用 ReserveServerAsync(mapId) 预留服务器，需要匹配分配时用 ApplyIngameMatchAsync(mapId, players)，需要让单个玩家换服时用 ChangeServerAsync(player)。这些接口都是异步的，应在 Task:Spawn 或协程中调用并用 pcall 保护，同时连接 TeleportInitFailed 以便在失败时拿到失败码与错误信息。

注意事项

TeleportService 仅服务端可用。TeleportAsync/ReserveServerAsync/ApplyIngameMatchAsync/ChangeServerAsync 都是异步方法，必须在协程（Task:Spawn 或 coroutine.wrap）中调用，失败时抛 error 需 pcall 保护。mapId 是调用方从项目配置传入的真实原始地图/关卡 ID，不是资源 URI；示例必须把 mapId 作为函数参数接收，不得在代码块内定义字符串常量充当 mapId；禁止写成 official://、map://、custom://、eggyasset:// 或 net://，也不要虚构占位 ID。公开 Meta 声明 TeleportOptions.New()，但当前运行时对象缺少数据方法；可运行代码应通过 CreateTeleportOptions() 创建传送选项。ReservedServerAccessCode 属于敏感凭据，不得输出到日志或客户端可见数据。

代码示例

在协程中传送当前在线玩家

-- @runtime server
local TeleportService = game:GetService('TeleportService')
local Players = game:GetService('Players')
local Task = game:GetService('Task')
local function teleportOnlinePlayers(mapId)
    if mapId == nil or mapId == '' then return end
    local players = Players:GetPlayers()
    if #players == 0 then return end
    Task:Spawn(function()
        local ok, result = pcall(function()
            return TeleportService:TeleportAsync(mapId, players, TeleportService:CreateTeleportOptions())
        end)
        if not ok then print('传送失败:', result) end
    end)
end
-- 调用方把项目配置中的真实地图 ID 传给 teleportOnlinePlayers

关联类型

• Unit

事件 (1)

TeleportInitFailed

签名：TeleportInitFailed(player: Player, teleportResult: TeleportErrcode, errorMessage: String, mapId: String, teleportOptions: Table) 触发：local

TeleportService 的传送初始化失败事件（服务端触发）。当一次传送在初始化阶段未能成功建立时触发，回调依次携带五个参数：player（Player，目标玩家）、teleportResult（TeleportErrcode，传送结果错误码）、errorMessage（String，错误描述）、mapId（String，目标地图标识）以及 teleportOptions（Table，本次传送使用的选项）。该事件为服务端触发，可在服务端监听以获知传送为何没有成功开始。

回调参数	类型	说明
player	Player	传送的玩家
teleportResult	TeleportErrcode	传送结果错误码
errorMessage	String	错误描述
mapId	String	本次传送的目标地图 mapId (传入 'SELF' 时, 事件上报的为解析后的当前地图实际 mapId)
teleportOptions	Table	传送选项 (含 ShouldReserveServer/ServerInstanceId 等字段)

示例代码

监听下一次传送初始化失败

-- @runtime server
local TeleportService = game:GetService('TeleportService')
TeleportService.TeleportInitFailed:Once(function(player, teleportResult, errorMessage, mapId, teleportOptions)
    print('传送失败玩家:', player:GetName())
    print('错误码:', tostring(teleportResult), '错误信息:', errorMessage)
    print('目标地图 ID:', mapId)
end)

函数 (5)

TeleportAsync

签名：TeleportAsync(mapId: String, players: Array, teleportOptions?: TeleportOptions) -> TeleportAsyncResult | nil (传送结果 (仅传入 teleportOptions 时返回; 未传时返回 nil))

将指定玩家迁移到目标地图，编辑器环境下不会生效。未传 teleportOptions 时走 fire-and-forget 方式不返回结果；传入 teleportOptions 时返回 TeleportAsyncResult。失败时抛出 error，调用方应使用 pcall 保护。

参数	类型	说明
mapId	String	传送目标: 传 'SELF' 表示传送到当前地图的其他服务器实例 (所有地图通用); 非多关卡地图仅支持 'SELF'; 多关卡地图可传关卡ID 传送到指定关卡
players	Array	待传送的玩家列表
teleportOptions?	TeleportOptions	传送选项, 可通过 TeleportService:CreateTeleportOptions() 创建 (可选)

返回值 TeleportAsyncResult | nil (传送结果 (仅传入 teleportOptions 时返回; 未传时返回 nil))

示例代码

协程中传送玩家到目标地图

-- @runtime server
local TeleportService = game:GetService('TeleportService')
local Task = game:GetService('Task')
local Players = game:GetService('Players')
local function teleportToMap(mapId)
  if mapId == nil or mapId == '' then return end
Task:Spawn(function()
    local options = TeleportService:CreateTeleportOptions()
    local players = Players:GetPlayers()
    if #players == 0 then
        print('当前没有玩家在线，无法传送')
        return
    end
    local ok, result = pcall(function()
        return TeleportService:TeleportAsync(mapId, players, options)
    end)
    if not ok then print('传送失败:', result) end
end)
end
-- 调用方把项目配置中的真实地图 ID 传给 teleportToMap

ReserveServerAsync

签名：ReserveServerAsync(mapId: String) -> ReserveServerResult | nil (保留服务器结果 (编辑器环境返回 nil))

获取一个预留服务器的战场实例访问码，返回 ReserveServerResult 对象；编辑器环境下返回 nil；失败时抛出 error，调用方应使用 pcall 保护。ReserveServerResult.ReservedServerAccessCode 可填入 TeleportOptions，再通过 TeleportAsync 把玩家送入预留的服务器战场实例。一旦获取到访问码，访问码始终可用；如果该服务器战场实例当前不在运行，会在传送开始时创建实例。

参数	类型	说明
mapId	String	预留目标: 传 'SELF' 表示为当前地图预留其他服务器实例 (所有地图通用); 非多关卡地图仅支持 'SELF'; 多关卡地图可传关卡ID 为指定关卡预留

返回值 ReserveServerResult | nil (保留服务器结果 (编辑器环境返回 nil))

示例代码

协程中预留服务器并安全传递访问码

-- @runtime server
local TeleportService = game:GetService('TeleportService')
local Task = game:GetService('Task')
local function reserveMapServer(mapId)
  if mapId == nil or mapId == '' then return end
Task:Spawn(function()
    local ok, result = pcall(function()
        return TeleportService:ReserveServerAsync(mapId)
    end)
    if not ok then
        print('预留服务器失败:', result)
    elseif result ~= nil then
        local options = TeleportService:CreateTeleportOptions()
        options.ReservedServerAccessCode = result.ReservedServerAccessCode
        print('预留服务器传送选项已配置')  -- 不输出访问码
    end
end)
end
-- 调用方把项目配置中的真实地图 ID 传给 reserveMapServer

ApplyIngameMatchAsync

签名：ApplyIngameMatchAsync(mapId: String, players: Array) -> String | nil (匹配结果中的 accessCode (编辑器环境返回 nil))

发起局内匹配，匹配完成后返回一个可用于后续传送的 ReservedServerAccessCode；失败时抛出错误。

参数	类型	说明
mapId	String	匹配目标: 传 'SELF' 表示在当前地图发起局内匹配 (所有地图通用); 非多关卡地图仅支持 'SELF'; 多关卡地图可传关卡ID 在指定关卡匹配
players	Array	参与匹配的玩家列表（至少 1 个）

返回值 String | nil (匹配结果中的 accessCode (编辑器环境返回 nil))

示例代码

协程中发起局内匹配

-- @runtime server
local TeleportService = game:GetService('TeleportService')
local Players = game:GetService('Players')
local Task = game:GetService('Task')
local function startMatch(mapId)
  if mapId == nil or mapId == '' then return end
Task:Spawn(function()
    local players = Players:GetPlayers()
    if #players == 0 then
        print('当前没有玩家在线，无法发起匹配')
        return
    end
    local ok, result = pcall(function()
        return TeleportService:ApplyIngameMatchAsync(mapId, { players[1] })
    end)
    if ok and result ~= nil and result ~= '' then
        local options = TeleportService:CreateTeleportOptions()
        options.ReservedServerAccessCode = result
        print('匹配传送选项已配置')  -- 不输出访问码
    elseif not ok then
        print('局内匹配失败:', result)
    else
        print("敏感凭据未写入日志")
    end
end)
end
-- 调用方把项目配置中的真实地图 ID 传给 startMatch

ChangeServerAsync

签名：ChangeServerAsync(player: Player) -> Bool (迁移结果 (编辑器环境返回 false))

ChangeServerAsync 用于将单个玩家迁移到由匹配系统分配的另一服务器战斗实例，参数为 player（Player），返回 Bool 表示迁移结果：迁移成功返回 true，迁移失败返回 false，编辑器环境下同样返回 false。注意成功的情况下执行顺序是先将玩家迁移出去再返回结果，因此收到返回时迁移已经完成；处于组队中的玩家无法被迁移。

参数	类型	说明
player	Player	要迁移的玩家

返回值 Bool (迁移结果 (编辑器环境返回 false))

示例代码

协程中迁移单个玩家

-- @runtime server
local TeleportService = game:GetService('TeleportService')
local Players = game:GetService('Players')
local Task = game:GetService('Task')
Task:Spawn(function()
    local player = Players:GetPlayers()[1]
    if player == nil then return end
    local ok, result = pcall(function()
        return TeleportService:ChangeServerAsync(player)
    end)
    print(ok and '迁移请求完成' or '迁移失败:', result)
end)

CreateTeleportOptions

签名：CreateTeleportOptions() -> TeleportOptions (传送选项对象)

创建一个新的传送选项实例。

返回值 TeleportOptions (传送选项对象)

示例代码

创建传送选项并附加公开数据

-- @runtime server
local TeleportService = game:GetService('TeleportService')
local options = TeleportService:CreateTeleportOptions()
options:SetTeleportData({ from = 'lobby' })
print('传送附带数据:', options:GetTeleportData())