Sharp Edges: 12 Critical Roblox Development Gotchas

-- ServerScriptService/PlayerDataService.luau
-- Using ProfileService for session-locked player data

local Players = game:GetService("Players")
local ServerScriptService = game:GetService("ServerScriptService")
local ProfileService = require(ServerScriptService.Libs.ProfileService)

local PROFILE_TEMPLATE = {
    Coins = 0,
    Gems = 0,
    Inventory = {},
    Level = 1,
    Experience = 0,
}

local DATASTORE_NAME = "PlayerData_v1"

local ProfileStore = ProfileService.GetProfileStore(DATASTORE_NAME, PROFILE_TEMPLATE)
local Profiles: { [Player]: typeof(ProfileStore:LoadProfileAsync("")) } = {}

local PlayerDataService = {}

function PlayerDataService.getProfile(player: Player)
    return Profiles[player]
end

function PlayerDataService.start()
    local function onPlayerAdded(player: Player)
        -- Session locking happens automatically inside LoadProfileAsync.
        -- If another server holds the lock, this yields until it releases.
        local profile = ProfileStore:LoadProfileAsync(
            "Player_" .. player.UserId,
            "ForceLoad" -- Steal the lock if the other server is unresponsive
        )

        if profile == nil then
            -- Profile could not be loaded (DataStore outage, etc.)
            player:Kick("Unable to load your data. Please rejoin.")
            return
        end

        -- Guard: player may have left while we were loading
        if not player:IsDescendantOf(Players) then
            profile:Release()
            return
        end

        -- If the session is stolen by another server, kick this player
        profile:ListenToRelease(function()
            Profiles[player] = nil
            player:Kick("Your data was loaded on another server. Please rejoin.")
        end)

        Profiles[player] = profile
    end

    local function onPlayerRemoving(player: Player)
        local profile = Profiles[player]
        if profile then
            profile:Release() -- Releases session lock AND saves
            Profiles[player] = nil
        end
    end

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

    -- Handle players already in game (Studio edge case)
    for _, player in Players:GetPlayers() do
        task.spawn(onPlayerAdded, player)
    end
end

return PlayerDataService

-- ServerScriptService/CurrencyService.luau
-- All currency logic is server-authoritative. The client NEVER sends a balance.

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

local PlayerDataService = require(script.Parent.PlayerDataService)

-- Remote used ONLY to push display updates to the client
local CurrencyChanged = ReplicatedStorage.Remotes.CurrencyChanged :: RemoteEvent

local CurrencyService = {}

-- Server-only: Add currency. Called by server systems (quests, shops, etc.)
function CurrencyService.addCoins(player: Player, amount: number): boolean
    assert(typeof(amount) == "number", "Amount must be a number")
    assert(amount > 0, "Amount must be positive")
    assert(amount == math.floor(amount), "Amount must be an integer")
    assert(amount <= 1_000_000, "Amount exceeds single-transaction limit")

    local profile = PlayerDataService.getProfile(player)
    if not profile then return false end

    profile.Data.Coins += amount

    -- Push display update to client (client cannot modify this)
    CurrencyChanged:FireClient(player, "Coins", profile.Data.Coins)
    return true
end

-- Server-only: Spend currency. Returns true if successful.
function CurrencyService.spendCoins(player: Player, amount: number): boolean
    assert(typeof(amount) == "number", "Amount must be a number")
    assert(amount > 0, "Amount must be positive")
    assert(amount == math.floor(amount), "Amount must be an integer")

    local profile = PlayerDataService.getProfile(player)
    if not profile then return false end

    if profile.Data.Coins < amount then
        return false -- Insufficient funds
    end

    profile.Data.Coins -= amount
    CurrencyChanged:FireClient(player, "Coins", profile.Data.Coins)
    return true
end

function CurrencyService.getCoins(player: Player): number
    local profile = PlayerDataService.getProfile(player)
    return if profile then profile.Data.Coins else 0
end

return CurrencyService

-- StarterPlayerScripts/CurrencyDisplay.client.luau
-- Client ONLY listens for display updates. It never sends currency data.

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

local CurrencyChanged = ReplicatedStorage.Remotes.CurrencyChanged :: RemoteEvent

local localPlayer = Players.LocalPlayer
local playerGui = localPlayer:WaitForChild("PlayerGui")

