roblox-teleport-matchmaking
Skill92 starsChanged 49 days agoMITView on GitHub
Multi-place and multi-server games - universes and places, TeleportAsync with TeleportOptions (ReservedServerId, VipServerId, specific servers, teleport data), retrying failed teleports, secure access control, lobby-to-match flows, parties and queues, Roblox matchmaking with custom signals, server type detection, data handoff. Use when adding lobbies, match servers, dungeons, parties, server browsers, or customizing server selection.
In this repository25 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- roblox-analytics-liveopsSkill
- roblox-architectureSkill
- roblox-audioSkill
- roblox-characters-animationSkill
- roblox-code-reviewSkill
- roblox-data-storesSkill
- roblox-game-systemsSkill
- roblox-inputSkill
- roblox-luauSkill
- roblox-monetizationSkill
- roblox-networkingSkill
- roblox-npc-aiSkill
- roblox-open-cloudSkill
- roblox-performanceSkill
- roblox-physicsSkill
- roblox-securitySkill
- roblox-studio-mcpSkill
- roblox-testingSkill
- roblox-text-chatSkill
- roblox-toolingSkill
- roblox-uiSkill
- roblox-world-buildingSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 119
When a match forms: generate a GUID, write match config to MemoryStore keyed by it, then TeleportAsync all players with ReservedServerId = …
- Distinctive: line 126
Default matchmaking scores eligible public servers by signals (friends, latency, language, age group, occupancy...) and picks the highest …
- Distinctive: line 133
Use it for skill-based public servers.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Teleports, places, and matchmaking
Structure
- A universe (experience) contains a start place plus sub-places. All places share DataStores, MemoryStores, MessagingService, developer products, and passes.
- Typical layouts: Lobby (start place) → Match place (reserved servers) → back to Lobby; or a hub with separate world places. Keep shared code in packages or a shared Rojo tree.
- Access Control for Places (Creator Dashboard):
Fully open,Limited to same universe, orSecure within universe only(only server-initiated teleports into non-start places — recommended for progression gates and test places). Clients can otherwise teleport themselves anywhere in the universe.
Teleporting (server)
--!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 safeTeleportTeleportOptions (set at most one of ReservedServerId, VipServerId, ServerInstanceId, or it errors):
ReservedServerId = HttpService:GenerateGUID(false)→ a reserved server (private, developer-created) — ideal for matches, dungeons, and parties. The first teleport with a new GUID creates the server; reusing the same GUID (store it in a DataStore/MemoryStore) sends more players to it. Generate GUIDs on the server. On arrival,game.PrivateServerIdequals that GUID.VipServerId = id→ a player's VIP server (itsgame.PrivateServerId), usable with any place in the experience. Carry the id in teleport data to keep a VIP group private across places (VIP → match → VIP); handleTeleportInitFailed(server closed, full, or player not allowed).ServerInstanceId = jobId→ a specific public server (e.g. "join friend's server").SetTeleportData(table)→ non-secure data readable on arrival withplayer:GetJoinData().TeleportData(server) orTeleportService:GetLocalPlayerTeleportData()(client). Clients can tamper with it: never trust it for currency, items, or permissions — use DataStores/MemoryStores keyed by user ID or by the reserved server'sPrivateServerId.
Deprecated: Teleport, TeleportToPlaceInstance, TeleportToPrivateServer, TeleportPartyAsync,
TeleportToSpawnByName → TeleportAsync + TeleportOptions. ReserveServer/ReserveServerAsync,
ShouldReserveServer, and ReservedServerAccessCode → ReservedServerId (old access codes still work).
--!strict
local HttpService = game:GetService("HttpService")
local TeleportService = game:GetService("TeleportService")
-- New reserved match server; returns its id so more players can be sent later.
local function teleportToNewMatch(placeId: number, players: { Player }): string
local serverId = HttpService:GenerateGUID(false)
local options = Instance.new("TeleportOptions")
options.ReservedServerId = serverId
TeleportService:TeleportAsync(placeId, players, options)
return serverId
end
return teleportToNewMatchData handoff between places
- Save the player's data before teleporting (ProfileStore: end the session / wait for save).
- The destination loads with session locking (ProfileStore retries while the old server releases).
- For match parameters (mode, map, team assignments), write a MemoryStore/DataStore entry keyed by
the reserved server's id (the
ReservedServerIdGUID) before teleporting; the match server readsgame.PrivateServerIdon start and loads its config. - On arrival,
TeleportService:SetTeleportGui(gui)(client, before teleport) keeps a loading screen up across the transition; useReplicatedFirstloading screens on arrival.
Detecting server type
| Server | game.PrivateServerId | game.PrivateServerOwnerId |
| Public | "" | 0 |
Reserved (ReservedServerId) | non-empty (the GUID) | 0 |
| Private (VIP) server | non-empty | owner's user id |
Lobby → match flow
- Players queue in the lobby (party leader invites; party members stored server-side).
- Queue in a MemoryStoreQueue / sorted map by mode and rating (see
roblox-data-stores), or use Roblox matchmaking to fill public servers. - When a match forms: generate a GUID, write match config to MemoryStore keyed by it, then
TeleportAsyncall players withReservedServerId = guid(the match server reads its config viagame.PrivateServerId). - Match server: waits for expected players (timeout), runs the round, saves results, teleports everyone
back to the lobby place (a public server, or the party's lobby via
ServerInstanceId).
Roblox matchmaking (which server a joining player gets)
Default matchmaking scores eligible public servers by signals (friends, latency, language, age group, occupancy...) and picks the highest weighted sum. You can customize it per place in Creator Hub:
- Adjust weights of Roblox signals, or add custom signals based on custom attributes:
- Player attributes: values stored in a DataStore (e.g.
PlayerElo), configured in the matchmaking settings. - Server attributes: set at runtime with
MatchmakingService:SetServerAttribute(name, value)(e.g.GameMode,ServerLevel);InitializeServerAttributesForStudiofor testing.
- Player attributes: values stored in a DataStore (e.g.
- Preview scores against mock servers before applying, then apply the configuration to places. Use it for skill-based public servers; use reserved servers when you need exact team composition.
Server lifecycle
game:BindToClosefor shutdown saves;game.JobIdidentifies the server; soft shutdowns after updates (Open Cloud:restartServersor "Restart servers for updates") teleport players to fresh servers.- Server browsers: each server heartbeats
{ jobId, players, mode }into a MemoryStore sorted map (TTL) — seeroblox-data-stores.
Related skills
roblox-data-stores (session locking, MemoryStore queues), roblox-security (access control),
roblox-game-systems (round loops), roblox-open-cloud (server restarts).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

