場所間のテレポート

ファンタジーワールドや複数の町、城、ダンジョン、広い森など、多くの異なる場所でエクスペリエンスを構築したい場合は、TeleportService を使用して、ユーザーが宇宙、サーバー、または他のエクスペリエンスの場所間でテレポートできるようにすることができます。

TeleportService Roblox Studio でプレイテストをサポートしていません。エクスペリエンスを公開し、テストのために Roblox アプリケーションで使用する必要があります。

テレポートを設定する

エクスペリエンスでテレポートを有効にするには、TeleportService:TeleportAsync() を使用します。メソッドは 3つのパラメータを受け入れます：

ユーザーがテレポートするための PlaceId
ユーザーをテレポートするための Player インスタンスを含む配列
オプションの TeleportOptions インスタンス、TeleportAsync() 呼び出しのカスタムプロパティを含む。


local Players = game:GetService("Players")
local TeleportService = game:GetService("TeleportService")

local TARGET_PLACE_ID = 1234 -- 自分のプレースIDで置換

local playerToTeleport = Players:GetPlayers()[1] -- エクスペリエンスの最初のユーザーを取得する

TeleportService:TeleportAsync(TARGET_PLACE_ID, {playerToTeleport}, teleportOptions)

サーバー側のスクリプトからのみ TeleportAsync() を呼び出すことができます。この制限は、クライアント側の悪用を減少させます。必要に応じて、クライアント側のスクリプトから Teleport() を呼び出すことができますが、TeleportAsync() は推奨される方法です。

テレポートを設定するときにエラーの処理に注意したい場合は、失敗したテレポートを処理する方法を参照してください。

クロスエクスペリエンステレポートを有効にする

セキュリティ目的で、ユーザーを自分のエクスペリエンスから他の人が所有するエクスペリエンス、または逆に他の人が自分のエクスペリエンスにテレポートすることは、デフォルトで失敗します。クロスエクスペリエンステレポートを有効にするには、ゲーム設定 > セキュリティ > サードパーティテレポートを許可を開き、Studio で第三者テレポートを許可を有効にします。

ユーザーがテレポートをトリガーすると、新しい場所がロードされるのを待っている間、標準の Roblox ロード画面が表示されます。クライアントに TeleportService:SetTeleportGui() を呼び出してユーザーの没入を向上させ、ユーザーをテレポートする前に ScreenGui を使用するためにパスして、カスタムテレポート画面を追加できます。次の例では、テレポートが発生したときにロード画面としてカスタマイズされた ScreenGui を ReplicatedStorage に設定します。それは ScreenGui 内のスクリプトを実行しません。


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

local teleportGui = ReplicatedStorage.TeleportGui

TeleportService:SetTeleportGui(teleportGui)

テレポートオプションのカスタマイズ

ユーザーを特定のサーバーにテレポートするやテレポートと一緒にユーザーデータを送信するなどのテレポートをカスタマイズできるように、インスタンスを設定し、メソッドにパスして、を設定します。

特定のサーバーにテレポート

ユーザーを特定のサーバーにテレポートするには、TeleportOptions を使用してターゲットサーバーを設定し、TeleportService:TeleportAsync() メソッドにパスします。サーバーを指定しないと、ユーザーはマッチメイド公開サーバーにテレポートされます。リストの最初のユーザーの情報は、その公開サーバーとのマッチメイキングに使用されます。

ユーザーを特定の公開サーバーにテレポートするには、TeleportOptions.ServerInstanceId プロパティを有効なインスタンスIDとして設定し、これは公開サーバーのユニークな識別子です。


local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ServerInstanceId = targetServerId

ユーザーを特定の予約サーバーにテレポートするには、予約サーバーに入るためのユニークなコードである TeleportOptions.ReservedServerAccessCode を設定します。


local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ReservedServerAccessCode = reservedServerCode

ユーザーを新しい予約サーバーにテレポートするには、TeleportOptions.ShouldReserveServer を真に設定します。


local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ShouldReserveServer = true

テレポートと一緒にユーザーデータを送信

場所間でユーザーをテレポートすると、そのユーザーに関連するローカルデータがすべて排除されます。次のアプローチを使用して、場所間のデータの持続性を処理できます。