CurrencyChanged.OnClientEvent:Connect(function(currencyName: string, newValue: number)
    -- Update UI display only
    local label = playerGui:FindFirstChild(currencyName .. "Label", true)
    if label and label:IsA("TextLabel") then
        label.Text = tostring(newValue)
    end
end)

-- ServerScriptService/GamepassAndProductHandler.luau

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

local PlayerDataService = require(script.Parent.PlayerDataService)
local CurrencyService   = require(script.Parent.CurrencyService)

local PRODUCTS = {
    [123456789] = {
        name  = "100 Coins",
        grant = function(player: Player): boolean
            return CurrencyService.addCoins(player, 100)
        end,
    },
    [987654321] = {
        name  = "500 Coins",
        grant = function(player: Player): boolean
            return CurrencyService.addCoins(player, 500)
        end,
    },
}

local function processReceipt(receiptInfo: {
    PlayerId: number,
    ProductId: number,
    PurchaseId: string,
    CurrencySpent: number,
    PlaceIdWherePurchased: number,
}): Enum.ProductPurchaseDecision

    -- 1. Find the player in this server
    local player = Players:GetPlayerByUserId(receiptInfo.PlayerId)
    if not player then
        -- Player left; Roblox will retry when they rejoin
        return Enum.ProductPurchaseDecision.NotProcessedYet
    end

    -- 2. Wait for their profile to load
    local profile = PlayerDataService.getProfile(player)
    if not profile then
        return Enum.ProductPurchaseDecision.NotProcessedYet
    end

    -- 3. Idempotency check — was this PurchaseId already granted?
    if table.find(profile.Data.ProcessedReceipts, receiptInfo.PurchaseId) then
        -- Already granted; stop retrying
        return Enum.ProductPurchaseDecision.PurchaseGranted
    end

    -- 4. Look up and execute the grant
    local productConfig = PRODUCTS[receiptInfo.ProductId]
    if not productConfig then
        warn("[ProcessReceipt] Unknown ProductId:", receiptInfo.ProductId)
        return Enum.ProductPurchaseDecision.NotProcessedYet
    end

    local grantSuccess = productConfig.grant(player)
    if not grantSuccess then
        return Enum.ProductPurchaseDecision.NotProcessedYet
    end

    -- 5. Record the PurchaseId so we never double-grant
    table.insert(profile.Data.ProcessedReceipts, receiptInfo.PurchaseId)

    -- Keep the receipts list bounded (last 100)
    if #profile.Data.ProcessedReceipts > 100 then
        table.remove(profile.Data.ProcessedReceipts, 1)
    end

    -- 6. ONLY NOW tell Roblox the purchase is complete
    return Enum.ProductPurchaseDecision.PurchaseGranted
end

MarketplaceService.ProcessReceipt = processReceipt

-- Shared/Trove.luau (simplified cleanup utility)

local Trove = {}
Trove.__index = Trove

function Trove.new()
    return setmetatable({ _objects = {} }, Trove)
end

function Trove:Add(object: any): any
    table.insert(self._objects, object)
    return object
end

function Trove:Connect(signal: RBXScriptSignal, callback: (...any) -> ()): RBXScriptConnection
    local connection = signal:Connect(callback)
    table.insert(self._objects, connection)
    return connection
end

function Trove:Clean()
    for _, object in self._objects do
        if typeof(object) == "RBXScriptConnection" then
            object:Disconnect()
        elseif typeof(object) == "Instance" then
            object:Destroy()
        elseif typeof(object) == "function" then
            object()
        end
    end
    table.clear(self._objects)
end

return Trove

-- ServerScriptService/PlayerSetup.luau

local Players = game:GetService("Players")
local Trove = require(game.ReplicatedStorage.Shared.Trove)

local playerTroves: { [Player]: typeof(Trove.new()) } = {}

local function onPlayerAdded(player: Player)
    local trove = Trove.new()
    playerTroves[player] = trove

    trove:Connect(player.CharacterAdded, function(character)
        local humanoid = character:WaitForChild("Humanoid")

        -- This connection is also tracked — cleaned when the trove cleans
        trove:Connect(humanoid.Died, function()
            print(player.Name, "died — respawning in 3 seconds")
            task.wait(3)
            player:LoadCharacter()
        end)
    end)

    -- Track created instances too
    local billboard = trove:Add(Instance.new("BillboardGui"))
    billboard.Name = "PlayerLabel"
    billboard.Parent = player.Character and player.Character:FindFirstChild("Head")
end

