Skip to content

Souvik-223/agent-skills-agentic-tools / .agents/skills/game-development/roblox-games

roblox-game

Verified

Expert Roblox game development companion — Luau, Roblox Studio, MCP integration, simulator, tycoon, obby, RPG, horror, battle royale, game design, security, performance.

FileKindSize
.gitignoreother9 B
README.mdmarkdown5.2 KB
SKILL.mdskill md5.1 KB
docs/plans/2026-03-04-roblox-game-skill-design.mdmarkdown11.6 KB
docs/plans/2026-03-04-roblox-game-skill-plan/_index.mdmarkdown5.3 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-001-create-directory-structure.mdmarkdown753 B
docs/plans/2026-03-04-roblox-game-skill-plan/task-002-write-skill-router.mdmarkdown1.5 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-003-luau-mastery.mdmarkdown2.1 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-004-architecture-patterns.mdmarkdown2.1 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-005-mcp-orchestration.mdmarkdown2.5 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-006-security-hardening.mdmarkdown2.2 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-007-datastore-persistence.mdmarkdown2.2 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-008-gui-systems.mdmarkdown2.1 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-009-performance-optimization.mdmarkdown2.2 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-010-monetization-systems.mdmarkdown2.3 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-011-combat-systems.mdmarkdown1.8 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-012-inventory-systems.mdmarkdown1.8 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-013-game-design-roblox.mdmarkdown2.1 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-014-tooling-ecosystem.mdmarkdown1.9 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-015-animation-vfx.mdmarkdown2.0 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-016-multiplayer-networking.mdmarkdown1.9 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-017-testing-patterns.mdmarkdown1.9 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-018-sharp-edges.mdmarkdown2.7 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-019-game-scaffold.mdmarkdown1.7 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-020-genre-simulator.mdmarkdown1.8 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-021-genre-tycoon.mdmarkdown1.3 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-022-genre-obby.mdmarkdown1.4 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-023-genre-rpg.mdmarkdown1.5 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-024-genre-horror.mdmarkdown1.6 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-025-genre-battle-royale.mdmarkdown1.7 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-026-workflow-new-game.mdmarkdown1.6 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-027-workflow-debug-loop.mdmarkdown1.4 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-028-workflow-performance-audit.mdmarkdown1.4 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-029-workflow-security-audit.mdmarkdown1.4 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-030-workflow-publish-checklist.mdmarkdown1.7 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-031-workflow-monetization-audit.mdmarkdown1.5 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-032-workflow-code-review.mdmarkdown1.6 KB
references/animation-vfx.mdmarkdown38.4 KB
references/architecture-patterns.mdmarkdown32.2 KB
references/combat-systems.mdmarkdown42.0 KB
references/datastore-persistence.mdmarkdown31.6 KB
references/game-design-roblox.mdmarkdown34.9 KB
references/gui-systems.mdmarkdown46.2 KB
references/inventory-systems.mdmarkdown51.7 KB
references/luau-mastery.mdmarkdown42.9 KB
references/mcp-orchestration.mdmarkdown16.4 KB
references/monetization-systems.mdmarkdown24.4 KB
references/multiplayer-networking.mdmarkdown50.0 KB
references/performance-optimization.mdmarkdown17.7 KB
references/security-hardening.mdmarkdown35.2 KB
references/sharp-edges.mdmarkdown40.3 KB
references/testing-patterns.mdmarkdown29.6 KB
references/tooling-ecosystem.mdmarkdown29.2 KB
templates/game-scaffold.mdmarkdown57.6 KB
templates/genre-battle-royale.mdmarkdown44.2 KB
templates/genre-horror.mdmarkdown49.9 KB
templates/genre-obby.mdmarkdown26.0 KB
templates/genre-rpg.mdmarkdown43.2 KB
templates/genre-simulator.mdmarkdown48.7 KB
templates/genre-tycoon.mdmarkdown50.9 KB
workflows/code-review.mdmarkdown10.3 KB
workflows/debug-loop.mdmarkdown7.8 KB
workflows/monetization-audit.mdmarkdown11.3 KB
workflows/new-game.mdmarkdown19.6 KB
workflows/performance-audit.mdmarkdown7.6 KB
workflows/publish-checklist.mdmarkdown9.6 KB
workflows/security-audit.mdmarkdown9.1 KB

references/multiplayer-networking.md

View on GitHub
# Roblox Multiplayer & Networking Reference

---

## 1. Overview

**Load this reference when:**

- Designing multiplayer game loops (rounds, lobbies, arenas)
- Implementing matchmaking or queue systems
- Building cross-server features (global chat, trading, server browsing)
- Working with TeleportService for multi-place games
- Creating team-based gameplay
- Managing player lifecycles in a multiplayer context
- Setting up private/reserved servers

This document covers player management, team systems, lobby implementation, round-based game loops, TeleportService, MessagingService, matchmaking, server instance management, and production best practices for multiplayer Roblox games.

---

## 2. Player Management

### Players Service

The `Players` service is the root of all player-related functionality. Every connected player is represented by a `Player` instance that lives as a child of `Players`.

```luau
local Players = game:GetService("Players")

-- Current player count
local count = #Players:GetPlayers()

-- Server capacity
local maxPlayers = Players.MaxPlayers

-- Iterate all connected players
for _, player in Players:GetPlayers() do
    print(player.Name, player.UserId)
end
```

### PlayerAdded / PlayerRemoving

These are the two most important events for multiplayer games. They fire on the server when a player joins or leaves.

```luau
-- ServerScriptService/PlayerManager.luau

local Players = game:GetService("Players")

local function onPlayerAdded(player: Player)
    -- Load saved data
    -- Initialize player state (score, team assignment, inventory)
    -- Grant starter gear
    -- Teleport to lobby spawn
    print(`{player.Name} joined (UserId: {player.UserId})`)
end

local function onPlayerRemoving(player: Player)
    -- Save player data (CRITICAL: do this before the player object is destroyed)
    -- Clean up any per-player state tables
    -- Notify other players
    -- Update team balance
    print(`{player.Name} leaving`)
end

Players.PlayerAdded:Connect(onPlayerAdded)
Players.PlayerRemoving:Connect(onPlayerRemoving)

-- Handle players who joined before this script ran (studio edge case)
for _, player in Players:GetPlayers() do
    task.spawn(onPlayerAdded, player)
end
```

**Critical rule:** Always handle `PlayerRemoving` to save data. The player object and its descendants are destroyed shortly after this event fires. If you yield too long (e.g., a slow DataStore call), you risk losing the save. Use `game:BindToClose()` as a fallback for server shutdowns.

### CharacterAdded / CharacterRemoving

Each player's character is a `Model` in `Workspace` that contains the `Humanoid`, body parts, and accessories. Characters are created and destroyed on respawn.