エクスペリエンスが、安全なユーザーデータ（エクスペリエンス内持ち物リスト貨やインベントリなど）を使用している場合、データストアまたはメモリストアを実装して、場所からプレースへのデータを維持します。
場所から場プレースへの基本的な安全でないデータを送信するには、TeleportOptions:SetTeleportData() を通過する前に呼び出してくださいTeleportAsync()。

TeleportOptions:SetTeleportData() で安全なデータをパスしないでください、それは悪用のリスクがあるからです。


local teleportData = {
    randomNumber = RNG:NextInteger(1, 100),
}

local teleportOptions = Instance.new("TeleportOptions")
teleportOptions:SetTeleportData(teleportData)

サーバー上のテレポートから到着するユーザーのすべてのデータを取得するには、Player:GetJoinData() 関数を使用し、ユーザーに関連するデータを含む辞書を返します。


local Players = game:GetService("Players")

local function onPlayerAdded(player)
    local joinData = player:GetJoinData()
    local teleportData = joinData.TeleportData
    local randomNumber = teleportData.randomNumber

    print(player.Name .. "joined with the number" .. randomNumber)
end

Players.PlayerAdded:Connect(onPlayerAdded)

クライアント上でのみテレポートデータを取得するには、TeleportService:GetLocalPlayerTeleportData() を使用できます。

ハンドル失敗テレポート

ネットワークリクエストを含むどの API 呼び出しも同様、テレポートは失敗してエラーが発生する可能性があります。保護された呼び出しで包み込む( pcall() )。予約済みのサーバーを含む失敗には、再試行が有益であるため、失敗に対して何回か再試行することをお勧めします。

呼び出しが成功してテレポートが開始しても、エラーを投げずに最後の瞬間に失敗し、ユーザーをサーバーに残すことができます。これが発生すると、TeleportService.TeleportInitFailed イベントがトリガーされます。

次の例 ModuleScript は、ユーザーを保護された呼び出しで再試行ロジックでテレポートする SafeTeleport 機能を定義します。また、handleFailedTeleport 呼び出しが成功したがテレポートが発生しなかった状況に対処する機能もあります。


local TeleportService = game:GetService("TeleportService")

local ATTEMPT_LIMIT = 5
local RETRY_DELAY = 1
local FLOOD_DELAY = 15

local function SafeTeleport(placeId, players, options)
    local attemptIndex = 0
    local success, result -- ループ外で pcall の結果を定義して、後で結果を報告できるようにする

    repeat
        success, result = pcall(function()
            return TeleportService:TeleportAsync(placeId, players, options) -- 保護された呼び出しでユーザーをテレポートしてエラーを防ぐ
        end)
        attemptIndex += 1
        if not success then
            task.wait(RETRY_DELAY)
        end
    until success or attemptIndex == ATTEMPT_LIMIT -- 呼び出しが成功した場合、または再試行制限に達した場合、テレポートを停止する

    if not success then
        warn(result) -- 出力に失敗理由を印刷する
    end

    return success, result
end

local function handleFailedTeleport(player, teleportResult, errorMessage, targetPlaceId, teleportOptions)
    if teleportResult == Enum.TeleportResult.Flooded then
        task.wait(FLOOD_DELAY)
    elseif teleportResult == Enum.TeleportResult.Failure then
        task.wait(RETRY_DELAY)
    else
        -- テレポートが無効である場合は、再試行ではなくエラーを報告する
        error(("Invalid teleport [%s]: %s"):format(teleportResult.Name, errorMessage))
    end

    SafeTeleport(targetPlaceId, {player}, teleportOptions)
end

TeleportService.TeleportInitFailed:Connect(handleFailedTeleport)

return SafeTeleport

SafeTeleport 関数は、TeleportAsync() 関数と同じ引数を受け取ります。エクスペリエンス内のどこかからテレポートを実行するには、次の ModuleScript 関数を使用して SafeTeleport 機能を実行でき、失敗したテレポートを減少できます。


local Players = game:GetService("Players")
local ServerScriptService = game:GetService("ServerScriptService")

local SafeTeleport = require(ServerScriptService.SafeTeleport)

local TARGET_PLACE_ID = 1818 -- 自分のプレースIDで置換

local playerToTeleport = Players:GetPlayers()[1] -- ゲームの最初のユーザーを取得する

SafeTeleport(TARGET_PLACE_ID, {playerToTeleport}, teleportOptions)