Gamebeast SDK

https://docs.gamebeast.gg/
Admin
The Gamebeast SDK is designed to be a familiar and easy-to-integrate tool for developers, allowing...
Tokens:16,545
Snippets:223
Trust Score:6.4
Update:4 months ago
Show doc for...
Tokens:
Raw
### Client-Side Gamebeast SDK Setup

Source: https://docs.gamebeast.gg/Roblox/Overview

Sets up the Gamebeast SDK on the client. This setup does not require an API key.

```lua
-- Client Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Gamebeast = require(ReplicatedStorage:WaitForChild("Gamebeast"))
 
Gamebeast:Setup()
```

--------------------------------

### SDK Setup Configuration Types

Source: https://docs.gamebeast.gg/Roblox/Overview

Defines the types for SDK settings and server setup configuration.

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

--------------------------------

### Initialize Gamebeast Markers Service

Source: https://docs.gamebeast.gg/Roblox/API/Markers

Requires the Gamebeast module and gets the Markers service. This setup is necessary before using any marker-sending functions.

```lua
local Gamebeast = require(game:GetService("ReplicatedStorage"):WaitForChild("Gamebeast"))
local GamebeastMarkers = Gamebeast:GetService("Markers")
```

--------------------------------

### Initialize Gamebeast SDK

Source: https://docs.gamebeast.gg/Roblox/Overview

Demonstrates how to initialize the Gamebeast SDK on both the server and client. The server requires a key, while the client can use a default setup.

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

--------------------------------

### Server-Side Gamebeast SDK Setup

Source: https://docs.gamebeast.gg/Roblox/Overview

Sets up the Gamebeast SDK on the server with an API key. Ensure the Gamebeast module is available in ReplicatedStorage.

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

--------------------------------

### Default SDK Settings

Source: https://docs.gamebeast.gg/Roblox/Overview

Shows the default configuration for SDK settings if not explicitly provided during setup.

```lua
{
    sdkWarningsEnabled = true,
    includeWarningStackTrace = false,
}
```

--------------------------------

### Initialize Gamebeast and Experiments Service

Source: https://docs.gamebeast.gg/Roblox/API/Experiments

Requires the Gamebeast module and retrieves the Experiments service. This is the initial setup for using the Experiments API.

```lua
local Gamebeast = require(game:GetService("ReplicatedStorage"):WaitForChild("Gamebeast"))
local GamebeastExperiments = Gamebeast:GetService("Experiments") :: Gamebeast.ExperimentsService
```

--------------------------------

### :Setup

Source: https://docs.gamebeast.gg/Roblox/Overview

Initializes the Gamebeast SDK. This function must be called once on both the server and client before any other SDK methods can be used. It accepts a configuration table for server-side setup.

```APIDOC
## :Setup(setupConfig)

### Description
Initializes the Gamebeast SDK. This function must be called once on both the server and client before any other SDK methods can be used. It accepts an optional configuration table for server-side setup.

### Method
`Setup`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **setupConfig** (ServerSetupConfig?) - The required config table for the SDK. If not provided on the client, default settings are used.
  - **key** (string | Secret) - Required for server setup. The API key for authentication.
  - **sdkSettings** (SDKSettings?) - Optional. Settings for the SDK.
    - **sdkWarningsEnabled** (boolean) - Enables SDK warnings. Defaults to `true`.
    - **includeWarningStackTrace** (boolean) - Enables stack trace inclusion with warnings. Defaults to `false`.

### Request Example
```lua
-- Server
Gamebeast:Setup({
    key = "abcd-efgh-1234-5678",
    sdkSettings = {
        sdkWarningsEnabled = true,
        includeWarningStackTrace = false,
    }
})

-- Client
Gamebeast:Setup()
```

### Response
#### Success Response (void)
This method does not return a value.

#### Response Example
N/A
```

--------------------------------

### Initialize Gamebeast SDK in Client Script

Source: https://docs.gamebeast.gg/Roblox/Installation

Use this code in a client script to initialize the Gamebeast SDK. This version does not require an explicit API key in the setup call, assuming it's handled server-side or through other configurations.

```lua
-- Client Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Gamebeast = require(ReplicatedStorage:WaitForChild("Gamebeast"))

Gamebeast:Setup()
```

--------------------------------

### Initialize Gamebeast and Cohorts Service

Source: https://docs.gamebeast.gg/Roblox/API/Cohorts

Requires the Gamebeast module and retrieves the Cohorts service. This setup is necessary before calling any Cohorts API methods.

```lua
local Gamebeast = require(game:GetService("ReplicatedStorage"):WaitForChild("Gamebeast"))
local GamebeastCohorts = Gamebeast:GetService("Cohorts") :: Gamebeast.CohortsService
```

--------------------------------

### Initialize Gamebeast SDK

Source: https://docs.gamebeast.gg/Unity/Overview

This script initializes the Gamebeast SDK with an API key when the Unity application starts. Ensure this is called once before any other SDK methods.

