Experiments

For more information about Experiments, visit the Experiments Guide.

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

Enrollment happens automatically. The SDK assigns players when they join, and the values returned by Configs already include each player's group changes. You don't need this service to run an experiment. Use it to read assignments, for display, analytics or debugging, and to set the properties your experiments target.

How assignments stay currentCopy Anchor Link

The SDK requests a player's groups when they join, again when their targeting properties change, and then every 30 seconds while they're in the server. That periodic refresh is how a change made on the dashboard, such as moving a player to another group by hand, reaches players already in game. Change how often it runs with the assignmentRefreshRate setting.

A player can be in several experiments at once, as long as they change different keys.

TypesCopy Anchor Link

ExperimentAssignmentCopy Anchor Link

type ExperimentAssignment = {
    experimentId: number,
    experimentName: string,
    groupId: number,
    groupLabel: string, -- The name of the group.
    unitType: "user" | "server", -- Whether a player or the server is assigned.
    source: string?, -- How the group was chosen: "weightedHash", "roundRobin" or "manual".
}

ExperimentPropertyValueCopy Anchor Link

-- Lists hold one type of value, at most 100 items.
type ExperimentPropertyValue = string | number | boolean | { string | number | boolean }

AssignmentsCopy Anchor Link

:GetAssignmentsForPlayer(player)Copy Anchor Link

→{ExperimentAssignment}return type

Returns the player's active assignments, ordered by experiment ID. Empty until their first assignment has resolved, shortly after they join.

UsageCopy Anchor Link

for _, assignment in GamebeastExperiments:GetAssignmentsForPlayer(player) do
    print(player.Name, "is in", assignment.groupLabel, "of", assignment.experimentName)
end

:GetServerAssignments()Copy Anchor Link

→{ExperimentAssignment}return type

Returns the server's active assignments, for experiments that assign whole servers.

UsageCopy Anchor Link

for _, assignment in GamebeastExperiments:GetServerAssignments() do
    print("Server is in", assignment.groupLabel, "of", assignment.experimentName)
end

:OnAssignmentsChangedForPlayer(player, callback)Copy Anchor Link

→RBXScriptConnectionreturn type

Calls callback with the player's full list of assignments whenever it changes. The connection is disconnected automatically shortly after the player leaves, after a last call with their assignments cleared.

UsageCopy Anchor Link

GamebeastExperiments:OnAssignmentsChangedForPlayer(player, function(assignments)
    print(player.Name, "is now in", #assignments, "experiments")
end)

:ObserveAssignmentsForPlayer(player, callback)Copy Anchor Link

→RBXScriptConnectionreturn type

Like :OnAssignmentsChangedForPlayer, but also calls callback once the player's assignments are first resolved, even if they aren't in any experiment.

UsageCopy Anchor Link

game:GetService("Players").PlayerAdded:Connect(function(player)
    GamebeastExperiments:ObserveAssignmentsForPlayer(player, function(assignments)
        for _, assignment in assignments do
            print(player.Name, "is in", assignment.groupLabel, "of", assignment.experimentName)
        end
    end)
end)

:OnServerAssignmentsChanged(callback)Copy Anchor Link

→RBXScriptConnectionreturn type

Calls callback with the server's full list of assignments whenever it changes.

UsageCopy Anchor Link

GamebeastExperiments:OnServerAssignmentsChanged(function(assignments)
    print("Server is now in", #assignments, "experiments")
end)

Targeting propertiesCopy Anchor Link

Experiments can target players on properties. The SDK reports these standard Roblox properties on its own, when an experiment needs them:

Device and input type come from the player's client, so the client must call Gamebeast:Setup() too.

To target on your own data, set properties with the methods below. Each value must be a string, number, boolean, or a list of one of those types with at most 100 items. A player or the server can have at most 100 properties, with names up to 128 characters. The SDK warns and ignores any property outside these limits.

Set a player's properties as soon as their data loads. Changing a property requests their groups again, so a late property can move a player into an experiment partway through their session.

:SetPlayerProperties(player, properties)Copy Anchor Link

→voidreturn type

Sets properties for a player, merged with any set before.

UsageCopy Anchor Link

GamebeastExperiments:SetPlayerProperties(player, {
    vip = true,
    level = 12,
    tags = { "beta", "founder" },
})

:SetPlayerProperty(player, key, value)Copy Anchor Link

→voidreturn type

Sets one property for a player. Pass nil to clear it.

UsageCopy Anchor Link

GamebeastExperiments:SetPlayerProperty(player, "level", 13)

:GetPlayerProperties(player)Copy Anchor Link

→{[string] : ExperimentPropertyValue}return type

Returns a copy of the properties set for a player.

:SetServerProperties(properties)Copy Anchor Link

→voidreturn type

Sets properties for the server, merged with any set before. Server properties also apply to every player in the server. If a player has a property with the same name, theirs wins.

UsageCopy Anchor Link

GamebeastExperiments:SetServerProperties({ region = "eu", mode = "ranked" })

:SetServerProperty(key, value)Copy Anchor Link

→voidreturn type

Sets one property for the server. Pass nil to clear it.

:GetServerProperties()Copy Anchor Link

→{[string] : ExperimentPropertyValue}return type

Returns a copy of the properties set for the server.

DeprecatedCopy Anchor Link

:GetGroupForPlayer(player)Copy Anchor Link

→ExperimentGroupMetadata?return type

Returns the player's first assignment, or the server's if the player has none, as { experimentName: string, groupName: string }. Returns nil if neither is in an experiment.