AccelByte Gaming Services SDK for Roblox

The AGS Roblox SDK is a library for integrating AccelByte Gaming Services into your Roblox game. The SDK provides access to a wide range of AGS APIs, including IAM, Leaderboard, Matchmaking, CloudSave, Social, Achievement, and more. This guide will walk you through getting started with the AGS Roblox SDK, including installation, configuration, and usage instructions.

Prerequisites

Before you begin, make sure you have:

• A game namespace on the AGS Admin Portal
• IAM Client for game client and game server

Installing SDK

1. Download AccelByteSDK.rbxm from the releases page of this repository.

2. Drag and drop AccelByteSDK.rbxm into ServerStorage in the Explorer panel. The contents in ServerStorage are only accessible to server-side code. This keeps your credentials and tokens away from clients.

3. The SDK communicates with AccelByte APIs over HTTPS, thus you need to enable HTTP request on your Roblox project. Go to File → Experience Settings, select the Security tab, and toggle on Allow HTTP Requests.

Configuring SDK

In the Explorer panel, expand ServerStorage → AccelByteSDK → Config. You will find four ModuleScript files:

File	When it's used
DefaultConfig	Default game client configuration. It is used for published game
DevelopmentConfig	Optional development game client configuration. It is only used in the Roblox Studio only
DefaultServerConfig	Default game server configuration. It is used for published game
DevelopmentServerConfig	Optional development game server configuration. It is only used in the Roblox Studio only

Open these files and fill in your values:

return {
    baseUrl = "https://your-namespace.accelbyte.io",
    namespace = "your-namespace",
    clientId = "your-iam-client-id",
    clientSecret = "your-iam-client-secret",
    publisherNamespace = "your-publisher-namespace", -- Only for AGS Private Cloud users
}

Field	Required	Description
baseUrl	Yes	AccelByte platform URL. Must start with https:// and no trailing slash.
namespace	Yes	Your AccelByte game namespace.
clientId	Yes	IAM Client ID from the Admin Portal.
clientSecret	Yes for server	IAM Client secret from the Admin Portal.
publisherNamespace	No	Publisher namespace, only for AGS Private Cloud users.

Initializing SDK

Create a Script under ServerScriptService and add:

-- In a Script under ServerScriptService
local AccelByte = require(game.ServerStorage.AccelByteSDK)
AccelByte.init()

AccelByte.init() must be called once before any login or API calls. It loads your config, sets up the HTTP clients, rate limiter, and token repository. Then, you can perform login for your game client and game server before accessing the APIs.

Game Server Login

For admin/server API endpoints, the server must authenticate using client credentials. Call this at game startup, after AccelByte.init():

-- In a Script under ServerScriptService
task.spawn(function()
    local ok, err = AccelByte.Auth:loginServer()
    if ok then
        print("[AccelByte] Server logged in")
    else
        warn("[AccelByte] Server login failed: " .. tostring(err))
    end
end)

Game Client Login

Game clients (players) cannot access ServerStorage, so client scripts cannot call the SDK directly. The standard Roblox pattern is to use RemoteEvents, the client fires a request, the server receives it and calls the SDK, then fires the result back to the client. Here is an example how you can do it.

1. Set up RemoteEvents in a Script or shared module.

   -- In a Script under ServerScriptService or wherever you want to manage RemoteEvents
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local loginEvent = Instance.new("RemoteEvent")
   loginEvent.Name = "LoginRequest"
   loginEvent.Parent = ReplicatedStorage
   
   local loginResultEvent = Instance.new("RemoteEvent")
   loginResultEvent.Name = "LoginResult"
   loginResultEvent.Parent = ReplicatedStorage

2. Then, create a login handle on the server script.

   -- In a Script under ServerScriptService
   loginEvent.OnServerEvent:Connect(function(player)
       task.spawn(function()
           local ok = AccelByte.Auth:loginPlayer(player, 3)  -- 3 retries with exponential backoff
           loginResultEvent:FireClient(player, { ok = ok })
       end)
   end)

3. Then, you can trigger login from the client

   -- In a LocalScript under StarterPlayerScripts
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local loginEvent = ReplicatedStorage:WaitForChild("LoginRequest")
   local loginResultEvent = ReplicatedStorage:WaitForChild("LoginResult")
   
   loginResultEvent.OnClientEvent:Connect(function(result)
       if result.ok then
           print("Logged in to AccelByte!")
       else
           warn("Login failed")
       end
   end)
   
   loginEvent:FireServer()

Interacting with the SDK

Game Client APIs

Use AccelByte:<Service>Api(player) for endpoints that operate on the player's own data. The player must be logged in first. Here is an example:

-- In a Script under ServerScriptService
someRemoteEvent.OnServerEvent:Connect(function(player)
    task.spawn(function()
        -- Get the desired service
        local lbApi = AccelByte:LeaderboardApi(player)

        -- Call the desired API
        local ok, result = lbApi.LeaderboardDataV3:getAllTimeLeaderboardRankingPublicV3({
            leaderboardCode = "my-leaderboard",
            limit = 50,
        })

        -- Check for response
        if ok then
            for _, entry in result.data do
                print(entry.rank, entry.userId, entry.point)
            end
        else
            warn("API call failed: " .. tostring(result))
        end
    end)
end)

Game Server APIs

Use AccelByte:<Service>ServerApi() for admin endpoints. The server must be logged in first. Here is an example:

-- In a Script under ServerScriptService
task.spawn(function()
    -- Get the desired service
    local socialApi = AccelByte:SocialServerApi()

    -- Call the desired API
    local ok, result = socialApi.UserStatistic:updateUserStatItemValue({
        statCode = "my-stat-code",
        userId = abUserId,
        body = {
            updateStrategy = "MAX",
            value = 1500,
        },
    })

    -- Check for response
    if ok then
        print("Stat updated")
    else
        warn("Stat update failed: " .. tostring(result))
    end
end)