```csharp
using UnityEngine;
using Gamebeast.Runtime;
 
public class GamebeastStarter : MonoBehaviour
{
    void Start()
    {
        GamebeastSdk.Init("abcd-efgh-1234-5678");
    }
}
```

--------------------------------

### Initialize Markers API

Source: https://docs.gamebeast.gg/Unity/API/Markers

Get a reference to the Markers API object. This is typically done once at the start of your application.

```csharp
var gamebeastMarkers = GamebeastSdk.Markers;
```

--------------------------------

### Accessing Configs API

Source: https://docs.gamebeast.gg/Unity/API/Configs

Get a reference to the Gamebeast SDK's Configs API. This is the entry point for all configuration-related operations.

```javascript
var gamebeastConfigs = GamebeastSdk.Configs;
```

--------------------------------

### Get Gamebeast Service

Source: https://docs.gamebeast.gg/Roblox/Overview

This snippet shows how to retrieve a specific service module from the Gamebeast SDK, such as the Markers service.

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

--------------------------------

### GetGroupForPlayer Usage Example

Source: https://docs.gamebeast.gg/Roblox/API/Experiments

Demonstrates how to use the GetGroupForPlayer method to retrieve a player's experiment group metadata and handle cases where the player is not in any group.

```lua
local groupMetaData = GamebeastExperiments:GetGroupForPlayer(player)

if groupMetaData then
    print("Player is in group", groupMetaData.groupName, "of experiment", groupMetaData.experimentName)
else
    print("Player is not in any experiment group.")
end
```

--------------------------------

### Example Formula Calculation

Source: https://docs.gamebeast.gg/Features/QueryBuilder

This formula calculates experience stickiness using Daily Active Users (DAU) and Monthly Active Users (MAU). The result is displayed as a new line in the visualization.

```plaintext
(A / B) * 100
```

--------------------------------

### Fetch Gamebeast Markers Service

Source: https://docs.gamebeast.gg/Roblox/API

Demonstrates how to get the ReplicatedStorage service and the Gamebeast module, then fetch the Markers service. This is a common pattern for accessing Gamebeast services.

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

local GamebeastMarkers = Gamebeast:GetService("Markers")
```

--------------------------------

### Get Multiple Config Values by Path

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Retrieves values for multiple configurations by providing an array of string paths. The method yields until all specified configs are loaded.

```lua
-- Path (array of strings)
local SunPosition = GamebeastConfigs:Get({"SunPosition"})
local Health = GamebeastConfigs:Get({"NPCs", "Spider", "Health"})
```

--------------------------------

### Get Single Config Value

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Retrieves the value of a specific configuration using its string path. The method yields until the config is loaded.

```lua
-- string
local SunPosition = GamebeastConfigs:Get("SunPosition")
```

--------------------------------

### Get(configKey)

Source: https://docs.gamebeast.gg/Unity/API/Configs

Retrieves a specific configuration value from Gamebeast using its key. This method supports generic type arguments to deserialize the configuration into a specified object type.

```APIDOC
## Get(configKey)

### Description
Retrieves a configuration value from Gamebeast by its unique key. The method supports generic type parameters to deserialize the configuration into a specified object.

### Method Signature
`object Get<T>(string configKey)`

### Parameters
#### Path Parameters
- **configKey** (string) - Required - The key of the configuration to retrieve.

### Usage Example
```csharp
public class ConfigExample
{
    public float myNumber;
}

var configValue = GamebeastSdk.Configs.Get<ConfigExample>("exampleConfigKey");
```
```

--------------------------------

### Get Config Value

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Retrieves the value of a specific configuration. This method will yield until the configs are loaded. It accepts a single string or a list of strings for the path.

```APIDOC
## :Get(path)

### Description
Retrieves the value of a specific config. It can accept either a single string or a list of strings as the `path` parameter. The :Get method will yield until the configs are loaded from Gamebeast.

### Parameters
#### path
- **path** (string | {string}) - Required - The configuration path to retrieve. You can provide either a single string or a list of strings.

### Usage
```lua
-- string
local SunPosition = GamebeastConfigs:Get("SunPosition")

-- Path (array of strings)
local SunPosition = GamebeastConfigs:Get({"SunPosition"})
local Health = GamebeastConfigs:Get({"NPCs", "Spider", "Health"})
```
```

--------------------------------

### Get Player-Specific Config Value

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Retrieve the value of a specific configuration for a given player. This method will wait until configurations are loaded. Use for single string or array of strings paths.

```Lua
game:GetService("Players").PlayerAdded:Connect(function(player : Player)
    if GamebeastConfigs:IsReady() == false then
        print("Configs are not ready yet, :GetForPlayer will yield until they are ready.")
    end
 
    -- string
    local SunPosition = GamebeastConfigs:GetForPlayer(player, "SunPosition")
 
    -- Path (array of strings)
    local SunPosition = GamebeastConfigs:GetForPlayer(player, {"SunPosition"})
    local Health = GamebeastConfigs:GetForPlayer(player, {"NPCs", "Spider", "Health"})
end)
```

--------------------------------

### Get Cohort Membership Status Async

Source: https://docs.gamebeast.gg/Roblox/API/Cohorts

Retrieves the cohort membership status for a list of user IDs. Wrap this call in pcall for error handling. Returns a dictionary mapping user IDs to their membership status (boolean).

```lua
local success, data = pcall(function()
    return GamebeastCohorts:GetCohortMembershipStatusAsync("My Cohort", {69935436, 51501379})
end)
 