local function onPlayerRemoving(player: Player)
    local trove = playerTroves[player]
    if trove then
        trove:Clean() -- Disconnects ALL connections, destroys ALL instances
        playerTroves[player] = nil
    end
end

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

-- ServerScriptService/RateLimiter.luau

local RateLimiter = {}
RateLimiter.__index = RateLimiter

export type Config = {
    maxRequests: number,   -- Max requests allowed in the window
    windowSeconds: number, -- Time window in seconds
    kickAfter: number?,    -- Kick player after this many violations (nil = never)
}

function RateLimiter.new(config: Config)
    return setmetatable({
        _config = config,
        _playerData = {} :: { [Player]: { count: number, windowStart: number, violations: number } },
    }, RateLimiter)
end

function RateLimiter:check(player: Player): boolean
    local now  = os.clock()
    local data = self._playerData[player]

    if not data then
        data = { count = 0, windowStart = now, violations = 0 }
        self._playerData[player] = data
    end

    -- Reset window if expired
    if now - data.windowStart >= self._config.windowSeconds then
        data.count = 0
        data.windowStart = now
    end

    data.count += 1

    if data.count > self._config.maxRequests then
        data.violations += 1

        if self._config.kickAfter and data.violations >= self._config.kickAfter then
            player:Kick("Rate limit exceeded.")
        end

        return false -- Request denied
    end

    return true -- Request allowed
end

function RateLimiter:removePlayer(player: Player)
    self._playerData[player] = nil
end

return RateLimiter

-- ServerScriptService/CombatRemotes.luau

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players           = game:GetService("Players")
local RateLimiter       = require(script.Parent.RateLimiter)

local AttackRemote = ReplicatedStorage.Remotes.Attack :: RemoteEvent

-- Allow 10 attack requests per second; kick after 5 violations
local attackLimiter = RateLimiter.new({
    maxRequests   = 10,
    windowSeconds = 1,
    kickAfter     = 5,
})

AttackRemote.OnServerEvent:Connect(function(player: Player, targetId: number)
    if not attackLimiter:check(player) then
        return -- Silently drop the request
    end

    -- Validate and process the attack (server-authoritative)
    -- ...
end)

Players.PlayerRemoving:Connect(function(player)
    attackLimiter:removePlayer(player)
end)

-- ServerScriptService/ShutdownHandler.luau

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

local PlayerDataService = require(script.Parent.PlayerDataService)

local IS_STUDIO = RunService:IsStudio()

game:BindToClose(function()
    if IS_STUDIO then
        task.wait(1)
        return
    end

    local savingPlayers = Players:GetPlayers()
    if #savingPlayers == 0 then return end

    -- Save ALL players in parallel
    local completed = 0
    local total     = #savingPlayers

    for _, player in savingPlayers do
        task.spawn(function()
            -- ProfileService:Release() handles save + session unlock
            local profile = PlayerDataService.getProfile(player)
            if profile then
                profile:Release()
            end
            completed += 1
        end)
    end

    -- Wait until all saves complete OR we approach the 30s deadline
    local deadline = os.clock() + 27 -- Leave 3s buffer
    while completed < total and os.clock() < deadline do
        task.wait(0.1)
    end

    if completed < total then
        warn(string.format(
            "[Shutdown] Saved %d/%d players before timeout!",
            completed, total
        ))
    else
        print(string.format("[Shutdown] All %d players saved successfully.", total))
    end
end)

CRITICAL — fix before shipping:
  SE-1  DataStore session locking     → Use ProfileService
  SE-2  Client-side currency          → Server-authoritative only
  SE-3  ProcessReceipt order          → Grant THEN return PurchaseGranted

HIGH — fix in current sprint:
  SE-4  Undisconnected events         → Trove/Maid pattern
  SE-5  RemoteEvent flooding          → Per-player rate limiter
  SE-6  BindToClose 30s timeout       → Parallel saves with task.spawn

MEDIUM — fix before scale:
  SE-7  Mobile part count             → StreamingEnabled + <10K parts
  SE-8  Yielding in module require    → Init/Start lifecycle pattern
  SE-9  Table # with nil gaps         → table.remove; never set nil in arrays
  SE-11 Infinite yield WaitForChild   → Always pass timeout parameter

LOW — fix when convenient:
  SE-10 Deprecated wait/spawn/delay   → task.wait / task.spawn / task.delay
  SE-12 String patterns vs regex      → %d not \d; % not \ as escape