Abtest

2. Name the Attribute Key

Use dot-separated hierarchical names: {System}.{Feature}.{Parameter}

Naming rules

• PascalCase each segment
• Boolean toggles: end with .Enabled (e.g., Eco.DiversityBonus.Enabled)
• Numeric tunables: name the parameter directly (e.g., Event.Money.StormDuration)
• String variants: name the choice (e.g., FTU.TutorialGroup)

Real examples from the codebase

-- Job-level (server-wide)
Event.Money.StormDuration          -- number (seconds)
Event.FireAndIce.MutationChance    -- number (0-1)
Wave.MinGapStudsMin                -- number
GenRate.ShowOverhead               -- boolean
AB.HideCarryStand                  -- boolean
LuckyBlock.NaturalSpawn.Enabled    -- boolean

-- Player-level (per-player)
FTU.SessionCountThreshold          -- number
Camera.ZoomMultiplier              -- number
Eco.DiversityBonus.Enabled         -- boolean
FriendRequest.Enabled              -- boolean
Steal.Common                       -- number (weight)

3. Sync vs Async

Rule: Default to sync. Only use async when you explicitly need to block until the value is available (e.g., deciding whether to teleport a player on join).

4. Implementation Workflow

Step 1: Add the import

local ABTests = require(ReplicatedStorage.UserGenerated.ABTests)

Place it in the -- Imports section of the service/controller.

Step 2: Replace hardcoded values

Find the hardcoded value and replace it with an ABTests call. Always use the current hardcoded value as the default so behavior is unchanged without backend config.

Before:

local STORM_DURATION = 30

After:

local stormDuration = ABTests.GetJobAttribute("Event.Money.StormDuration", 30)

Step 3: Add reactive updates (client only, if needed)

If the value can change at runtime via live config updates, listen for changes. Which event depends on scope:

• Player-level: ABTests.PlayerUpdated
• Job-level: ABTests.JobUpdated

Step 4: Add condition callbacks (if needed)

If the test needs custom targeting conditions (beyond what backend can do with built-in conditions), add a callback to ABTestConditions.server.luau. See section 6.

5. Code Templates

Server service -- sync (most common)

For values read during gameplay. No yielding.

-- In a service function
local function processReward(player: Player)
    local multiplier = ABTests.GetJobAttribute("Reward.Multiplier", 1)
    giveReward(player, BASE_REWARD * multiplier)
end

Server service -- async (join flow)

For values needed before a player-specific decision on join.

function MyService.playerAdded(player: Player)
    local threshold = ABTests.GetAttributeAsync(player, "FTU.SpeedThreshold", 200)
    if player.Data.CurrentSpeed >= threshold then
        return
    end
    -- player qualifies for FTU flow
end

Client controller -- player-level with reactive updates

local ABTests = require(ReplicatedStorage.UserGenerated.ABTests)
local Players = game:GetService("Players")

local LocalPlayer = Players.LocalPlayer

local MyController = {}

local function applySettings()
    local enabled = ABTests.GetAttribute(LocalPlayer, "Feature.Enabled", false)
    if type(enabled) ~= "boolean" then
        enabled = false
    end
    -- apply the value
end

function MyController.init()
    -- Apply once loaded
    if ABTests.IsLoaded() then
        applySettings()
    else
        task.spawn(function()
            ABTests.Loaded:Wait()
            applySettings()
        end)
    end

    -- React to live updates
    ABTests.PlayerUpdated:Connect(function(updatedPlayer)
        if updatedPlayer == LocalPlayer then
            applySettings()
        end
    end)
end

return MyController

Client controller -- job-level with reactive updates

local ABTests = require(ReplicatedStorage.UserGenerated.ABTests)

local MyController = {}

local function applySettings()
    local showFeature = ABTests.GetJobAttribute("AB.ShowFeature", true)
    if type(showFeature) ~= "boolean" then
        showFeature = true
    end
    -- apply the value
end

function MyController.init()
    if ABTests.IsLoaded() then
        applySettings()
    else
        task.spawn(function()
            ABTests.Loaded:Wait()
            applySettings()
        end)
    end

    ABTests.JobUpdated:Connect(applySettings)
end