if success then
    for userId, isMember in pairs(data) do
        print("User ID:", userId, "Is Member:", isMember)
    end
else
    warn("Failed to get cohort membership status:", data)
end
```

--------------------------------

### IsReady()

Source: https://docs.gamebeast.gg/Unity/API/Configs

Checks if the configurations have been successfully loaded and are ready for access. Returns a boolean indicating the readiness status.

```APIDOC
## IsReady()

### Description
Checks whether the configurations have been loaded and are ready to be accessed.

### Method Signature
`bool IsReady()`

### Usage Example
```csharp
if (GamebeastSdk.Configs.IsReady())
{
    // Configurations are ready to be accessed.
}
```
```

--------------------------------

### Init(apiKey)

Source: https://docs.gamebeast.gg/Unity/Overview

Initializes the Gamebeast SDK. This function must be called once before any other SDK methods. It takes your API key as a string argument.

```APIDOC
## Init(apiKey)

### Description
This function must be called once to initialize the Gamebeast SDK. Attempting to call any other SDK method before calling `Init` will result in an error.

### Method
`GamebeastSdk.Init(apiKey: string)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **apiKey** (string) - Required - The API key for the SDK.

### Request Example
```csharp
GamebeastSdk.Init("abcd-efgh-1234-5678");
```

### Response
#### Success Response (void)
This method does not return a value.

#### Response Example
N/A
```

--------------------------------

### Initialize Gamebeast SDK in Unity

Source: https://docs.gamebeast.gg/Unity/Installation

Add this script to your Unity project to initialize the Gamebeast SDK. Ensure you replace the placeholder API key with your actual key.

```csharp
using UnityEngine;
using Gamebeast.Runtime;

public class GamebeastStarter : MonoBehaviour
{
    void Start()
    {
        GamebeastSdk.Init("abcd-efgh-1234-5678");
    }
}
```

--------------------------------

### OnReady(callback)

Source: https://docs.gamebeast.gg/Unity/API/Configs

Subscribes a callback function to be invoked once the configurations are fully loaded and ready. If already loaded, the callback is invoked immediately.

```APIDOC
## OnReady(callback)

### Description
Registers a callback function that will be executed when the configurations are completely loaded and ready for use. If configurations are already loaded upon subscription, the callback is invoked immediately.

### Method Signature
`IDisposable OnReady(Action callback)`

### Parameters
#### Path Parameters
- **callback** (Action) - Required - The function to execute when configurations are ready.

### Usage Example
```csharp
GamebeastSdk.Configs.OnReady(() =>
{
    // Configurations are ready to be accessed.
});
```
```

--------------------------------

### Callback when Configs are Ready

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Fires a callback function once all configurations have been successfully loaded from Gamebeast.

```APIDOC
## :OnReady(callback)

### Description
Fires a callback once the configs are loaded from Gamebeast.

### Parameters
#### callback
- **callback** (function) - Required - Callback function fired when the configs are ready. It receives the loaded `configs` as an argument.

### Usage
```lua
GamebeastConfigs:OnReady(function(configs)
    print("Configs are ready!", configs)
end)
```
```

--------------------------------

### Initialize Gamebeast SDK in Server Script

Source: https://docs.gamebeast.gg/Roblox/Installation

Use this code in a server script to initialize the Gamebeast SDK with your API key. Ensure the Gamebeast module is accessible from ReplicatedStorage.

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

Gamebeast:Setup({
    key = "abcd-efgh-1234-5678",
})
```

--------------------------------

### Initialize Gamebeast SDK

Source: https://docs.gamebeast.gg/Unity/Overview

Call this function once to initialize the Gamebeast SDK with your API key. Other SDK methods cannot be called before this.

```csharp
GamebeastSdk.Init("abcd-efgh-1234-5678");
```

--------------------------------

### Execute Callback When Configs are Ready

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Fires a callback function once all configurations have been successfully loaded from Gamebeast. The callback receives the loaded configurations as an argument.

```lua
GamebeastConfigs:OnReady(function(configs)
    print("Configs are ready!", configs)
end)
```

--------------------------------

### Initialize Gamebeast Configs Service

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Requires the Gamebeast module and retrieves the Configs service. This is a prerequisite for using other config methods.

```lua
local Gamebeast = require(game:GetService("ReplicatedStorage"):WaitForChild("Gamebeast"))
local GamebeastConfigs = Gamebeast:GetService("Configs")
```

--------------------------------

### Callback on Configuration Ready

Source: https://docs.gamebeast.gg/Unity/API/Configs

Subscribe to an event that triggers when configurations are fully loaded. If already loaded, the callback is invoked immediately.

```csharp
gamebeastConfigs.OnReady(() =>
{
    // Configurations are ready to be accessed, do something.
});
```

--------------------------------

### Check Configuration Readiness

Source: https://docs.gamebeast.gg/Unity/API/Configs

Check if the configurations have been loaded and are ready for access. Use this before attempting to retrieve configuration values.

```csharp
if (gamebeastConfigs.IsReady())
{
    // Configurations are ready to be accessed, do something.
}
```

--------------------------------

### Gamebeast SDK Initialization with API Key

Source: https://docs.gamebeast.gg/Unity/Installation

This is the line of code used to initialize the Gamebeast SDK. Remember to replace the placeholder with your project's API key.

```csharp
GamebeastSdk.Init("abcd-efgh-1234-5678"); // Replace with your API key.
```

--------------------------------

### Listen for Multiple Config Changes by Path

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Sets up a callback to be executed when any of the configurations specified by an array of paths change. Returns an RBXScriptSignal for managing the connection.

```lua
-- Path (array of strings)
local ChangedConnection = GamebeastConfigs:OnChanged({"Lighting", "Atmosphere"}, function(newValue, oldValue)
    print("New config", newValue)
end)
```

--------------------------------

### Check if Configs are Ready

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Returns a boolean indicating whether all configurations have been loaded and are ready for use.

```APIDOC
## :IsReady()

