Skip to main content

TeleportDataBuilder

Realm-agnostic assembly of the teleport-data envelope: the provider registry plus TeleportDataBuilder.PromiseBuildTeleportData. Both TeleportDataService (server) and TeleportDataServiceClient (client) own one of these and delegate their build surface to it, so a teleport authored on either realm goes through the same providers and produces the same envelope shape. That symmetry is the point: a client-initiated teleport can no longer forget shared data or hand-roll a divergent table.

Pure -- it performs no teleport and touches no Player state beyond the injected UserId resolver -- so it is unit tested without any real player.

Types​

TeleportDataProvider​

</>
type TeleportDataProvider = ({Player}) → ({[string]: any}?)

Contributes teleport data shared by every player in a teleport. Returns nil to contribute nothing.

PerPlayerTeleportDataProvider​

</>
type PerPlayerTeleportDataProvider = (
Player,
{Player}
) → ({[string]: any}?)

Contributes teleport data for a single player in a teleport (called once per player, with the full player list for context). Returns nil to contribute nothing. This is how per-player data survives a group teleport, where every player would otherwise share one flat table.

Functions​

new​

</>
TeleportDataBuilder.new(getUserId: ((Player) → number)?) → TeleportDataBuilder

Creates a builder. getUserId resolves the UserId used to key a player's envelope slice; it is injected (rather than reading player.UserId directly) so a headless test can stand in a fake player.

RegisterTeleportDataProvider​

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

Registers a provider that contributes teleport data on every TeleportDataBuilder.PromiseBuildTeleportData call. Returns a function that unregisters the provider (also give it to a [Maid]).

RegisterPerPlayerTeleportDataProvider​

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

Registers a per-player provider that contributes each player's own slice on every TeleportDataBuilder.PromiseBuildTeleportData call. Returns a function that unregisters it (also give it to a [Maid]).

PromiseBuildTeleportData​

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

Builds the teleport-data envelope, awaiting any provider that returns a Promise. Providers may return a table, nil, or a Promise of either. Resolves to the assembled per-player envelope (see TeleportDataBuilder._assembleEnvelope for precedence and the size guard).

A provider whose Promise rejects rejects the whole build, so an asynchronous provider should handle its own errors (e.g. resolve nil) when it would rather degrade than block the teleport.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Creates a builder. `getUserId` resolves the UserId used to key a player's envelope slice; it is\ninjected (rather than reading `player.UserId` directly) so a headless test can stand in a fake player.",
            "params": [
                {
                    "name": "getUserId",
                    "desc": "",
                    "lua_type": "((Player) -> number)?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "TeleportDataBuilder"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 63,
                "path": "src/teleportserviceutils/src/Shared/TeleportDataBuilder.lua"
            }
        },
        {
            "name": "RegisterTeleportDataProvider",
            "desc": "Registers a provider that contributes teleport data on every [TeleportDataBuilder.PromiseBuildTeleportData]\ncall. Returns a function that unregisters the provider (also give it to a [Maid]).",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TeleportDataBuilder"
                },
                {
                    "name": "provider",
                    "desc": "",
                    "lua_type": "TeleportDataProvider"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 82,
                "path": "src/teleportserviceutils/src/Shared/TeleportDataBuilder.lua"
            }
        },
        {
            "name": "RegisterPerPlayerTeleportDataProvider",
            "desc": "Registers a per-player provider that contributes each player's own slice on every\n[TeleportDataBuilder.PromiseBuildTeleportData] call. Returns a function that unregisters it (also give it to\na [Maid]).",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TeleportDataBuilder"
                },
                {
                    "name": "provider",
                    "desc": "",
                    "lua_type": "PerPlayerTeleportDataProvider"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 106,
                "path": "src/teleportserviceutils/src/Shared/TeleportDataBuilder.lua"
            }
        },
        {
            "name": "PromiseBuildTeleportData",
            "desc": "Builds the teleport-data envelope, awaiting any provider that returns a Promise. Providers may return\na table, nil, or a Promise of either. Resolves to the assembled per-player envelope (see\n[TeleportDataBuilder._assembleEnvelope] for precedence and the size guard).\n\nA provider whose Promise rejects rejects the whole build, so an asynchronous provider should handle\nits own errors (e.g. resolve nil) when it would rather degrade than block the teleport.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TeleportDataBuilder"
                },
                {
                    "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": 201,
                "path": "src/teleportserviceutils/src/Shared/TeleportDataBuilder.lua"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "TeleportDataProvider",
            "desc": "Contributes teleport data shared by *every* player in a teleport. Returns nil to contribute nothing.",
            "lua_type": "({ Player }) -> ({ [string]: any }?)",
            "source": {
                "line": 28,
                "path": "src/teleportserviceutils/src/Shared/TeleportDataBuilder.lua"
            }
        },
        {
            "name": "PerPlayerTeleportDataProvider",
            "desc": "Contributes teleport data for a *single* player in a teleport (called once per player, with the full\nplayer list for context). Returns nil to contribute nothing. This is how per-player data survives a\ngroup teleport, where every player would otherwise share one flat table.",
            "lua_type": "(Player, { Player }) -> ({ [string]: any }?)",
            "source": {
                "line": 38,
                "path": "src/teleportserviceutils/src/Shared/TeleportDataBuilder.lua"
            }
        }
    ],
    "name": "TeleportDataBuilder",
    "desc": "Realm-agnostic assembly of the teleport-data envelope: the provider registry plus\n[TeleportDataBuilder.PromiseBuildTeleportData]. Both [TeleportDataService] (server) and\n[TeleportDataServiceClient] (client) own one of these and delegate their build surface to it, so a\nteleport authored on either realm goes through the *same* providers and produces the *same* envelope\nshape. That symmetry is the point: a client-initiated teleport can no longer forget shared data or\nhand-roll a divergent table.\n\nPure -- it performs no teleport and touches no [Player] state beyond the injected UserId resolver --\nso it is unit tested without any real player.",
    "source": {
        "line": 15,
        "path": "src/teleportserviceutils/src/Shared/TeleportDataBuilder.lua"
    }
}