```luau
local function onCharacterAdded(character: Model)
    local humanoid = character:WaitForChild("Humanoid")
    local rootPart = character:WaitForChild("HumanoidRootPart")

    -- Set custom health
    humanoid.MaxHealth = 150
    humanoid.Health = 150

    -- Listen for death
    humanoid.Died:Connect(function()
        -- Award kill to attacker, update scoreboard, etc.
    end)
end

player.CharacterAdded:Connect(onCharacterAdded)
```

### LoadCharacter (Manual Respawning)

By default, Roblox auto-spawns characters. For round-based games, disable auto-spawn and control it manually:

```luau
-- In StarterPlayer properties: set CharacterAutoLoads = false
-- Or set it in script:
Players.CharacterAutoLoads = false

-- Spawn a specific player
player:LoadCharacter()

-- Spawn all players
for _, player in Players:GetPlayers() do
    task.spawn(function()
        player:LoadCharacter()
    end)
end
```

### Player Instance Lifecycle

Understanding the lifecycle prevents common bugs:

1. `PlayerAdded` fires -- Player instance exists, no character yet.
2. `CharacterAdded` fires -- Character model is parented to Workspace.
3. `CharacterRemoving` fires -- Character is about to be destroyed (death or manual removal).
4. `CharacterAdded` fires again -- Respawn.
5. `PlayerRemoving` fires -- Player is disconnecting. Character may or may not exist.

**Gotcha:** `player.Character` can be `nil` at any point. Always nil-check before accessing it.

---

## 3. Team Systems

### Teams Service

The `Teams` service holds `Team` objects. Teams are automatically replicated to all clients and show up in the default leaderboard.

```luau
local Teams = game:GetService("Teams")

-- Create teams programmatically (or place them in Studio under Teams)
local redTeam = Instance.new("Team")
redTeam.Name = "Red"
redTeam.TeamColor = BrickColor.new("Bright red")
redTeam.AutoAssignable = false -- Don't auto-assign players
redTeam.Parent = Teams

local blueTeam = Instance.new("Team")
blueTeam.Name = "Blue"
blueTeam.TeamColor = BrickColor.new("Bright blue")
blueTeam.AutoAssignable = false
blueTeam.Parent = Teams

local lobbyTeam = Instance.new("Team")
lobbyTeam.Name = "Lobby"
lobbyTeam.TeamColor = BrickColor.new("Medium stone grey")
lobbyTeam.AutoAssignable = true -- New players go here
lobbyTeam.Parent = Teams
```

### Assigning Players to Teams