### Description
Returns a boolean indicating whether the configs are loaded and ready to be used.

### Return Value
- **boolean** - `true` if configs are ready, `false` otherwise.

### Usage
```lua
if GamebeastConfigs:IsReady() then
    print("Configs are ready!")
end
```
```

--------------------------------

### Observe Player Config Availability and Changes

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Callback when a player's configuration is ready or changes. Handles both initial availability and subsequent updates. Accepts a single string or an array of strings for the path.

```Lua
game:GetService("Players").PlayerAdded:Connect(function(player : Player)
    -- string
    GamebeastConfigs:ObserveForPlayer("SunPosition", function(newValue, oldValue)
        -- Old value will be nil if the config was not previously available
        print("Config is ready/changed", newValue)
    end)
 
    -- Path (array of strings)
    local ObserveConnection = GamebeastConfigs:ObserveForPlayer({"Lighting", "Atmosphere"}, function(newValue, oldValue)
        print("Config is ready/changed", newValue)
    end)
end)
```

--------------------------------

### Listen for Single Config Changes

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Sets up a callback to be executed whenever a specific configuration's value changes. Accepts a single string path.

```lua
-- string
GamebeastConfigs:OnChanged("SunPosition", function(newValue, oldValue)
    print("New config", newValue)
end)
```

--------------------------------

### Check if Configs are Ready

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Returns a boolean indicating whether all configurations have been loaded and are ready for use. Useful for conditional logic before accessing config values.

```lua
if GamebeastConfigs:IsReady() then
    print("Configs are ready!")
end
```

--------------------------------

### Accessing Services

Source: https://docs.gamebeast.gg/Unity/Overview

After initializing the SDK, you can access various services provided by the Gamebeast SDK. Each service is accessible via a static property on the `GamebeastSdk` class.

```APIDOC
## Accessing Services

### Description
After initializing the SDK, you can access various services provided by the Gamebeast SDK. Each service is accessible via a static property on the `GamebeastSdk` class.

### Example: Accessing the Markers Service
```csharp
var markersService = GamebeastSdk.Markers;
markersService.SendMarker("example_marker", new { value = 42 });
```
```

--------------------------------

### Observe Single Config Availability and Changes

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Fires a callback when a specific configuration is ready or its value changes. The old value will be nil if the config was not previously available. Accepts a single string path.

```lua
-- string
GamebeastConfigs:Observe("SunPosition", function(newValue, oldValue)
    -- Old value will be nil if the config was not previously available
    print("Config is ready/changed", newValue)
end)
```

--------------------------------

### Observe Multiple Configs Availability and Changes by Path

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Fires a callback when any of the configurations specified by an array of paths become available or change. Returns an RBXScriptSignal for managing the connection.

```lua
-- Path (array of strings)
local ObserveConnection = GamebeastConfigs:Observe({"Lighting", "Atmosphere"}, function(newValue, oldValue)
    print("Config is ready/changed", newValue)
end)
```

--------------------------------

### :GetService

Source: https://docs.gamebeast.gg/Roblox/Overview

Retrieves a specific service module from the Gamebeast SDK. Available services are documented separately.

```APIDOC
## :GetService(serviceName)

### Description
Retrieves a specific service module from the Gamebeast SDK. All available services can be found documented elsewhere.

### Method
`GetService`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **serviceName** (string) - Required. The name of the SDK service to retrieve.

### Request Example
```lua
GamebeastMarkers = Gamebeast:GetService("Markers") :: Gamebeast.MarkersService
```

### Response
#### Success Response (GamebeastService)
Returns the requested Gamebeast service module.

#### Response Example
```lua
-- Example response is dependent on the service requested
-- For instance, if "Markers" service is requested:
-- GamebeastMarkers = Gamebeast.MarkersService
```
```

--------------------------------

### ObserveForPlayer

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Fires a callback when a player's target configuration changes or becomes available. Accepts a single string or a list of strings for the `path`.

```APIDOC
## ObserveForPlayer

### Description
Fires the provided callback when the player’s target config either changed, or becomes available after being initially fetched from Gamebeast. Accepts a single string or an array of strings for the `path`.

### Method
`GamebeastConfigs:ObserveForPlayer(player, path, callback)`

### Parameters
#### player
- **player** (Player) - Required - The player whose config we’re observing.
#### path
- **path** (string | {string}) - Required - The configuration path to retrieve. Can be a single string or an array of strings.
#### callback
- **callback** ((newValue : any, oldValue : any) -> ()) - Required - Callback function fired when the config on the provided path is ready, or is changed.

### Usage Example
```lua
game:GetService("Players").PlayerAdded:Connect(function(player : Player)
    -- string
    GamebeastConfigs:ObserveForPlayer("SunPosition", function(newValue, oldValue)
        -- Old value will be nil if the config was not previously available
        print("Config is ready/changed", newValue)
    end)

    -- Path (array of strings)
    local ObserveConnection = GamebeastConfigs:ObserveForPlayer({"Lighting", "Atmosphere"}, function(newValue, oldValue)
        print("Config is ready/changed", newValue)
    end)
end)
```
```

--------------------------------

### Observe Config Availability and Changes

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Fires a callback when a target config changes or becomes available after initial fetching. Similar to :OnChanged but also triggers on initial availability.

```APIDOC
## :Observe(path, callback)

### Description
Fires the provided callback when the target config either changed, **or** becomes available after being initially fetched from Gamebeast.

### Parameters
#### path
- **path** (string | {string}) - Required - The configuration path to retrieve. You can provide either a single string or a list of strings.
#### callback
- **callback** (function) - Required - Callback function fired when the config on the provided path is ready, or is changed. It receives `newValue` and `oldValue` as arguments.

### Usage
```lua
-- string
GamebeastConfigs:Observe("SunPosition", function(newValue, oldValue)
    -- Old value will be nil if the config was not previously available
    print("Config is ready/changed", newValue)
end)

-- Path (array of strings)
local ObserveConnection = GamebeastConfigs:Observe({"Lighting", "Atmosphere"}, function(newValue, oldValue)
    print("Config is ready/changed", newValue)
end)
```
```

--------------------------------

### Listen for Config Changes

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Listens for changes to the value of a specific configuration. It accepts a single string or a list of strings for the path, and a callback function to execute when the value changes.

```APIDOC
## :OnChanged(path, callback)

### Description
Listens to the value of a specific config changing. It can accept either a single string or a list of strings as the `path` parameter.

### Parameters
#### path
- **path** (string | {string}) - Required - The configuration path to retrieve. You can provide either a single string or a list of strings.
#### callback
- **callback** (function) - Required - Callback function fired when the config on the provided path changes. It receives `newValue` and `oldValue` as arguments.

