Roblox SDKOverview

Roblox SDK

Use this section to review required setup functions and examples for the Roblox SDK.

Refer to the Intallation section for installation information.

Calling into Gamebeast from Roblox

server.lua
-- Server Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Gamebeast = require(ReplicatedStorage:WaitForChild("Gamebeast"))
 
Gamebeast:Setup({
    key = "abcd-efgh-1234-5678",
})
client.lua
-- Client Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Gamebeast = require(ReplicatedStorage:WaitForChild("Gamebeast"))
 
Gamebeast:Setup()

IMPORTANT: Tracking Dev Product purchases

If you are using Dev Products in your game, it is highly recommeded to implement the :SendNewPurchaseGrantedMarker method to track purchases accurately.

SDK Usage Considerations

Do not clear the shared global table.

Gamebeast’s Roblox SDK uses shared.GBMod to fetch modules within its internal framework. Clearing this table will result in the SDK erroring during startup. It’s okay to add additional entries to shared as long as GBMod is not overwritten.

It is unsafe to change the SDK’s source.

The SDK is designed to be a black box, modifying its source code can lead to unexpected behavior. Changes will not be preserved when the plugin updates the SDK. If you’re interested in additional functionality, please reach out.

Default Behaviors

Default Markers

The SDK will automatically send certain default markers to help track player activity in your experience. These include things like player joins, leaves, and place teleports.

For a full list of default markers sent by the Gamebeast Roblox SDK, view the dropdown below:

View Default Markers
Login

Triggered when a player logs in to your experience.

This does not include when joining from a teleport within the same experience, such as teleporting to the main place from the lobby place.

Arguments:

policyInfo

{[string] : any}

the policy information of the player retrieved from PolicyService:GetPolicyInfoForPlayerAsync()

Logout

Triggered when a player leaves your experience. This does not include leaving by teleports to places within the same experience.

Arguments:

sessionLength

number

The length of the player’s session in seconds across all places in the experience.

sessionLengthPercentageWithFriends

number

A 0-1 representation of the percentage of the player’s session spent with friends.

JoinedUser

Triggered when a player joins another player in your experience.

Arguments:

userId

number

The ID of the user that the player joined.

isFriend

boolean

Whether the user that the player joined is a friend.

PlaceTeleport

Triggered when a player teleports to a different place within your experience.

Arguments:

sourcePlaceId

number

The ID of the place the player is teleporting from.

destinationPlaceId

number

The ID of the place the player is teleporting to.

sessionLength

number

The length of the player’s session in seconds within that place.

Purchase

Triggered when a player makes a purchase in your experience, such as buying a developer product, game pass, asset, or subscription.

Arguments:

type

string

The type of purchase made by the player. This can be set to gamepass, asset, devproduct or subscription.

fromReceipt

boolean

Whether or not this purchase marker was made from the receipt of a purchase via MarkersService:SendNewPurchaseGrantedMarker()

id

number

The Roblox provided identifier for the purchased item.

price

number

The price of the purchased item. This is the price the player paid, which may differ from the base price if discounts are applied from Roblox’s geographic pricing.

basePrice

number

The default price of the purchased item.

name

string

The name of the purchased item.

description

string

The description of the purchased item.

imageId

string

The image URL of the purchased item.

Chat

Triggered when a player sends a chat message in your experience.

Arguments:

message

string

The chat message sent by the player.

SDK Methods

local Gamebeast = require(game:GetService("ReplicatedStorage"):WaitForChild("Gamebeast"))

:Setup(setupConfig)

→ void

This function must be called once on the server and client to initialize the Gamebeast SDK. Attempting to call any other SDK method before calling :Setup will result in an error.

setupConfig

ServerSetupConfig?

The required config table for the SDK.

Types

type SDKSettings = {
	-- Enables SDK warnings for API misuse, internal errors, etc.
	sdkWarningsEnabled : boolean,
	-- Enables stack trace inclusion with warning messages.
	includeWarningStackTrace : boolean,
}
type ServerSetupConfig = {
	key : string | Secret,
	sdkSettings : SDKSettings?
}

Usage

-- Server
Gamebeast:Setup({
    key = "abcd-efgh-1234-5678",
    sdkSettings = {
        sdkWarningsEnabled = true,
        includeWarningStackTrace = false,
    }
})
 
-- Client
Gamebeast:Setup()

if sdkSettings is not provided, the following are the defaults that will be used.

{
    sdkWarningsEnabled = true,
    includeWarningStackTrace = false,
}

:GetService(serviceName)

→ GamebeastService

This method will attempt to fetch a service module from the Gamebeast SDK. All available services can be found documented here.

serviceName

string

The name of the SDK service.

Usage

GamebeastMarkers = Gamebeast:GetService("Markers") :: Gamebeast.MarkersService
InstallationAPI