```luau
-- Direct assignment
player.Team = redTeam

-- The player's nametag, leaderboard entry, and spawn location
-- all update automatically based on TeamColor.

-- Get all players on a team
local redPlayers = redTeam:GetPlayers()
print(`Red team has {#redPlayers} players`)
```

### Team-Based Logic

Always check teams on the **server** before applying damage or other competitive interactions:

```luau
local function canDamage(attacker: Player, victim: Player): boolean
    -- No friendly fire
    if attacker.Team == victim.Team then
        return false
    end

    -- No damaging lobby players
    if victim.Team == lobbyTeam then
        return false
    end

    return true
end

-- In a weapon hit handler (server-side)
local function onWeaponHit(attacker: Player, victimCharacter: Model)
    local victim = Players:GetPlayerFromCharacter(victimCharacter)
    if not victim then return end

    if not canDamage(attacker, victim) then return end

    local humanoid = victimCharacter:FindFirstChild("Humanoid")
    if humanoid then
        humanoid:TakeDamage(25)
    end
end
```

### Auto-Balancing Teams

```luau
local function getSmallestTeam(teamList: {Team}): Team
    local smallest = teamList[1]
    local smallestCount = #smallest:GetPlayers()

    for i = 2, #teamList do
        local count = #teamList[i]:GetPlayers()
        if count < smallestCount then
            smallest = teamList[i]
            smallestCount = count
        end
    end

    return smallest
end

-- Assign player to the team with fewer members
local function assignToBalancedTeam(player: Player)
    player.Team = getSmallestTeam({ redTeam, blueTeam })
end
```

---

## 4. Lobby System

A lobby holds players in a waiting area until enough are ready to start a round. This implementation tracks ready states, shows a ready-up GUI, enforces a minimum player threshold, and auto-starts after a timeout.

### Server-Side Lobby Manager

```luau
-- ServerScriptService/LobbyManager.luau

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

local LobbyRemotes = Instance.new("Folder")
LobbyRemotes.Name = "LobbyRemotes"
LobbyRemotes.Parent = ReplicatedStorage

local ReadyUpEvent = Instance.new("RemoteEvent")
ReadyUpEvent.Name = "ReadyUp"
ReadyUpEvent.Parent = LobbyRemotes

local LobbyStatusEvent = Instance.new("RemoteEvent")
LobbyStatusEvent.Name = "LobbyStatus"
LobbyStatusEvent.Parent = LobbyRemotes

-- Configuration
local MIN_PLAYERS = 2
local MAX_WAIT_TIME = 60 -- seconds to auto-start after minimum reached
local COUNTDOWN_DURATION = 10 -- final countdown before round starts

-- State
local readyPlayers: { [Player]: boolean } = {}
local lobbyActive = true
local countdownRunning = false

local function getReadyCount(): number
    local count = 0
    for player, isReady in readyPlayers do
        -- Verify the player is still connected
        if isReady and player.Parent == Players then
            count += 1
        end
    end
    return count
end

local function getTotalPlayers(): number
    return #Players:GetPlayers()
end

local function broadcastStatus(message: string, countdown: number?)
    for _, player in Players:GetPlayers() do
        LobbyStatusEvent:FireClient(player, message, countdown, getReadyCount(), getTotalPlayers())
    end
end

local function shouldStart(): boolean
    return getTotalPlayers() >= MIN_PLAYERS and getReadyCount() >= MIN_PLAYERS
end

local function startCountdown()
    if countdownRunning then return end
    countdownRunning = true

    for i = COUNTDOWN_DURATION, 1, -1 do
        if not lobbyActive then
            countdownRunning = false
            return
        end

        -- Recheck player count (someone may have left)
        if getTotalPlayers() < MIN_PLAYERS then
            broadcastStatus("Not enough players. Waiting...", nil)
            countdownRunning = false
            return
        end

        broadcastStatus(`Round starting in {i}...`, i)
        task.wait(1)
    end

    countdownRunning = false
    lobbyActive = false
    broadcastStatus("Round starting!", 0)

    -- Signal to round manager (see Section 5)
    local RoundManager = require(script.Parent:WaitForChild("RoundManager"))
    RoundManager.startRound()
end

-- Handle ready-up toggle
ReadyUpEvent.OnServerEvent:Connect(function(player: Player)
    if not lobbyActive then return end

    readyPlayers[player] = not readyPlayers[player]
    broadcastStatus(
        if readyPlayers[player] then `{player.Name} is ready!` else `{player.Name} unreadied.`,
        nil
    )

    if shouldStart() and not countdownRunning then
        task.spawn(startCountdown)
    end
end)

-- Clean up when players leave
Players.PlayerRemoving:Connect(function(player: Player)
    readyPlayers[player] = nil

    if lobbyActive then
        broadcastStatus(`{player.Name} left the lobby.`, nil)
    end
end)

-- Auto-start timer: once minimum players are present, start a background timer
task.spawn(function()
    local waitElapsed = 0
    while lobbyActive do
        task.wait(1)
        if getTotalPlayers() >= MIN_PLAYERS then
            waitElapsed += 1
            if waitElapsed >= MAX_WAIT_TIME and not countdownRunning then
                -- Force all present players to ready
                for _, player in Players:GetPlayers() do
                    readyPlayers[player] = true
                end
                task.spawn(startCountdown)
            end
        else
            waitElapsed = 0
        end
    end
end)

-- Public API for reset
local LobbyManager = {}

function LobbyManager.reset()
    readyPlayers = {}
    lobbyActive = true
    countdownRunning = false
    broadcastStatus("Lobby open. Ready up!", nil)
end

return LobbyManager
```

### Client-Side Ready-Up GUI

```luau
-- StarterPlayerScripts/LobbyGui.client.luau

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

local player = Players.LocalPlayer
local playerGui = player:WaitForChild("PlayerGui")
local lobbyRemotes = ReplicatedStorage:WaitForChild("LobbyRemotes")
local readyUpEvent = lobbyRemotes:WaitForChild("ReadyUp")
local lobbyStatusEvent = lobbyRemotes:WaitForChild("LobbyStatus")

-- Build GUI
local screenGui = Instance.new("ScreenGui")
screenGui.Name = "LobbyGui"
screenGui.ResetOnSpawn = false
screenGui.Parent = playerGui

local frame = Instance.new("Frame")
frame.Size = UDim2.fromScale(0.3, 0.15)
frame.Position = UDim2.fromScale(0.35, 0.8)
frame.BackgroundColor3 = Color3.fromRGB(30, 30, 30)
frame.BackgroundTransparency = 0.3
frame.Parent = screenGui

local uiCorner = Instance.new("UICorner")
uiCorner.CornerRadius = UDim.new(0, 12)
uiCorner.Parent = frame

local statusLabel = Instance.new("TextLabel")
statusLabel.Size = UDim2.fromScale(1, 0.5)
statusLabel.BackgroundTransparency = 1
statusLabel.TextColor3 = Color3.new(1, 1, 1)
statusLabel.TextScaled = true
statusLabel.Text = "Waiting for players..."
statusLabel.Parent = frame

local readyButton = Instance.new("TextButton")
readyButton.Size = UDim2.fromScale(0.6, 0.4)
readyButton.Position = UDim2.fromScale(0.2, 0.55)
readyButton.BackgroundColor3 = Color3.fromRGB(0, 170, 0)
readyButton.TextColor3 = Color3.new(1, 1, 1)
readyButton.TextScaled = true
readyButton.Text = "Ready Up"
readyButton.Parent = frame

local readyCorner = Instance.new("UICorner")
readyCorner.CornerRadius = UDim.new(0, 8)
readyCorner.Parent = readyButton

local isReady = false

readyButton.Activated:Connect(function()
    isReady = not isReady
    readyButton.Text = if isReady then "Unready" else "Ready Up"
    readyButton.BackgroundColor3 = if isReady
        then Color3.fromRGB(170, 0, 0)
        else Color3.fromRGB(0, 170, 0)
    readyUpEvent:FireServer()
end)

lobbyStatusEvent.OnClientEvent:Connect(function(message: string, countdown: number?, readyCount: number, totalCount: number)
    statusLabel.Text = `{message}\nReady: {readyCount}/{totalCount}`

    if countdown and countdown == 0 then
        screenGui.Enabled = false
    end
end)
```

---

## 5. Round-Based Games

### Round Lifecycle State Machine

A production round system follows a clear state machine:

```
Intermission --> Countdown --> Playing --> Results --> Intermission
```

Each state has entry/exit logic, and the system must handle players joining and leaving at any point.

### Complete Round Manager Implementation

```luau
-- ServerScriptService/RoundManager.luau

local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ServerStorage = game:GetService("ServerStorage")
local Teams = game:GetService("Teams")

-- Remotes
local RoundRemotes = Instance.new("Folder")
RoundRemotes.Name = "RoundRemotes"
RoundRemotes.Parent = ReplicatedStorage

local RoundStateEvent = Instance.new("RemoteEvent")
RoundStateEvent.Name = "RoundState"
RoundStateEvent.Parent = RoundRemotes

local ScoreUpdateEvent = Instance.new("RemoteEvent")
ScoreUpdateEvent.Name = "ScoreUpdate"
ScoreUpdateEvent.Parent = RoundRemotes

-- Configuration
local INTERMISSION_TIME = 15
local COUNTDOWN_TIME = 5
local ROUND_TIME = 120 -- 2 minutes per round
local RESULTS_TIME = 10
local SCORE_TO_WIN = 10

-- Map pool (models stored in ServerStorage/Maps/)
local MAP_NAMES = { "Desert", "Forest", "City" }

-- State
export type RoundState = "Intermission" | "Countdown" | "Playing" | "Results"

local currentState: RoundState = "Intermission"
local currentMap: Model? = nil
local currentMapName: string = ""
local roundNumber = 0
local mapRotationIndex = 0
local playerScores: { [Player]: number } = {}
local roundParticipants: { Player } = {}

-- Teams (assumed created elsewhere or created here)
local redTeam = Teams:FindFirstChild("Red")
local blueTeam = Teams:FindFirstChild("Blue")
local lobbyTeam = Teams:FindFirstChild("Lobby")

local RoundManager = {}

-- Utility: broadcast state to all clients
local function broadcastState(state: RoundState, data: { [string]: any }?)
    for _, player in Players:GetPlayers() do
        RoundStateEvent:FireClient(player, state, data or {})
    end
end

-- Utility: broadcast scores
local function broadcastScores()
    local scores = {}
    for player, score in playerScores do
        if player.Parent == Players then
            scores[player.Name] = score
        end
    end
    for _, player in Players:GetPlayers() do
        ScoreUpdateEvent:FireClient(player, scores)
    end
end

-- Map Selection: sequential rotation (can be changed to random)
local function selectNextMap(): string
    mapRotationIndex = (mapRotationIndex % #MAP_NAMES) + 1
    return MAP_NAMES[mapRotationIndex]
end

-- Load map into workspace
local function loadMap(mapName: string): Model?
    local mapsFolder = ServerStorage:FindFirstChild("Maps")
    if not mapsFolder then
        warn("Maps folder not found in ServerStorage")
        return nil
    end

    local mapTemplate = mapsFolder:FindFirstChild(mapName)
    if not mapTemplate then
        warn(`Map "{mapName}" not found`)
        return nil
    end

    local mapClone = mapTemplate:Clone()
    mapClone.Name = "ActiveMap"
    mapClone.Parent = workspace
    return mapClone
end

-- Remove current map
local function unloadMap()
    if currentMap then
        currentMap:Destroy()
        currentMap = nil
    end
end

-- Get spawn points from the active map
local function getSpawnPoints(teamName: string): { BasePart }
    if not currentMap then return {} end

    local spawns = {}
    local spawnFolder = currentMap:FindFirstChild(teamName .. "Spawns")
    if spawnFolder then
        for _, spawn in spawnFolder:GetChildren() do
            if spawn:IsA("BasePart") then
                table.insert(spawns, spawn)
            end
        end
    end
    return spawns
end

-- Teleport player to a spawn point
local function teleportToSpawn(player: Player, spawnPoints: { BasePart })
    if #spawnPoints == 0 then return end
    if not player.Character then return end

    local rootPart = player.Character:FindFirstChild("HumanoidRootPart")
    if not rootPart then return end

    local spawn = spawnPoints[math.random(1, #spawnPoints)]
    rootPart.CFrame = spawn.CFrame + Vector3.new(0, 5, 0)
end

-- Teleport player back to lobby
local function teleportToLobby(player: Player)
    local lobbySpawn = workspace:FindFirstChild("LobbySpawn")
    if not lobbySpawn or not player.Character then return end

    local rootPart = player.Character:FindFirstChild("HumanoidRootPart")
    if rootPart then
        rootPart.CFrame = lobbySpawn.CFrame + Vector3.new(0, 5, 0)
    end
end

-- Assign players to balanced teams
local function assignTeams()
    local players = Players:GetPlayers()
    roundParticipants = {}

    -- Shuffle for fairness
    for i = #players, 2, -1 do
        local j = math.random(1, i)
        players[i], players[j] = players[j], players[i]
    end

    for i, player in players do
        if i % 2 == 1 then
            player.Team = redTeam
        else
            player.Team = blueTeam
        end
        playerScores[player] = 0
        table.insert(roundParticipants, player)
    end
end

-- Register a kill/score
function RoundManager.addScore(player: Player, points: number)
    if currentState ~= "Playing" then return end
    if not playerScores[player] then return end

    playerScores[player] += points
    broadcastScores()
end

-- Determine winner
local function determineWinner(): (string, Player?)
    local topPlayer: Player? = nil
    local topScore = 0

    -- Individual scores
    for player, score in playerScores do
        if player.Parent == Players and score > topScore then
            topScore = score
            topPlayer = player
        end
    end

    -- Team scores
    local redScore, blueScore = 0, 0
    for player, score in playerScores do
        if player.Parent ~= Players then continue end
        if player.Team == redTeam then
            redScore += score
        elseif player.Team == blueTeam then
            blueScore += score
        end
    end

    local winningTeam = "Tie"
    if redScore > blueScore then
        winningTeam = "Red"
    elseif blueScore > redScore then
        winningTeam = "Blue"
    end

    return winningTeam, topPlayer
end

-- Check if a player reached the score limit
local function checkScoreLimit(): boolean
    for _, score in playerScores do
        if score >= SCORE_TO_WIN then
            return true
        end
    end
    return false
end

-- State: Intermission
local function stateIntermission()
    currentState = "Intermission"
    roundNumber += 1

    -- Move all players to lobby team
    for _, player in Players:GetPlayers() do
        player.Team = lobbyTeam
        task.spawn(function()
            player:LoadCharacter()
            task.wait(0.5)
            teleportToLobby(player)
        end)
    end

    unloadMap()
    currentMapName = selectNextMap()
    broadcastState("Intermission", { duration = INTERMISSION_TIME, nextMap = currentMapName, round = roundNumber })

    for i = INTERMISSION_TIME, 1, -1 do
        broadcastState("Intermission", { timeLeft = i, nextMap = currentMapName, round = roundNumber })
        task.wait(1)
    end
end

-- State: Countdown
local function stateCountdown()
    currentState = "Countdown"

    -- Load map
    currentMap = loadMap(currentMapName)

    -- Assign teams and reset scores
    assignTeams()

    -- Spawn characters at team spawn points
    for _, player in roundParticipants do
        if player.Parent ~= Players then continue end

        task.spawn(function()
            player:LoadCharacter()
            task.wait(0.5) -- brief wait for character to load

            local teamName = if player.Team == redTeam then "Red" else "Blue"
            teleportToSpawn(player, getSpawnPoints(teamName))
        end)
    end

    -- Freeze players during countdown (disable movement)
    -- This is optional but improves feel
    for i = COUNTDOWN_TIME, 1, -1 do
        broadcastState("Countdown", { timeLeft = i })
        task.wait(1)
    end
end

-- State: Playing
local function statePlaying()
    currentState = "Playing"
    playerScores = {}
    for _, player in roundParticipants do
        if player.Parent == Players then
            playerScores[player] = 0
        end
    end

    broadcastState("Playing", { duration = ROUND_TIME })
    broadcastScores()

    -- Round timer with early exit on score limit
    for i = ROUND_TIME, 1, -1 do
        if currentState ~= "Playing" then break end

        if checkScoreLimit() then
            break
        end

        broadcastState("Playing", { timeLeft = i })
        task.wait(1)
    end
end

-- State: Results
local function stateResults()
    currentState = "Results"

    local winningTeam, topPlayer = determineWinner()
    local topPlayerName = if topPlayer then topPlayer.Name else "Nobody"

    broadcastState("Results", {
        winningTeam = winningTeam,
        topPlayer = topPlayerName,
        duration = RESULTS_TIME,
    })

    task.wait(RESULTS_TIME)
end

-- Handle player death during a round (respawn at team spawn)
local function onCharacterDied(player: Player)
    if currentState ~= "Playing" then return end

    task.wait(3) -- respawn delay
    if player.Parent ~= Players then return end
    if currentState ~= "Playing" then return end

    player:LoadCharacter()
    task.wait(0.5)

    local teamName = if player.Team == redTeam then "Red" else "Blue"
    teleportToSpawn(player, getSpawnPoints(teamName))
end

-- Wire up character death tracking
Players.PlayerAdded:Connect(function(player)
    player.CharacterAdded:Connect(function(character)
        local humanoid = character:WaitForChild("Humanoid")
        humanoid.Died:Connect(function()
            onCharacterDied(player)
        end)
    end)
end)

-- Clean up player from round on disconnect
Players.PlayerRemoving:Connect(function(player)
    playerScores[player] = nil
    local idx = table.find(roundParticipants, player)
    if idx then
        table.remove(roundParticipants, idx)
    end
end)

-- Main game loop
function RoundManager.startRound()
    while true do
        stateIntermission()
        stateCountdown()
        statePlaying()
        stateResults()
    end
end

-- Start automatically or called from LobbyManager
return RoundManager
```

### Client-Side Round HUD

```luau
-- StarterPlayerScripts/RoundHud.client.luau

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local playerGui = player:WaitForChild("PlayerGui")

local roundRemotes = ReplicatedStorage:WaitForChild("RoundRemotes")
local roundStateEvent = roundRemotes:WaitForChild("RoundState")
local scoreUpdateEvent = roundRemotes:WaitForChild("ScoreUpdate")

-- Build HUD (top-center status bar)
local screenGui = Instance.new("ScreenGui")
screenGui.Name = "RoundHud"
screenGui.ResetOnSpawn = false
screenGui.Parent = playerGui

local statusLabel = Instance.new("TextLabel")
statusLabel.Size = UDim2.fromScale(0.4, 0.06)
statusLabel.Position = UDim2.fromScale(0.3, 0.02)
statusLabel.BackgroundColor3 = Color3.fromRGB(20, 20, 20)
statusLabel.BackgroundTransparency = 0.4
statusLabel.TextColor3 = Color3.new(1, 1, 1)
statusLabel.TextScaled = true
statusLabel.Font = Enum.Font.GothamBold
statusLabel.Parent = screenGui

local uiCorner = Instance.new("UICorner")
uiCorner.CornerRadius = UDim.new(0, 8)
uiCorner.Parent = statusLabel

roundStateEvent.OnClientEvent:Connect(function(state: string, data: { [string]: any })
    if state == "Intermission" then
        local timeLeft = data.timeLeft or data.duration
        statusLabel.Text = `INTERMISSION | Next: {data.nextMap or "?"} | {timeLeft}s`
        statusLabel.BackgroundColor3 = Color3.fromRGB(40, 40, 100)
    elseif state == "Countdown" then
        statusLabel.Text = `GET READY! {data.timeLeft}`
        statusLabel.BackgroundColor3 = Color3.fromRGB(200, 150, 0)
    elseif state == "Playing" then
        statusLabel.Text = `ROUND | {data.timeLeft or data.duration}s`
        statusLabel.BackgroundColor3 = Color3.fromRGB(0, 120, 0)
    elseif state == "Results" then
        statusLabel.Text = `{data.winningTeam} wins! MVP: {data.topPlayer}`
        statusLabel.BackgroundColor3 = Color3.fromRGB(150, 50, 0)
    end
end)

scoreUpdateEvent.OnClientEvent:Connect(function(scores: { [string]: number })
    -- Update a scoreboard UI (implementation depends on your UI framework)
end)
```

---

## 6. TeleportService

TeleportService handles moving players between places (separate experiences within a universe) or between servers of the same place.

### Multi-Place Architecture

A typical multi-place setup:

```
Universe (Experience)
  |-- Hub/Lobby Place (start place)
  |-- Arena Place
  |-- Minigame Place A
  |-- Minigame Place B
```

Each place has its own PlaceId. Players start at the start place and are teleported to sub-places.

### TeleportAsync

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

local ARENA_PLACE_ID = 123456789 -- Replace with your actual PlaceId

-- Teleport a single player
local function teleportPlayer(player: Player)
    local success, result = pcall(function()
        return TeleportService:TeleportAsync(ARENA_PLACE_ID, { player })
    end)

    if not success then
        warn(`Teleport failed for {player.Name}: {result}`)
    end
end

-- Teleport a group of players together (they land on the same server)
local function teleportGroup(players: { Player })
    local success, result = pcall(function()
        return TeleportService:TeleportAsync(ARENA_PLACE_ID, players)
    end)

    if not success then
        warn(`Group teleport failed: {result}`)
    end
end
```

### TeleportOptions and Data Passing

`TeleportOptions` lets you configure the teleport and pass data between places.

```luau
local function teleportWithData(players: { Player }, matchData: { [string]: any })
    local teleportOptions = Instance.new("TeleportOptions")

    -- Pass data that all players in this teleport can read on arrival
    teleportOptions:SetTeleportData({
        matchId = matchData.matchId,
        gameMode = matchData.gameMode,
        teams = matchData.teams,
    })

    -- Optionally target a reserved server
    if matchData.reservedCode then
        teleportOptions.ReservedServerAccessCode = matchData.reservedCode
    end

    local success, result = pcall(function()
        return TeleportService:TeleportAsync(ARENA_PLACE_ID, players, teleportOptions)
    end)

    if not success then
        warn(`Teleport with data failed: {result}`)
    end
end
```

### Reading Teleport Data on Arrival

```luau
-- In the destination place's server script
local TeleportService = game:GetService("TeleportService")
local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player: Player)
    local joinData = player:GetJoinData()
    local teleportData = joinData.TeleportData

    if teleportData then
        print(`Player {player.Name} arrived with match ID: {teleportData.matchId}`)
        print(`Game mode: {teleportData.gameMode}`)
        -- Use this data to set up the match
    end
end)
```

### ReservedServer for Private Matches

Reserved servers are free, programmatically-created private servers. They are essential for matchmaking.

```luau
local TeleportService = game:GetService("TeleportService")

local ARENA_PLACE_ID = 123456789

-- Step 1: Reserve a server (returns an access code)
local success, accessCode = pcall(function()
    return TeleportService:ReserveServer(ARENA_PLACE_ID)
end)

if not success then
    warn(`Failed to reserve server: {accessCode}`)
    return
end

-- Step 2: Teleport players to the reserved server
local teleportOptions = Instance.new("TeleportOptions")
teleportOptions.ReservedServerAccessCode = accessCode
teleportOptions:SetTeleportData({
    matchId = "MATCH_001",
    gameMode = "Deathmatch",
})

local success2, err = pcall(function()
    TeleportService:TeleportAsync(ARENA_PLACE_ID, playersToTeleport, teleportOptions)
end)

if not success2 then
    warn(`Teleport to reserved server failed: {err}`)
end
```

### Teleport Error Handling

Teleports can fail for many reasons (rate limits, player in another teleport, server full). Always handle failures.

```luau
local TeleportService = game:GetService("TeleportService")

-- Listen for teleport failures (fires on the client)
-- Server-side retry pattern:
local MAX_RETRIES = 3
local RETRY_DELAY = 2

local function teleportWithRetry(placeId: number, players: { Player }, options: TeleportOptions?)
    for attempt = 1, MAX_RETRIES do
        local success, result = pcall(function()
            return TeleportService:TeleportAsync(placeId, players, options)
        end)

        if success then
            return true
        end

        warn(`Teleport attempt {attempt}/{MAX_RETRIES} failed: {result}`)

        if attempt < MAX_RETRIES then
            task.wait(RETRY_DELAY)

            -- Remove disconnected players before retry
            local validPlayers = {}
            for _, player in players do
                if player.Parent then
                    table.insert(validPlayers, player)
                end
            end
            players = validPlayers

            if #players == 0 then
                return false
            end
        end
    end

    warn("All teleport retries exhausted")
    return false
end
```

### TeleportInitFailed (Client-Side)

```luau
-- StarterPlayerScripts/TeleportHandler.client.luau

local TeleportService = game:GetService("TeleportService")

TeleportService.TeleportInitFailed:Connect(function(player, teleportResult, errorMessage)
    warn(`Teleport failed: {teleportResult} - {errorMessage}`)
    -- Show error UI to the player
end)
```

---

## 7. MessagingService

MessagingService provides cross-server publish/subscribe messaging. Messages sent from one server can be received by all other servers in the same experience.

### Basic Pub/Sub

```luau
local MessagingService = game:GetService("MessagingService")

local TOPIC = "GlobalAnnouncements"

-- Subscribe to a topic (do this once on server startup)
local success, subscription = pcall(function()
    return MessagingService:SubscribeAsync(TOPIC, function(message)
        -- message.Data contains the published data
        -- message.Sent is the Unix timestamp when it was published
        local data = message.Data
        print(`[Global] {data.text} (from server {data.serverId})`)

        -- Broadcast to all players on this server
        for _, player in game:GetService("Players"):GetPlayers() do
            -- Fire a remote to show announcement UI
        end
    end)
end)

if not success then
    warn(`Failed to subscribe to {TOPIC}: {subscription}`)
end

-- Publish a message (all subscribed servers receive it, including this one)
local function announce(text: string)
    local success, err = pcall(function()
        MessagingService:PublishAsync(TOPIC, {
            text = text,
            serverId = game.JobId,
            timestamp = os.time(),
        })
    end)

    if not success then
        warn(`Failed to publish to {TOPIC}: {err}`)
    end
end
```

### Rate Limits

MessagingService has strict rate limits. Exceeding them causes errors.

| Limit | Value |
|---|---|
| **PublishAsync** | 150 + 60 * numPlayers messages per minute |
| **SubscribeAsync** | 5 + 2 * numPlayers subscriptions per minute |
| **Message size** | 1 KB per message |
| **Messages received** | (150 + 60 * numPlayers) * numSubscriptions per minute |

For a server with 20 players: 150 + 60 * 20 = **1,350 publishes per minute**.

### Use Case: Global Server List

```luau
-- ServerScriptService/ServerList.luau

local MessagingService = game:GetService("MessagingService")
local Players = game:GetService("Players")
local HttpService = game:GetService("HttpService")

local HEARTBEAT_TOPIC = "ServerHeartbeat"
local HEARTBEAT_INTERVAL = 30 -- seconds

-- Subscribe to heartbeats from other servers
local serverList: { [string]: { playerCount: number, maxPlayers: number, lastSeen: number } } = {}

pcall(function()
    MessagingService:SubscribeAsync(HEARTBEAT_TOPIC, function(message)
        local data = message.Data
        serverList[data.jobId] = {
            playerCount = data.playerCount,
            maxPlayers = data.maxPlayers,
            lastSeen = os.time(),
        }
    end)
end)

-- Broadcast this server's info periodically
task.spawn(function()
    while true do
        pcall(function()
            MessagingService:PublishAsync(HEARTBEAT_TOPIC, {
                jobId = game.JobId,
                playerCount = #Players:GetPlayers(),
                maxPlayers = Players.MaxPlayers,
            })
        end)
        task.wait(HEARTBEAT_INTERVAL)
    end
end)

-- Prune stale servers
task.spawn(function()
    while true do
        task.wait(60)
        local now = os.time()
        for jobId, info in serverList do
            if now - info.lastSeen > 90 then
                serverList[jobId] = nil
            end
        end
    end
end)
```

### Use Case: Cross-Server Global Events

```luau
-- Trigger a global event (e.g., double XP, boss spawn, holiday event)
local EVENTS_TOPIC = "GlobalEvents"

-- Publisher (admin server or admin command)
local function triggerGlobalEvent(eventName: string, duration: number)
    pcall(function()
        MessagingService:PublishAsync(EVENTS_TOPIC, {
            event = eventName,
            startTime = os.time(),
            duration = duration,
        })
    end)
end

-- Subscriber (every server)
pcall(function()
    MessagingService:SubscribeAsync(EVENTS_TOPIC, function(message)
        local data = message.Data
        if data.event == "DoubleXP" then
            -- Set a global multiplier
            _G.XPMultiplier = 2
            task.delay(data.duration, function()
                _G.XPMultiplier = 1
            end)
        end
    end)
end)
```

---

## 8. Matchmaking

Roblox does not provide a built-in matchmaking service. You must build one using DataStores, TeleportService, and optionally MessagingService.

### Concepts

- **Skill-Based Matching:** Track player skill (ELO, MMR, rank) in a DataStore. Match players with similar ratings.
- **Queue System:** Players join a queue. When enough players are queued, create a reserved server and teleport them.
- **Party Queuing:** Groups of friends queue together as a unit.

### ELO/MMR Tracking

```luau
-- ServerScriptService/Modules/EloSystem.luau

local DataStoreService = game:GetService("DataStoreService")
local eloStore = DataStoreService:GetDataStore("PlayerElo")

local EloSystem = {}

local DEFAULT_ELO = 1000
local K_FACTOR = 32

function EloSystem.getElo(userId: number): number
    local success, elo = pcall(function()
        return eloStore:GetAsync(`elo_{userId}`)
    end)
    return if success and elo then elo else DEFAULT_ELO
end

function EloSystem.saveElo(userId: number, elo: number)
    pcall(function()
        eloStore:SetAsync(`elo_{userId}`, math.floor(elo))
    end)
end

function EloSystem.calculateNewElo(winnerElo: number, loserElo: number): (number, number)
    local expectedWinner = 1 / (1 + 10 ^ ((loserElo - winnerElo) / 400))
    local expectedLoser = 1 - expectedWinner

    local newWinnerElo = winnerElo + K_FACTOR * (1 - expectedWinner)
    local newLoserElo = loserElo + K_FACTOR * (0 - expectedLoser)

    return math.floor(newWinnerElo), math.max(0, math.floor(newLoserElo))
end

return EloSystem
```

### Queue System with Reserved Servers

```luau
-- ServerScriptService/MatchmakingQueue.luau

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

local EloSystem = require(script.Parent.Modules.EloSystem)

local ARENA_PLACE_ID = 123456789
local MATCH_SIZE = 2 -- 1v1
local ELO_RANGE = 200 -- max ELO difference for matching
local ELO_RANGE_EXPAND_INTERVAL = 15 -- expand range every 15 seconds
local ELO_RANGE_EXPAND_AMOUNT = 50

-- Remotes
local QueueRemote = Instance.new("RemoteEvent")
QueueRemote.Name = "QueueRemote"
QueueRemote.Parent = ReplicatedStorage

local QueueStatusRemote = Instance.new("RemoteEvent")
QueueStatusRemote.Name = "QueueStatus"
QueueStatusRemote.Parent = ReplicatedStorage

-- Queue state
type QueueEntry = {
    player: Player,
    elo: number,
    joinedAt: number,
}

local queue: { QueueEntry } = {}

local function removeFromQueue(player: Player)
    for i = #queue, 1, -1 do
        if queue[i].player == player then
            table.remove(queue, i)
            return
        end
    end
end

local function isInQueue(player: Player): boolean
    for _, entry in queue do
        if entry.player == player then
            return true
        end
    end
    return false
end

local function findMatch(entry: QueueEntry): QueueEntry?
    local now = os.time()
    local waitTime = now - entry.joinedAt
    local expandedRange = ELO_RANGE + math.floor(waitTime / ELO_RANGE_EXPAND_INTERVAL) * ELO_RANGE_EXPAND_AMOUNT

    for _, other in queue do
        if other.player == entry.player then continue end
        if math.abs(entry.elo - other.elo) <= expandedRange then
            return other
        end
    end
    return nil
end

local function createMatch(players: { Player })
    -- Reserve a server
    local success, accessCode = pcall(function()
        return TeleportService:ReserveServer(ARENA_PLACE_ID)
    end)

    if not success then
        warn(`Failed to reserve server: {accessCode}`)
        for _, player in players do
            QueueStatusRemote:FireClient(player, "Error", "Failed to create match. Please try again.")
        end
        return
    end

    -- Build match data
    local matchData = {
        matchId = game:GetService("HttpService"):GenerateGUID(false),
        players = {},
    }
    for _, player in players do
        table.insert(matchData.players, { userId = player.UserId, name = player.Name })
    end

    -- Teleport
    local teleportOptions = Instance.new("TeleportOptions")
    teleportOptions.ReservedServerAccessCode = accessCode
    teleportOptions:SetTeleportData(matchData)

    for _, player in players do
        QueueStatusRemote:FireClient(player, "MatchFound", "Teleporting to arena...")
    end

    local teleportSuccess, err = pcall(function()
        TeleportService:TeleportAsync(ARENA_PLACE_ID, players, teleportOptions)
    end)

    if not teleportSuccess then
        warn(`Match teleport failed: {err}`)
    end
end

-- Queue processing loop
task.spawn(function()
    while true do
        task.wait(1)

        -- Clean disconnected players
        for i = #queue, 1, -1 do
            if queue[i].player.Parent ~= Players then
                table.remove(queue, i)
            end
        end

        -- Attempt to find matches
        local matched: { [Player]: boolean } = {}

        for _, entry in queue do
            if matched[entry.player] then continue end

            local opponent = findMatch(entry)
            if opponent and not matched[opponent.player] then
                matched[entry.player] = true
                matched[opponent.player] = true

                -- Remove both from queue and create match
                removeFromQueue(entry.player)
                removeFromQueue(opponent.player)
                task.spawn(createMatch, { entry.player, opponent.player })
            end
        end
    end
end)

-- Handle queue join/leave
QueueRemote.OnServerEvent:Connect(function(player: Player, action: string)
    if action == "join" then
        if isInQueue(player) then return end

        local elo = EloSystem.getElo(player.UserId)
        table.insert(queue, {
            player = player,
            elo = elo,
            joinedAt = os.time(),
        })
        QueueStatusRemote:FireClient(player, "Queued", `Searching... (ELO: {elo})`)

    elseif action == "leave" then
        removeFromQueue(player)
        QueueStatusRemote:FireClient(player, "Left", "Removed from queue.")
    end
end)

-- Auto-remove on disconnect
Players.PlayerRemoving:Connect(function(player)
    removeFromQueue(player)
end)
```

---

## 9. Instance Management

### Server Types

| Type | Cost | Creation | Use Case |
|---|---|---|---|
| **Public Server** | Free | Automatic (Roblox fills them) | Default gameplay |
| **Reserved Server** | Free | `TeleportService:ReserveServer()` | Matchmaking, private matches, instanced dungeons |
| **Private Server (VIP)** | Paid (Robux, set by developer) | Player purchases via game page | Player-owned private spaces |

### Reserved Servers

Reserved servers are the backbone of custom matchmaking. They are created on demand, receive an access code, and only players with that code can join.

```luau
-- Create a reserved server
local accessCode = TeleportService:ReserveServer(placeId)

-- This code can be:
-- 1. Used immediately to teleport players
-- 2. Stored in a DataStore for later use (e.g., persistent worlds)
-- 3. Shared via MessagingService so other servers can direct players to it
```

### Server Capacity

```luau
local Players = game:GetService("Players")

-- Maximum players for this server (set in Game Settings)
print(Players.MaxPlayers) -- e.g., 50

-- Preferred player count (Roblox matchmaker target)
-- Set via Game Settings > Places > Max Players
-- For reserved servers, the limit is the place's MaxPlayers setting
```

### Detecting Server Type

```luau
-- On the destination server:
local privateServerId = game.PrivateServerId
local privateServerOwnerId = game.PrivateServerOwnerId

if privateServerId ~= "" and privateServerOwnerId == 0 then
    print("This is a Reserved Server (matchmaking)")
elseif privateServerId ~= "" and privateServerOwnerId ~= 0 then
    print(`This is a VIP/Private Server owned by UserId {privateServerOwnerId}`)
else
    print("This is a public server")
end
```

---

## 10. Best Practices

### Handle Disconnects Gracefully

```luau
-- Save data BEFORE teleporting (data can be lost during server hops)
local function safeTeleport(player: Player, placeId: number, options: TeleportOptions?)
    -- Save all player data first
    local DataManager = require(script.Parent.Modules.DataManager)
    DataManager.savePlayerData(player)

    -- Small delay to ensure save completes
    task.wait(0.5)

    -- Then teleport
    pcall(function()
        TeleportService:TeleportAsync(placeId, { player }, options)
    end)
end
```

### Auto-Save During Rounds

```luau
-- Periodic auto-save to prevent data loss from crashes
local AUTO_SAVE_INTERVAL = 120 -- every 2 minutes

task.spawn(function()
    while true do
        task.wait(AUTO_SAVE_INTERVAL)
        for _, player in Players:GetPlayers() do
            task.spawn(function()
                pcall(function()
                    DataManager.savePlayerData(player)
                end)
            end)
        end
    end
end)
```

### Validate Player Counts

```luau
-- Before starting a round, verify enough players are still connected
local function validatePlayerCount(minimum: number): boolean
    local count = #Players:GetPlayers()
    if count < minimum then
        warn(`Not enough players to start: {count}/{minimum}`)
        return false
    end
    return true
end
```

### Anti-AFK System

```luau
-- ServerScriptService/AntiAfk.luau

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

local AFK_TIMEOUT = 300 -- 5 minutes
local AFK_WARNING = 240 -- warn at 4 minutes

local AfkPingRemote = Instance.new("RemoteEvent")
AfkPingRemote.Name = "AfkPing"
AfkPingRemote.Parent = ReplicatedStorage

local AfkWarningRemote = Instance.new("RemoteEvent")
AfkWarningRemote.Name = "AfkWarning"
AfkWarningRemote.Parent = ReplicatedStorage

local lastActivity: { [Player]: number } = {}

-- Client pings on any input (mouse move, key press, touch)
AfkPingRemote.OnServerEvent:Connect(function(player: Player)
    lastActivity[player] = os.time()
end)

Players.PlayerAdded:Connect(function(player)
    lastActivity[player] = os.time()
end)

Players.PlayerRemoving:Connect(function(player)
    lastActivity[player] = nil
end)

-- Check loop
task.spawn(function()
    while true do
        task.wait(10)
        local now = os.time()
        for player, lastTime in lastActivity do
            if player.Parent ~= Players then continue end

            local idle = now - lastTime
            if idle >= AFK_TIMEOUT then
                player:Kick("You were kicked for being AFK.")
                lastActivity[player] = nil
            elseif idle >= AFK_WARNING then
                AfkWarningRemote:FireClient(player, AFK_TIMEOUT - idle)
            end
        end
    end
end)
```

**Client-side AFK ping:**

```luau
-- StarterPlayerScripts/AfkPing.client.luau

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

local afkPing = ReplicatedStorage:WaitForChild("AfkPing")

local PING_THROTTLE = 10 -- only ping every 10 seconds max
local lastPing = 0

UserInputService.InputBegan:Connect(function()
    local now = os.clock()
    if now - lastPing >= PING_THROTTLE then
        lastPing = now
        afkPing:FireServer()
    end
end)
```

### Handle Mid-Round Joins

```luau
-- When a player joins during an active round, decide what to do:
Players.PlayerAdded:Connect(function(player)
    if currentState == "Playing" then
        -- Option A: Add them as a spectator
        player.Team = lobbyTeam
        -- Show spectator UI

        -- Option B: Add them to the round (if team-based, pick smaller team)
        -- player.Team = getSmallestTeam({ redTeam, blueTeam })
        -- player:LoadCharacter()
        -- teleportToSpawn(player, getSpawnPoints(player.Team.Name))
        -- playerScores[player] = 0

    elseif currentState == "Intermission" then
        -- Normal join, they'll be included in the next round
        player.Team = lobbyTeam
        player:LoadCharacter()
    end
end)
```

### BindToClose for Server Shutdowns

```luau
-- Ensure data saves even when Roblox shuts down the server
game:BindToClose(function()
    for _, player in Players:GetPlayers() do
        task.spawn(function()
            pcall(function()
                DataManager.savePlayerData(player)
            end)
        end)
    end

    -- Give DataStore calls time to complete
    task.wait(3)
end)
```

---

## 11. Anti-Patterns

### Not Handling Teleport Failures

```luau
-- BAD: Fire and forget
TeleportService:TeleportAsync(placeId, { player })

-- GOOD: Wrap in pcall, retry on failure
local success, err = pcall(function()
    TeleportService:TeleportAsync(placeId, { player })
end)
if not success then
    warn(`Teleport failed: {err}`)
    -- Retry or notify player
end
```

### Losing Data During Server Hop

```luau
-- BAD: Teleport without saving
QueueRemote.OnServerEvent:Connect(function(player, action)
    if action == "join" then
        TeleportService:TeleportAsync(arenaPlaceId, { player })
    end
end)

-- GOOD: Save then teleport
QueueRemote.OnServerEvent:Connect(function(player, action)
    if action == "join" then
        DataManager.savePlayerData(player)
        task.wait(0.5)
        pcall(function()
            TeleportService:TeleportAsync(arenaPlaceId, { player })
        end)
    end
end)
```

### Unbalanced Teams

```luau
-- BAD: Random or first-come assignment
player.Team = if math.random() > 0.5 then redTeam else blueTeam

-- GOOD: Always assign to the smallest team
player.Team = getSmallestTeam({ redTeam, blueTeam })
```

### No Reconnection / Rejoin Support

If your game involves long sessions (RPGs, survival), consider allowing rejoins:

```luau
-- Store the reserved server access code in a DataStore keyed by UserId
-- When a player reconnects, check if they have an active session:

local function checkActiveSession(player: Player): string?
    local success, code = pcall(function()
        return sessionStore:GetAsync(`session_{player.UserId}`)
    end)
    if success and code then
        return code -- reserved server access code
    end
    return nil
end

Players.PlayerAdded:Connect(function(player)
    local activeCode = checkActiveSession(player)
    if activeCode then
        -- Offer to rejoin
        -- If accepted:
        local options = Instance.new("TeleportOptions")
        options.ReservedServerAccessCode = activeCode
        pcall(function()
            TeleportService:TeleportAsync(ARENA_PLACE_ID, { player }, options)
        end)
    end
end)
```

### Not Cleaning Up State on Player Leave

```luau
-- BAD: State tables grow forever
Players.PlayerRemoving:Connect(function(player)
    -- Nothing cleaned up
end)

-- GOOD: Remove player from all state tables
Players.PlayerRemoving:Connect(function(player)
    playerScores[player] = nil
    readyPlayers[player] = nil
    lastActivity[player] = nil

    local idx = table.find(roundParticipants, player)
    if idx then
        table.remove(roundParticipants, idx)
    end

    removeFromQueue(player)
end)
```

### Trusting Client for Match-Critical Logic

```luau
-- BAD: Client tells server the score
ScoreRemote.OnServerEvent:Connect(function(player, score)
    playerScores[player] = score -- Exploiter sends 999999
end)

-- GOOD: Server tracks all scoring
-- Only the server increments scores based on validated game events
-- (e.g., server detects a kill via Humanoid.Died and awards points)
```

---

## Quick Reference: Service Summary

| Service | Purpose | Key Methods/Events |
|---|---|---|
| **Players** | Player management | `PlayerAdded`, `PlayerRemoving`, `GetPlayers()`, `MaxPlayers` |
| **Teams** | Team assignment | `Team.AutoAssignable`, `Team:GetPlayers()`, `player.Team` |
| **TeleportService** | Cross-place movement | `TeleportAsync`, `ReserveServer`, `TeleportOptions` |
| **MessagingService** | Cross-server messaging | `PublishAsync`, `SubscribeAsync` |
| **DataStoreService** | Persistent data (ELO, sessions) | `GetAsync`, `SetAsync`, `UpdateAsync` |
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall