Skip to main content

TeleportDataService

This item only works when running on the server. Server

Server half of the symmetric teleport-data surface. Two responsibilities:

The trust split is the load-bearing idea. A player's arrived data reaches the server two ways:

  • the trusted band -- player:GetJoinData().TeleportData -- which Roblox only populates for a server-initiated teleport, so it is genuinely server-authored and safe to authorize on; and
  • the non-trusted band -- what the client read from its own local teleport data (GetLocalPlayerTeleportData) and replicated back to us. A client-initiated teleport (e.g. a menu teleporting the local player) only ever reaches the server this way, so without it the server is blind to data the client can see.

The unified read (TeleportDataService.PromiseArrivedData) merges both with the trusted band winning, so a client can never override a key the server set. Because the non-trusted band arrives over the network, every read is a [Promise]: it resolves once the client has replicated (or a bounded timeout falls back to the trusted band alone, so a stale client can never hang a read forever). A PlayerMock has no client to wait for, so its reads fall back at the next resumption step instead of the production window -- a spec injects arrived data (via the testing seams) before yielding. Code that must not trust the client reads the trusted band explicitly via TeleportDataService.PromiseTrustedArrivedData; the unified accessor is deliberately un-named for trust so trusting client data is always a visible choice.

Functions​

RegisterTeleportDataProvider​

</>
TeleportDataService.RegisterTeleportDataProvider(
) → () → ()

Registers a shared provider (contributes to every player's teleport data). See TeleportDataBuilder.RegisterTeleportDataProvider. Returns an unregister function.

RegisterPerPlayerTeleportDataProvider​

</>
TeleportDataService.RegisterPerPlayerTeleportDataProvider(
) → () → ()

Registers a per-player provider. See TeleportDataBuilder.RegisterPerPlayerTeleportDataProvider. Returns an unregister function.

PromiseBuildTeleportData​

</>
TeleportDataService.PromiseBuildTeleportData(
players: {Player},
baseData: {[string]: any}?
) → Promise<{[string]: any}>

Builds the teleport data envelope, awaiting any provider that returns a Promise. See TeleportDataBuilder.PromiseBuildTeleportData. Use this when a provider assembles its slice asynchronously (e.g. persisting live state before a teleport).

_getUserId​

</>
TeleportDataService._getUserId(
player: Player
) → number

Resolves the UserId used to key a player's envelope slice. A method so tests can stand in a fake player (which has no UserId) by overriding it.

PromiseArrivedData​

</>
TeleportDataService.PromiseArrivedData(
player: Player
) → Promise<{[string]: any}?>

Returns the unified teleport data the player arrived with -- the trusted band (server join data) merged over the non-trusted band (client-replicated), trusted winning -- or nil. Resolves once the client has replicated its band, or when the bounded timeout falls back to the trusted band alone.

This is the everyday accessor. It may contain client-authored keys, so treat it as a request, not an authority; for authoritative reads use TeleportDataService.PromiseTrustedArrivedData.

PromiseTrustedArrivedData​

</>
TeleportDataService.PromiseTrustedArrivedData(
player: Player
) → Promise<{[string]: any}?>

Returns the trusted-band teleport data the player arrived with (server-authored, from join data), or nil. Safe to authorize on -- a client can never place data here. Resolves once the arrival is sealed.

PromiseNonTrustedArrivedData​

</>
TeleportDataService.PromiseNonTrustedArrivedData(
player: Player
) → Promise<{[string]: any}?>

Returns the non-trusted-band teleport data the player arrived with (client-replicated), or nil. Rarely needed directly; prefer the unified TeleportDataService.PromiseArrivedData.

PromiseArrivedValue​

</>
TeleportDataService.PromiseArrivedValue(
player: Player,
key: string
) → Promise<any>

Returns the unified value the player arrived with under key, or nil.

PromiseHasArrivedValue​

</>
TeleportDataService.PromiseHasArrivedValue(
player: Player,
key: string
) → Promise<boolean>

Returns whether the player arrived with a unified value under key.

PromiseTrustedArrivedValue​

</>
TeleportDataService.PromiseTrustedArrivedValue(
player: Player,
key: string
) → Promise<any>

Returns the trusted-band value the player arrived with under key, or nil. Safe to authorize on.

PromiseHasTrustedArrivedValue​

</>
TeleportDataService.PromiseHasTrustedArrivedValue(
player: Player,
key: string
) → Promise<boolean>

Returns whether the player arrived with a trusted-band value under key.

PromiseArrivedValueIsTrusted​

</>
TeleportDataService.PromiseArrivedValueIsTrusted(
player: Player,
key: string
) → Promise<boolean>

Returns whether the unified value for key came from the trusted band -- i.e. whether it is safe to authorize on. Defense-in-depth for code that reads the unified view but must occasionally assert provenance without a second read.

SetTrustedArrivedTeleportDataForTesting​

</>
TeleportDataService.SetTrustedArrivedTeleportDataForTesting(
player: Player,
data: {[string]: any}?
) → ()

Overrides the trusted arrived band for a player. Test seam -- headless servers have no join data, so specs inject what a player would have arrived with from a server teleport. Must be set before any read seals the arrival.

SetNonTrustedArrivedTeleportDataForTesting​

</>
TeleportDataService.SetNonTrustedArrivedTeleportDataForTesting(
player: Player,
data: {[string]: any}?
) → ()

Simulates the client's non-trusted band arriving (the replication the real client pushes). Test seam. First arrival wins and seals; later calls are ignored, mirroring production first-wins semantics.

SetReplicationTimeoutForTesting​

</>
TeleportDataService.SetReplicationTimeoutForTesting(
seconds: number
) → ()

Sets the bounded wait before a read falls back to the trusted band alone. Test seam, so a spec can drive the timeout path deterministically without waiting the production window.

Show raw api
{
    "functions": [
        {
            "name": "RegisterTeleportDataProvider",
            "desc": "Registers a shared provider (contributes to every player's teleport data). See\n[TeleportDataBuilder.RegisterTeleportDataProvider]. Returns an unregister function.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TeleportDataService"
                },
                {
                    "name": "provider",
                    "desc": "",
                    "lua_type": "TeleportDataProvider"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 124,
                "path": "src/teleportserviceutils/src/Server/TeleportDataService.lua"
            }
        },
        {
            "name": "RegisterPerPlayerTeleportDataProvider",
            "desc": "Registers a per-player provider. See [TeleportDataBuilder.RegisterPerPlayerTeleportDataProvider].\nReturns an unregister function.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TeleportDataService"
                },
                {
                    "name": "provider",
                    "desc": "",
                    "lua_type": "PerPlayerTeleportDataProvider"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 138,
                "path": "src/teleportserviceutils/src/Server/TeleportDataService.lua"
            }
        },
        {
            "name": "PromiseBuildTeleportData",
            "desc": "Builds the teleport data envelope, awaiting any provider that returns a Promise. See\n[TeleportDataBuilder.PromiseBuildTeleportData]. Use this when a provider assembles its slice\nasynchronously (e.g. persisting live state before a teleport).",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TeleportDataService"
                },
                {
                    "name": "players",
                    "desc": "",
                    "lua_type": "{ Player }"
                },
                {
                    "name": "baseData",
                    "desc": "",
                    "lua_type": "{ [string]: any }?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<{ [string]: any }>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 154,
                "path": "src/teleportserviceutils/src/Server/TeleportDataService.lua"
            }
        },
        {
            "name": "_getUserId",
            "desc": "Resolves the UserId used to key a player's envelope slice. A method so tests can stand in a fake\nplayer (which has no UserId) by overriding it.",
            "params": [
                {
                    "name": "_self",
                    "desc": "",
                    "lua_type": "TeleportDataService"
                },
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 169,
                "path": "src/teleportserviceutils/src/Server/TeleportDataService.lua"
            }
        },
        {
            "name": "PromiseArrivedData",
            "desc": "Returns the *unified* teleport data the player arrived with -- the trusted band (server join data)\nmerged over the non-trusted band (client-replicated), trusted winning -- or nil. Resolves once the\nclient has replicated its band, or when the bounded timeout falls back to the trusted band alone.\n\nThis is the everyday accessor. It may contain client-authored keys, so treat it as a *request*, not\nan authority; for authoritative reads use [TeleportDataService.PromiseTrustedArrivedData].",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TeleportDataService"
                },
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<{ [string]: any }?>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 184,
                "path": "src/teleportserviceutils/src/Server/TeleportDataService.lua"
            }
        },
        {
            "name": "PromiseTrustedArrivedData",
            "desc": "Returns the trusted-band teleport data the player arrived with (server-authored, from join data), or\nnil. Safe to authorize on -- a client can never place data here. Resolves once the arrival is sealed.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TeleportDataService"
                },
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<{ [string]: any }?>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 201,
                "path": "src/teleportserviceutils/src/Server/TeleportDataService.lua"
            }
        },
        {
            "name": "PromiseNonTrustedArrivedData",
            "desc": "Returns the non-trusted-band teleport data the player arrived with (client-replicated), or nil.\nRarely needed directly; prefer the unified [TeleportDataService.PromiseArrivedData].",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TeleportDataService"
                },
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<{ [string]: any }?>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 218,
                "path": "src/teleportserviceutils/src/Server/TeleportDataService.lua"
            }
        },
        {
            "name": "PromiseArrivedValue",
            "desc": "Returns the unified value the player arrived with under `key`, or nil.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TeleportDataService"
                },
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                },
                {
                    "name": "key",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<any>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 235,
                "path": "src/teleportserviceutils/src/Server/TeleportDataService.lua"
            }
        },
        {
            "name": "PromiseHasArrivedValue",
            "desc": "Returns whether the player arrived with a unified value under `key`.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TeleportDataService"
                },
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                },
                {
                    "name": "key",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<boolean>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 253,
                "path": "src/teleportserviceutils/src/Server/TeleportDataService.lua"
            }
        },
        {
            "name": "PromiseTrustedArrivedValue",
            "desc": "Returns the trusted-band value the player arrived with under `key`, or nil. Safe to authorize on.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TeleportDataService"
                },
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                },
                {
                    "name": "key",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<any>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 266,
                "path": "src/teleportserviceutils/src/Server/TeleportDataService.lua"
            }
        },
        {
            "name": "PromiseHasTrustedArrivedValue",
            "desc": "Returns whether the player arrived with a trusted-band value under `key`.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TeleportDataService"
                },
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                },
                {
                    "name": "key",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<boolean>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 284,
                "path": "src/teleportserviceutils/src/Server/TeleportDataService.lua"
            }
        },
        {
            "name": "PromiseArrivedValueIsTrusted",
            "desc": "Returns whether the unified value for `key` came from the trusted band -- i.e. whether it is safe to\nauthorize on. Defense-in-depth for code that reads the unified view but must occasionally assert\nprovenance without a second read.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TeleportDataService"
                },
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                },
                {
                    "name": "key",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<boolean>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 299,
                "path": "src/teleportserviceutils/src/Server/TeleportDataService.lua"
            }
        },
        {
            "name": "SetTrustedArrivedTeleportDataForTesting",
            "desc": "Overrides the *trusted* arrived band for a player. Test seam -- headless servers have no join data, so\nspecs inject what a player would have arrived with from a server teleport. Must be set before any read\nseals the arrival.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TeleportDataService"
                },
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                },
                {
                    "name": "data",
                    "desc": "",
                    "lua_type": "{ [string]: any }?"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 318,
                "path": "src/teleportserviceutils/src/Server/TeleportDataService.lua"
            }
        },
        {
            "name": "SetNonTrustedArrivedTeleportDataForTesting",
            "desc": "Simulates the client's non-trusted band arriving (the replication the real client pushes). Test seam.\nFirst arrival wins and seals; later calls are ignored, mirroring production first-wins semantics.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TeleportDataService"
                },
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                },
                {
                    "name": "data",
                    "desc": "",
                    "lua_type": "{ [string]: any }?"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 338,
                "path": "src/teleportserviceutils/src/Server/TeleportDataService.lua"
            }
        },
        {
            "name": "SetReplicationTimeoutForTesting",
            "desc": "Sets the bounded wait before a read falls back to the trusted band alone. Test seam, so a spec can\ndrive the timeout path deterministically without waiting the production window.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TeleportDataService"
                },
                {
                    "name": "seconds",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 354,
                "path": "src/teleportserviceutils/src/Server/TeleportDataService.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "TeleportDataService",
    "desc": "Server half of the symmetric teleport-data surface. Two responsibilities:\n\n* **Building** teleport data through a shared [TeleportDataBuilder], so every teleport site assembles\n  the same envelope from the same providers (see [TeleportDataService.PromiseBuildTeleportData]).\n* **Reading** the data a player arrived with, as a *unified* view across two trust bands.\n\nThe trust split is the load-bearing idea. A player's arrived data reaches the server two ways:\n\n* the **trusted** band -- `player:GetJoinData().TeleportData` -- which Roblox only populates for a\n  *server*-initiated teleport, so it is genuinely server-authored and safe to authorize on; and\n* the **non-trusted** band -- what the *client* read from its own local teleport data\n  (`GetLocalPlayerTeleportData`) and replicated back to us. A client-initiated teleport (e.g. a menu\n  teleporting the local player) only ever reaches the server this way, so without it the server is\n  blind to data the client can see.\n\nThe unified read ([TeleportDataService.PromiseArrivedData]) merges both with the **trusted band\nwinning**, so a client can never override a key the server set. Because the non-trusted band arrives\nover the network, every read is a [Promise]: it resolves once the client has replicated (or a bounded\ntimeout falls back to the trusted band alone, so a stale client can never hang a read forever). A\n[PlayerMock] has no client to wait for, so its reads fall back at the next resumption step instead of\nthe production window -- a spec injects arrived data (via the testing seams) before yielding. Code\nthat must *not* trust the client reads the trusted band explicitly via\n[TeleportDataService.PromiseTrustedArrivedData]; the unified accessor is deliberately un-named for\ntrust so trusting client data is always a visible choice.",
    "realm": [
        "Server"
    ],
    "source": {
        "line": 31,
        "path": "src/teleportserviceutils/src/Server/TeleportDataService.lua"
    }
}