Roblox Crux Quickstart: Lua SDK, Data & Leaderboards

-- ServerScriptService/GameServer (Script)

local Crux = require(game.ServerScriptService.Crux)

local gsb = Crux.init(
    "YOUR_PROJECT_ID",    -- e.g. "proj_01abc..."
    "YOUR_SERVER_TOKEN",  -- e.g. "gsb_st_..."
    "YOUR_ENVIRONMENT_ID" -- e.g. "env_01abc..."  (use your "production" env)
)

local Players = game:GetService("Players")

-- Maps Roblox UserId → Crux player_id for this session
local playerIds = {}

Players.PlayerAdded:Connect(function(player)
    local ok, result = pcall(function()
        return gsb:VerifyPlayer(player.UserId)
    end)

    if ok then
        playerIds[player.UserId] = result.player_id
        print("[Crux] Verified " .. player.Name .. " → " .. result.player_id)
    else
        warn("[Crux] Verify failed for " .. player.Name .. ": " .. tostring(result))
    end
end)

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

-- Get a player's save data
local profileStore = gsb:GetDataStore("profile")

local function loadProfile(robloxUserId)
    local playerId = playerIds[robloxUserId]
    if not playerId then return end

    local data, version = profileStore:GetAsync(playerId)
    -- data is a Lua table (or nil if no save exists yet)
    return data, version
end

local function saveProfile(robloxUserId, data)
    local playerId = playerIds[robloxUserId]
    if not playerId then return end

    profileStore:SetAsync(playerId, data)
end

local function addXP(robloxUserId, amount)
    local playerId = playerIds[robloxUserId]
    if not playerId then return end

    profileStore:UpdateAsync(playerId, function(current)
        current = current or { xp = 0, level = 1 }
        current.xp = current.xp + amount
        -- level up every 1000 XP
        current.level = math.floor(current.xp / 1000) + 1
        return current
    end)
end

-- Submit a score when a round ends
local function onRoundEnd(robloxUserId, finalScore)
    local playerId = playerIds[robloxUserId]
    if not playerId then return end

    gsb:SubmitScore("weekly-kills", playerId, finalScore, {
        -- optional metadata attached to this entry
        weapon = "shotgun",
        mode   = "tdm",
    })
end

-- Show the top 10 at game start (e.g. to populate a lobby board)
local function showLeaderboard()
    local entries = gsb:GetLeaderboardTop("weekly-kills", 10)
    for _, entry in ipairs(entries) do
        print(string.format("#%d  %s  %d", entry.rank, entry.player_id, entry.score))
    end
end

-- Show where a specific player ranks
local function showPlayerRank(robloxUserId)
    local playerId = playerIds[robloxUserId]
    local standing = gsb:GetPlayerStanding("weekly-kills", playerId)
    if standing then
        print("You are rank " .. standing.rank .. " with " .. standing.score .. " kills")
    end
end

local function getEconomy(robloxUserId)
    local playerId = playerIds[robloxUserId]
    if not playerId then return end

    local economy = gsb:GetPlayerEconomy(playerId)

    -- currency_id/item_id are legacy SDK names for the stable catalog key.
    for _, bal in ipairs(economy.balances or {}) do
        print(bal.currency_name .. " (" .. bal.currency_id .. "): " .. bal.amount)
    end

    for _, item in ipairs(economy.inventory or {}) do
        print(item.item_name .. " (" .. item.item_id .. ") ×" .. item.quantity)
    end
end

-- Use the stable catalog keys you configured in the dashboard.
local GOLD_KEY  = "gold"
local CRATE_KEY = "crate"

local function onKillReward(robloxUserId)
    local playerId = playerIds[robloxUserId]
    if not playerId then return end

    local updated = gsb:AdjustEconomy(
        playerId,
        {{ currency_key = GOLD_KEY, amount = 50 }},
        {{ item_key = CRATE_KEY, quantity = 1 }}
    )
    return updated -- the resulting economy state
end

-- ServerScriptService/GameServer

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

local gsb = Crux.init("YOUR_PROJECT_ID", "YOUR_SERVER_TOKEN", "YOUR_ENVIRONMENT_ID")

local GOLD_KEY = "gold"
local playerIds = {}

Players.PlayerAdded:Connect(function(player)
    local ok, result = pcall(gsb.VerifyPlayer, gsb, player.UserId)
    if not ok then return end
    local pid = result.player_id
    playerIds[player.UserId] = pid

    -- Load profile
    local ds = gsb:GetDataStore("profile")
    local profile = ds:GetAsync(pid) or { xp = 0, level = 1, kills = 0 }

    -- Store in player attribute for easy access
    player:SetAttribute("gsb_pid",   pid)
    player:SetAttribute("xp",        profile.xp)
    player:SetAttribute("level",     profile.level)
    player:SetAttribute("kills",     profile.kills)
end)

Players.PlayerRemoving:Connect(function(player)
    local pid = player:GetAttribute("gsb_pid")
    if not pid then return end

    -- Save profile on leave
    local ds = gsb:GetDataStore("profile")
    ds:SetAsync(pid, {
        xp     = player:GetAttribute("xp"),
        level  = player:GetAttribute("level"),
        kills  = player:GetAttribute("kills"),
    })
    playerIds[player.UserId] = nil
end)

-- Called by your combat system
local function onPlayerKill(killerUserId)
    local pid = playerIds[killerUserId]
    if not pid then return end

    -- Award gold and increment kill counter
    gsb:AdjustEconomy(pid, {{ currency_key = GOLD_KEY, amount = 25 }}, {})
    local killer = Players:GetPlayerByUserId(killerUserId)
    if killer then
        local kills = (killer:GetAttribute("kills") or 0) + 1
        killer:SetAttribute("kills", kills)
        gsb:SubmitScore("all-time-kills", pid, kills)
    end
end

-- Experience A (e.g. your main game)
local gsbA = Crux.init("proj_shared", "st_main_game", "env_prod")
local verifiedA = gsbA:VerifyPlayer(player.UserId)

-- Experience B (e.g. a separate hub experience)
local gsbB = Crux.init("proj_shared", "st_hub", "env_prod")
local verifiedB = gsbB:VerifyPlayer(player.UserId)
local pid = verifiedB.player_id
local profile = gsbB:GetDataStore("profile"):GetAsync(pid)