GamebeastDocs
Dashboard
Dashboard
Roblox SDK

Roblox SDK

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

Refer to the Installation 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 recommended to implement the :SendNewPurchaseGrantedMarker method to track purchases accurately.

SDK Usage Considerations

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:

sessionLengthnumber

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

sessionLengthPercentageWithFriendsnumber

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:

userIdnumber

The ID of the user that the player joined.

isFriendboolean

Whether the user that the player joined is a friend.

PlaceTeleport

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

Arguments:

sourcePlaceIdnumber

The ID of the place the player is teleporting from.

destinationPlaceIdnumber

The ID of the place the player is teleporting to.

sessionLengthnumber

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:

typestring

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

fromReceiptboolean

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

idnumber

The Roblox provided identifier for the purchased item.

pricenumber

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.

basePricenumber

The default price of the purchased item.

namestring

The name of the purchased item.

descriptionstring

The description of the purchased item.

imageIdstring

The image URL of the purchased item.

Chat

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

Arguments:

messagestring

The chat message sent by the player.

SDK Methods

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

:Setup(setupConfig)

voidreturn type

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.

setupConfigServerSetupConfig?

The required config table for the SDK.

Types

type SDKSettings = {
	-- Enables SDK warnings for API misuse, internal errors, etc. Default true.
	sdkWarningsEnabled : boolean?,
	-- Enables stack trace inclusion with warning messages. Default false.
	includeWarningStackTrace : boolean?,
	-- Enables SDK debug messages about internal state changes. Default false.
	sdkDebugEnabled : boolean?,
	-- The environment to use: "production" or "studio".
	-- Defaults to "studio" in Studio and "production" in live servers.
	environment : ("production" | "studio")?,
	-- Seconds between sending batches of markers. Default 10, minimum 1.
	markerFlushRate : number?,
	-- Seconds between checks for configuration and experiment changes. Default 30, minimum 5.
	statusPollRate : number?,
	-- Seconds between refreshing the experiment groups of the players in the server.
	-- Default 30, minimum 10.
	assignmentRefreshRate : number?,
	-- Seconds between server reports (players, server and client performance).
	-- Default 30, minimum 10, maximum 45.
	serverReportRate : number?,
}
type ServerSetupConfig = {
	key : string | Secret,
	sdkSettings : SDKSettings?
}

Usage

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

-- Client
Gamebeast:Setup()

Settings you leave out use their defaults. If a value is invalid, :Setup errors and says what it expected, for example Expected at least 5 seconds, got 2.

Rates

The rate settings control how often the SDK talks to Gamebeast. Lower values pick up dashboard changes sooner and send more requests.

SettingDefaultRangeWhat it controls
markerFlushRate101 or moreHow often queued markers are sent. A full queue is sent immediately.
statusPollRate305 or moreHow often the server checks for configuration and experiment changes. During an incident Gamebeast can ask servers to check less often, never more often.
assignmentRefreshRate3010 or moreHow often the server refreshes the experiment groups of its players. This is how a group change made on the dashboard reaches players already in game.
serverReportRate3010 to 45How often the server reports its players and performance. The maximum keeps a report in every minute, which player counts on the dashboard rely on.

In Studio, rates you leave out default lower so you see dashboard changes quickly while testing: markerFlushRate 2, statusPollRate 5, assignmentRefreshRate 10 and serverReportRate 10. Rates you set yourself are used as given.

:UpdateSettings(sdkSettings)

voidreturn type

Changes settings on a running SDK. Settings left out of the table keep their current value, and nothing changes unless every setting you pass is valid. Changes take effect within a few seconds.

environment can only be set in :Setup, since it decides where the SDK's data comes from and goes to.

sdkSettingsSDKSettings

The settings to change.

Usage

Gamebeast:UpdateSettings({ statusPollRate = 120, sdkDebugEnabled = true })

:GetService(serviceName)

GamebeastServicereturn type

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

serviceNamestring

The name of the SDK service.

Usage

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

SDKs

Integrate Gamebeast into your game or app with the SDK for your platform.

Installation

Getting started with Gamebeast in Roblox is easy. This guide will walk you through the process of installing the Gamebeast SDK and configuring your API key.

On this page

Calling into Gamebeast from RobloxIMPORTANT: Tracking Dev Product purchasesSDK Usage ConsiderationsIt is unsafe to change the SDK's source.Default BehaviorsDefault MarkersSDK Methods:Setup(setupConfig)TypesUsageRates:UpdateSettings(sdkSettings)Usage:GetService(serviceName)Usage