### Usage
```lua
-- string
GamebeastConfigs:OnChanged("SunPosition", function(newValue, oldValue)
    print("New config", newValue)
end)

-- Path (array of strings)
local ChangedConnection = GamebeastConfigs:OnChanged({"Lighting", "Atmosphere"}, function(newValue, oldValue)
    print("New config", newValue)
end)
```
```

--------------------------------

### Listen for Configuration Changes

Source: https://docs.gamebeast.gg/Unity/API/Configs

Subscribe to changes for a specific configuration. A callback is invoked when the configuration's value is updated.

```csharp
GamebeastSdk.Configs.OnChanged("MyConfig", () =>
{
    var newValue = GamebeastSdk.Configs.Get<string>("MyConfig");
    Debug.Log($
```

--------------------------------

### Send Purchase Granted Marker

Source: https://docs.gamebeast.gg/Roblox/API/Markers

Sends a 'Purchase' marker when a dev product is granted within the MarketplaceService.ProcessReceipt callback. This should only be called for new purchases.

```lua
local MarketplaceService = game:GetService("MarketplaceService")
local DataStoreService = game:GetService("DataStoreService")

local PurchaseHistoryStore = DataStoreService:GetDataStore("PurchaseHistory")

MarketplaceService.ProcessReceipt = function(receiptInfo)
    local success, isPurchaseRecorded = pcall(function()
		return PurchaseHistoryStore:UpdateAsync(receiptInfo.PurchaseId, function(alreadyPurchased)
			if alreadyPurchased then
				return true
			end

            -- NOTE: In your experience, you should have more checks. Make sure to look at Roblox's documentation for more information.
 
            local success, result = pcall(function()
                -- Grant the product to the player
            end)
 
			if success then
                -- Send the purchase marker to Gamebeast only if we've never processed this purchase before.
                GamebeastMarkers:SendNewPurchaseGrantedMarker(receiptInfo)
                return true
            else
                -- Do not record the purchase if granting the product failed
				error("Failed to process a product purchase")
				return nil
			end
		end)
	end)
 
	if success == false or isPurchaseRecorded == nil then
		return Enum.ProductPurchaseDecision.NotProcessedYet
	else
		-- IMPORTANT: Tell Roblox that the game successfully handled the purchase
		return Enum.ProductPurchaseDecision.PurchaseGranted
	end
end
```

--------------------------------

### GetForPlayer

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Retrieves the value of a specific configuration for a given player. This method will yield until the configurations are loaded.

```APIDOC
## GetForPlayer

### Description
Retrieves the value of a specific configuration for a specific player. It accepts a single string or a list of strings for the `path`.

### Method
`GamebeastConfigs:GetForPlayer(player, path)`

### Parameters
#### player
- **player** (Player) - Required - The player to retrieve the config for.
#### path
- **path** (string | {string}) - Required - The configuration path to retrieve. Can be a single string or an array of strings.

### Usage Example
```lua
game:GetService("Players").PlayerAdded:Connect(function(player : Player)
    -- string
    local SunPosition = GamebeastConfigs:GetForPlayer(player, "SunPosition")

    -- Path (array of strings)
    local SunPosition = GamebeastConfigs:GetForPlayer(player, {"SunPosition"})
    local Health = GamebeastConfigs:GetForPlayer(player, {"NPCs", "Spider", "Health"})
end)
```
```

--------------------------------

### Listen for Player Config Changes

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Subscribe to changes in a specific player's configuration value. This function can accept a single string or an array of strings for the configuration path.

```Lua
game:GetService("Players").PlayerAdded:Connect(function(player : Player)
    -- string
    GamebeastConfigs:OnChangedForPlayer(player, "SunPosition", function(newValue, oldValue)
        print("New config", newValue)
    end)
 
    -- Path (array of strings)
    local ChangedConnection = GamebeastConfigs:OnChangedForPlayer(player, {"Lighting", "Atmosphere"}, function(newValue, oldValue)
        print("New config", newValue)
    end)
end)
```

--------------------------------

### Require Gamebeast Services

Source: https://docs.gamebeast.gg/Roblox/API/Jobs

This snippet shows how to require the Gamebeast module and access the Jobs service. Ensure the Gamebeast module is present in ReplicatedStorage.

```lua
local Gamebeast = require(game:GetService("ReplicatedStorage"):WaitForChild("Gamebeast"))
local GamebeastJobs = Gamebeast:GetService("Jobs") :: Gamebeast.JobsService
```

--------------------------------

### OnChangedForPlayer

Source: https://docs.gamebeast.gg/Roblox/API/Configs

Listens for changes to a specific player's configuration value at a given path. It can accept a single string or a list of strings for the `path`.

```APIDOC
## OnChangedForPlayer

### Description
Listens to changes in a specific player's configuration value at a given path. Accepts a single string or an array of strings for the `path`.

### Method
`GamebeastConfigs:OnChangedForPlayer(player, path, callback)`

### Parameters
#### player
- **player** (Player) - Required - The player whose config we’re listening to.
#### path
- **path** (string | {string}) - Required - The configuration path to retrieve. Can be a single string or an array of strings.
#### callback
- **callback** ((newValue : any, oldValue : any) -> ()) - Required - Callback function fired when the config on the provided path changes.

### Usage Example
```lua
game:GetService("Players").PlayerAdded:Connect(function(player : Player)
    -- string
    GamebeastConfigs:OnChangedForPlayer(player, "SunPosition", function(newValue, oldValue)
        print("New config", newValue)
    end)

    -- Path (array of strings)
    local ChangedConnection = GamebeastConfigs:OnChangedForPlayer(player, {"Lighting", "Atmosphere"}, function(newValue, oldValue)
        print("New config", newValue)
    end)
end)
```
```

--------------------------------

### Access Markers Service

Source: https://docs.gamebeast.gg/Unity/Overview

Access the Markers service via a static property on the GamebeastSdk class to send markers with associated data.

```csharp
var markersService = GamebeastSdk.Markers;
markersService.SendMarker("example_marker", new { value = 42 });
```

--------------------------------

### Handle Failed Markers Callback

Source: https://docs.gamebeast.gg/Roblox/API/Markers

Registers a callback function that is executed when markers fail to send to Gamebeast. The callback receives a list of the markers that failed.

```lua
GamebeastMarkers:OnMarkersFailed(function(failedMarkers)
    print("The following markers failed to send to Gamebeast:", failedMarkers)
 
    -- Save to DataStore for retrying later, etc.
end)
```

--------------------------------

### Retrieve Configuration Value

Source: https://docs.gamebeast.gg/Unity/API/Configs

Retrieve a specific configuration value using its key. Supports generic type casting for structured configurations.

```csharp
public class ConfigExample
{
    public float myNumber;
}
 
var configValue = gamebeastConfigs.Get<ConfigExample>("exampleConfigKey");
```

--------------------------------

### OnChanged(configName, callback)

Source: https://docs.gamebeast.gg/Unity/API/Configs

Subscribes a callback function to be invoked when a specific configuration value changes. The callback receives the updated configuration object.

```APIDOC
## OnChanged(configName, callback)

### Description
Subscribes a callback to an event that is triggered whenever a specified configuration changes. The callback function receives the updated configuration value.

### Method Signature
`IDisposable OnChanged(string configName, Action<object> callback)`

### Parameters
#### Path Parameters
- **configName** (string) - Required - The name of the configuration to monitor for changes.
- **callback** (Action<object>) - Required - The function to execute when the configuration changes. It receives the new configuration value.

### Usage Example
```csharp
GamebeastSdk.Configs.OnChanged("MyConfig", (newValue) =>
{
    Debug.Log($"Config 'MyConfig' changed! New value: {newValue}");
});
```
```

--------------------------------

### Type Casting Gamebeast Markers Service

Source: https://docs.gamebeast.gg/Roblox/API

Shows how to explicitly cast the fetched Markers service to its specific type for better type checking and autocompletion in Luau.

```lua
local GamebeastMarkers = Gamebeast:GetService("Markers") :: Gamebeast.MarkersService
```

--------------------------------

### Replace Placeholder API Key

Source: https://docs.gamebeast.gg/Roblox/Installation

This snippet shows how to replace the placeholder API key with your actual Gamebeast API key in your Roblox Studio script.

```lua
key = "abcd-efgh-1234-5678", -- Replace with your API key.
```

--------------------------------

### OnMarkersFailed

Source: https://docs.gamebeast.gg/Roblox/API/Markers

Registers a callback function that is invoked when markers fail to send to Gamebeast, providing a list of the failed markers.

```APIDOC
## :OnMarkersFailed(callback)

### Description
Fires a callback with a raw list of markers that failed to send to Gamebeast.

### Parameters
- **callback** ((failedMarkers : {{[string] : any}}) -> ()) - Required - The callback function that will be fired if markers fail to send.

### Usage Example
```lua
GamebeastMarkers:OnMarkersFailed(function(failedMarkers)
    print("The following markers failed to send to Gamebeast:", failedMarkers)
end)
```
```

--------------------------------

### Require Gamebeast SDK

Source: https://docs.gamebeast.gg/Roblox/Overview

This snippet shows how to require the Gamebeast SDK module in your Roblox project.

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

--------------------------------

### Send a General Engagement Marker

Source: https://docs.gamebeast.gg/Unity/API/Markers

Send a marker with associated data to track general in-game events. Use this for events not tied to a specific user.

```csharp
gamebeastMarkers.SendMarker("RoundEnded", new { Score = 600, Map = "Office", Duration = 120 });
```

--------------------------------

### RetryFailedMarkersAsync

Source: https://docs.gamebeast.gg/Roblox/API/Markers

Attempts to resend a list of markers that previously failed to transmit to Gamebeast. Returns true on success and false on failure.

```APIDOC
## :RetryFailedMarkersAsync(markers)

### Description
Retries sending a list of markers that previously failed to send to Gamebeast. This method will yield and return true if the retry was successful, and false if it failed again.

### Parameters
- **markers** ({{[string] : any}}) - Required - The list of markers that failed to send. This should be the raw list of markers received from the `:OnMarkersFailed` callback.

### Usage Example
```lua
local FailedMarkersFromDatastore = getFailedMarkers()
local success = GamebeastMarkers:RetryFailedMarkersAsync(FailedMarkersFromDatastore)
if success then
    print("Successfully retried failed markers.")
else
    print("Failed to send markers.")
end
```
```

--------------------------------

### Set Custom Job Callback

Source: https://docs.gamebeast.gg/Roblox/API/Jobs

Sets a callback function for a custom job. This function executes when the job is triggered from the Gamebeast dashboard. Callbacks should only be set once per job. Errors within the callback will be reported as 'Failed' on the dashboard.

```lua
GamebeastJobs:SetCallback("My Custom Job", function(config : {[string] : any})
    print("My custom job was triggered!")

    if config.SomeProperty == true then
        return "Job completed with SomeProperty set to true!"
    else
        error("An error occurred!")
    end
end)
```

--------------------------------

### SendUserMarker

Source: https://docs.gamebeast.gg/Unity/API/Markers

Sends a marker for a specific user with the specified type and value to Gamebeast. This is useful for tracking user-specific events.

```APIDOC
## SendUserMarker(userId, markerType, value)

### Description
This method sends a marker for a specific user with the specified value to Gamebeast.

### Parameters
#### Path Parameters
* **userId** (string) - Required - The ID of the user.
* **markerType** (string) - Required - The name of the marker.
* **value** (object) - Required - The value of the marker.

### Usage
```csharp
gamebeastMarkers.SendUserMarker("user123", "ItemPurchased", new { ItemID = "sword_001", Price = 150 });
```
```

--------------------------------

### SendNewPurchaseGrantedMarker

Source: https://docs.gamebeast.gg/Roblox/API/Markers

Sends a `Purchase` marker for a dev product purchase within the `MarketplaceService.ProcessReceipt` callback. It requires receipt information and an optional position.

```APIDOC
## :SendNewPurchaseGrantedMarker(receiptInfo, position)

### Description
Sends a `Purchase` marker from a dev product purchase to Gamebeast. This method should be used inside of your game’s `MarketplaceService.ProcessReceipt` callback whenever a **new** purchase is granted.

### Parameters
- **receiptInfo** ({[string] : any}) - Required - The receiptInfo dictionary from the `MarketplaceService.ProcessReceipt` callback.
- **position** (Vector3?) - Optional - The optional marker world position for heatmap visualization.

### Usage Example
```lua
MarketplaceService.ProcessReceipt = function(receiptInfo)
    -- ... (receipt processing logic) ...
    GamebeastMarkers:SendNewPurchaseGrantedMarker(receiptInfo)
    -- ... (return Enum.ProductPurchaseDecision.PurchaseGranted) ...
end
```
```

--------------------------------

### Send a User-Specific Engagement Marker

Source: https://docs.gamebeast.gg/Unity/API/Markers

Send a marker with associated data for a specific user. Use this to track events related to individual user actions or progress.

```csharp
gamebeastMarkers.SendUserMarker("user123", "ItemPurchased", new { ItemID = "sword_001", Price = 150 });
```

--------------------------------

### SendPlayerMarker

Source: https://docs.gamebeast.gg/Roblox/API/Markers

Sends a marker associated with a specific player to Gamebeast. This includes the player instance, marker details, and an optional position.

```APIDOC
## :SendPlayerMarker(player, markerType, value, position)

### Description
Sends a marker associated with a specific player to Gamebeast.

### Parameters
- **player** (Player) - Required - The player instance associated with the marker.
- **markerType** (string) - Required - The name of the marker.
- **value** (number | {[string] : any}) - Required - The value of the marker.
- **position** (Vector3?) - Optional - The optional marker world position for heatmap visualization.

### Usage Example
```lua
local Player = game:GetService("Players").Player1
GamebeastMarkers:SendPlayerMarker(Player, "Coins", {Amount = 50, FoundIn = "Lobby"})
GamebeastMarkers:SendPlayerMarker(Player, "Coins", 50)
GamebeastMarkers:SendPlayerMarker(Player, "Coins", 50, Player.Character.PrimaryPart.Position)
```
```

--------------------------------

### SetCallback

Source: https://docs.gamebeast.gg/Roblox/API/Jobs

Sets a callback function for a specific job. This function is executed when the job is triggered from the Gamebeast dashboard. Callbacks should be set only once per job to avoid overwriting.

```APIDOC
## SetCallback(jobName, callback)

### Description
This method sets a callback function for a specific job. The callback function will be called when the user triggers a custom job on the dashboard with the same name as the specified `jobName`.
Callbacks should only be set **once per job** , as setting multiple callbacks for the same job will overwrite the previous callback. When a callback is triggered, `config` will be equal to the configuration object that was passed when the job was triggered from the Gamebeast dashboard.
If a job callback errors, it will appear on the Gamebeast dashboard as “Failed”.

### Parameters
#### Path Parameters
- **jobName** (string) - Required - The name of the custom job.
- **callback** (function) - Required - The function to run when the job is executed. It accepts a `config` object ({[string] : any}) and returns any.

### Usage
```lua
GamebeastJobs:SetCallback("My Custom Job", function(config : {[string] : any})
    print("My custom job was triggered!")
 
    if config.SomeProperty == true then
        return "Job completed with SomeProperty set to true!"
    else
        error("An error occurred!")
    end
end)
```
```

--------------------------------

### SendMarker

Source: https://docs.gamebeast.gg/Unity/API/Markers

Sends a marker with the specified type and value to Gamebeast. This is used for general engagement tracking.

```APIDOC
## SendMarker(markerType, value)

### Description
This method sends a marker with the specified value to Gamebeast.

### Parameters
#### Path Parameters
* **markerType** (string) - Required - The name of the marker.
* **value** (object) - Required - The value of the marker.

### Usage
```csharp
gamebeastMarkers.SendMarker("RoundEnded", new { Score = 600, Map = "Office", Duration = 120 });
```
```

--------------------------------

### GetGroupForPlayer

Source: https://docs.gamebeast.gg/Roblox/API/Experiments

Retrieves the experiment group metadata for a specific player. Returns nil if the player is not in any experiment group.

```APIDOC
## GetGroupForPlayer(player)

### Description
This method retrieves the experiment group metadata for a specific player. If the player is not in any experiment group, this method will return `nil`.

### Parameters
#### Path Parameters
- **player** (Player) - Required - The player to get the group for.

### Usage
```lua
local groupMetaData = GamebeastExperiments:GetGroupForPlayer(player)

if groupMetaData then
    print("Player is in group", groupMetaData.groupName, "of experiment", groupMetaData.experimentName)
else
    print("Player is not in any experiment group.")
end
```

### Response
#### Success Response
- **ExperimentGroupMetadata?** - The experiment group metadata for the player, or nil if the player is not in any group.

### Types
#### ExperimentGroupMetadata
```lua
type ExperimentGroupMetadata = {
    experimentName: string, -- The name of the experiment this group belongs to.
    groupName: string, -- The name of the group this player is in.
}
```
```
Tokens:
Raw