roblox-teleport-matchmaking — Claude Code skill: what it does
roblox-teleport-matchmaking — a skill for Claude Code handles player teleports and matchmaking flows in Roblox via TeleportService.
MIT 1,200 installs ★ 131 updated 2026-11-03
npx skills add EL4CTEO/roblox-skills --skill roblox-teleport-matchmaking -a claude-codeWhat roblox-teleport-matchmaking does
The agent brings in this skill when building lobbies, match servers, dungeons, party queues, or customizing server selection. It contains Luau code patterns for secure TeleportAsync calls, retrying failed transfers, and passing session data between places. The documentation also covers TeleportOptions, reserved servers, VIP servers, and custom matchmaking signals in Creator Hub.
The guide details universe layouts, memory store handoffs, and server type detection via game.PrivateServerId. Deprecated methods are flagged alongside security boundaries for client-side teleport data.
Set access control in the Creator Dashboard to secure within universe only before running scripts in Roblox Studio.
What it helps with
- configure secure player teleports across Roblox places and servers
- implement retry loops for failed teleports in Luau scripts
- pass match parameters between servers using MemoryStore
- set up custom matchmaking signals and attributes in Creator Hub
Example prompts for the agent
- Write Luau code for safe player teleportation to a reserved server with retry logic
- Configure data handoff between the lobby and match server using MemoryStore
- Set up custom attributes and signal weights for Roblox matchmaking
How to install roblox-teleport-matchmaking
1Skills CLI (Vercel)
npx skills add EL4CTEO/roblox-skills --skill roblox-teleport-matchmaking -a claude-code2Manually: put the files in place
~/.claude/skills/roblox-teleport-matchmaking/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/roblox-teleport-matchmaking/
1Skills CLI (Vercel)
npx skills add EL4CTEO/roblox-skills --skill roblox-teleport-matchmaking -a codex2Manually: put the files in place
.agents/skills/roblox-teleport-matchmaking/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add EL4CTEO/roblox-skills --skill roblox-teleport-matchmaking -a cursor2Manually: put the files in place
.cursor/skills/roblox-teleport-matchmaking/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install EL4CTEO/roblox-skills skills/roblox-teleport-matchmaking2Manually: put the files in place
.github/skills/roblox-teleport-matchmaking/SKILL.md1Skills CLI (Vercel)
npx skills add EL4CTEO/roblox-skills --skill roblox-teleport-matchmaking -a gemini-cli2Platform CLI
gemini skills install https://github.com/EL4CTEO/roblox-skills --path skills/roblox-teleport-matchmakingManually: put the files in place
.devin/skills/roblox-teleport-matchmaking/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add EL4CTEO/roblox-skills --skill roblox-teleport-matchmaking -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about roblox-teleport-matchmaking
How to install roblox-teleport-matchmaking in Claude Code?
Run npx skills add EL4CTEO/roblox-skills --skill roblox-teleport-matchmaking -a claude-code followed by ~/.claude/skills/roblox-teleport-matchmaking/SKILL.md.
What does roblox-teleport-matchmaking do?
The skill provides guidelines and Luau snippets for managing player teleports, reserved servers, queues, and matchmaking in Roblox experiences.
What is required to run server scripts in Roblox?
You need appropriate Creator Dashboard access permissions and a working Roblox Studio environment supporting Luau.
Source text
SKILL.md · MIT
---
name: roblox-teleport-matchmaking
description: 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.
---
# 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`, or
**`Secure 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)
```luau
--!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 safeTeleport
```
`TeleportOptions` (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.PrivateServerId` equals that GUID.
- `VipServerId = id` → a player's **VIP server** (its `game.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);
handle `TeleportInitFailed` (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 with `player:GetJoinData().TeleportData`
(server) or `TeleportService: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's `PrivateServerId`.
Deprecated: `Teleport`, `TeleportToPlaceInstance`, `TeleportToPrivateServer`, `TeleportPartyAsync`,
`TeleportToSpawnByName` → `TeleportAsync` + `TeleportOptions`. `ReserveServer`/`ReserveServerAsync`,
`ShouldReserveServer`, and `ReservedServerAccessCode` → `ReservedServerId` (old access codes still work).
```luau
--!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 teleportToNewMatch
```
## Data handoff between places
1. Save the player's data **before** teleporting (ProfileStore: end the session / wait for save).
2. The destination loads with session locking (ProfileStore retries while the old server releases).
3. For match parameters (mode, map, team assignments), write a MemoryStore/DataStore entry keyed by
the reserved server's id (the `ReservedServerId` GUID) before teleporting; the match server reads
`game.PrivateServerId` on start and loads its config.
4. On arrival, `TeleportService:SetTeleportGui(gui)` (client, before teleport) keeps a loading screen
up across the transition; use `ReplicatedFirst` loading 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
1. Players queue in the lobby (party leader invites; party members stored server-side).
2. Queue in a **MemoryStoreQueue** / sorted map by mode and rating (see `roblox-data-stores`), or use
Roblox matchmaking to fill public servers.
3. When a match forms: generate a GUID, write match config to MemoryStore keyed by it, then `TeleportAsync`
all players with `ReservedServerId = guid` (the match server reads its config via `game.PrivateServerId`).
4. 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`); `InitializeServerAttributesForStudio` for testing.
- 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:BindToClose` for shutdown saves; `game.JobId` identifies the server; soft shutdowns after updates
(Open Cloud `:restartServers` or "Restart servers for updates") teleport players to fresh servers.
- Server browsers: each server heartbeats `{ jobId, players, mode }` into a MemoryStore sorted map
(TTL) — see `roblox-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).
© EL4CTEO · MIT · EL4CTEO/roblox-skills