return MyController

Client controller -- async in init (blocking)

When the controller cannot proceed without the value. Use sparingly -- this yields init.

function MyController.init()
    local enabled = ABTests.GetJobAttributeAsync("FTU.HideTower", true)
    if not enabled then
        return
    end
    -- setup tower UI
end

Event module -- job-level tunables

Events typically read many job-level attributes for all their parameters:

local function run(duration: number, _context: any?)
    local messageDelay = ABTests.GetJobAttribute("Event.MyEvent.MessageDelay", 3)
    local messageText = ABTests.GetJobAttribute(
        "Event.MyEvent.Message",
        "My Event has started!"
    )
    local spawnRate = ABTests.GetJobAttribute("Event.MyEvent.SpawnRate", 0.5)
    local maxItems = ABTests.GetJobAttribute("Event.MyEvent.MaxItemCap", 100)

    task.delay(messageDelay, function()
        Popup.GlobalMessage(messageText)
    end)

    -- use spawnRate, maxItems in event logic...

    return function()
        -- cleanup
    end
end

6. Adding Condition Callbacks

Condition callbacks let the backend target tests to specific server/player states. Add them to src/ServerScriptService/UGApp/ABTestConditions.server.luau.

Structure

The file exports a module table of callbacks. All callbacks are auto-registered at the bottom via a loop:

for name, func in pairs(module) do
    if type(name) == "string" and type(func) == "function" then
        ServerABTests.RegisterConditionCallback(name, func)
    end
end

Template for a new callback

--[[
    Description of what this condition checks.
    @param player Required/Optional
    @param arg1 Description
    @return true if condition is met
]]
function module.MyConditionName(
    player: Player?,
    arg1: number,
    arg2: number?
): boolean
    assert(player)
    Asserts.Player(player)
    Asserts.IntegerNonNegative(arg1)
    if arg2 ~= nil then
        Asserts.IntegerNonNegative(arg2)
    end
    -- logic here
    return result
end

Existing callbacks (for reference)

Key rules

• Type signature: (player: Player?, ...any) -> boolean
• Always assert(player) if the condition requires a player
• Validate all arguments with Asserts at the top
• For range checks: min inclusive, max inclusive and optional
• Player conditions can access profile data via Profiles.GetAsync(player, true)
• Server conditions (no player needed) still receive player: Player? parameter

7. Best Practices

1. Default = current behavior. The default value in GetAttribute/GetJobAttribute must match the current hardcoded value. This ensures no behavior change without backend config.

2. Validate returned types. Backend can send unexpected types. Guard booleans and numbers:

   local val = ABTests.GetJobAttribute("Key", true)
   if type(val) ~= "boolean" then val = true end
   

3. Don't yield in hot paths. Use sync GetAttribute/GetJobAttribute in gameplay loops, event handlers, and render callbacks. These return the default if not loaded yet.

4. Comment the ABTest attributes. At the top of the file or above the function, document what attributes are read and their types/defaults:

   -- ABTest Attributes:
   -- - Camera.ZoomMultiplier: number (default 1.3)
   

5. Backend handles test configuration. You implement the attribute reads. Backend configures groups, percentages, conditions, and scheduling. Once your code is merged, backend sets up the test.

6. One attribute per tunable. Don't pack multiple values into a single table attribute when they could be independent. Event.Money.SpawnRate and Event.Money.MaxCap are better than Event.Money.Config = {spawnRate=0.5, maxCap=100}.

8. API Reference

Setup

Works on both client and server:

local ABTests = require(ReplicatedStorage.UserGenerated.ABTests)

Player Attributes

Client can only read LocalPlayer's attributes. Other players always return default.

Job Attributes

Job attributes use the first player in the server (or LocalPlayer on client). All players on a server share the same value.

System State

Events

Default Values

Default values can be any Luau type:

Notes

• Async vs sync: Async methods yield until loaded. Use async for join flows, sync for gameplay loops and event handlers.
• Client limitation: Client can only read LocalPlayer's attributes. Other players always return default.
• How it works: You implement the attribute reads in your code. Backend handles all test configuration (groups, percentages, player/server scoping, scheduling). Once your code is merged, backend configures the test.