Owl - Flags: API Reference & Examples

This document provides the full API reference and code examples for working with OwlFlag on the server.

Initialization

OwlFlag.Bootstrap()

Bootstraps the flag system on the server. Initializes the DataStore connection, loads persistent flag states, subscribes to MessagingService and starts background flush and poll loops.

Note: Bootstrap() can only be called from the server (RunService:IsServer()).

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Owl = require(ReplicatedStorage.Owl)
local OwlFlag = Owl.Util.Flag
 
-- > // Initialize OwlFlag on server startup
OwlFlag.Bootstrap()

Flag Management Methods

OwlFlag.CreateFlag(name, config?)

Creates a new flag with the given configuration. Errors if the flag already exists.

• name: string - Non empty flag identifier.
• config: FlagConfig? - Optional configuration settings.
• Returns: FlagState

local flag = OwlFlag.CreateFlag("BetaInventory", {
    Scope = "Public",
    Enabled = true,
    RolloutPercent = 25, -- > // 25% of players will receive this feature
    Whitelist = { 12345678, 87654321 }, -- > // Specific UserIds guaranteed access
    Blacklist = { 99999999 }, -- > // Explicitly blocked UserIds
})

OwlFlag.SetFlag(name, config)

Updates an existing flag, incrementing its version for cross-server synchronization. Creates the flag if it does not already exist.

• name: string - Flag identifier.
• config: FlagConfig - Updated flag configuration settings.
• Returns: FlagState

OwlFlag.SetFlag("BetaInventory", {
    Enabled = true,
    RolloutPercent = 50, -- > // Increased rollout from 25% to 50%
})

OwlFlag.DeleteFlag(name)

Deletes a flag from memory, updates the persistent DataStore registry and notifies all connected servers to delete it locally.

• name: string - Flag identifier.

OwlFlag.DeleteFlag("BetaInventory")

Flag Query Methods

OwlFlag.IsEnabled(name, player)

Checks whether a flag is enabled for a given player based on Whitelists, Blacklists, overall status and deterministic percentage rollouts.

• name: string - Flag identifier.
• player: Player - The target player.
• Returns: boolean

Players.PlayerAdded:Connect(function(player)
    if OwlFlag.IsEnabled("BetaInventory", player) then
        print(player.Name .. " has access to the Beta Inventory!")
    else
        print(player.Name .. " is using the standard inventory.")
    end
end)

OwlFlag.GetAll()

Returns a shallow copy table containing all registered flags and their states.

• Returns: {[string]: FlagState}

local allFlags = OwlFlag.GetAll()
 
for flagName, flagState in pairs(allFlags) do
    print(flagName, "Enabled:", flagState.Enabled)
end

OwlFlag.GetBucket(name, userId)

Utility function that returns the calculated hash bucket (0–99) for a given user and flag. Useful for debugging rollouts.

• name: string - Flag identifier.
• userId: number - Player's Roblox userId.
• Returns: number

Events & Signals

OwlFlag.Changed

Signal fired whenever a flag is created, modified or deleted across any server instance.

• Parameters: (flagName: string, state: FlagState?)

OwlFlag.Changed:Connect(function(flagName, state)
    if state then
        print(("Flag %q updated to version %d"):format(flagName, state.Version))
    else
        print(("Flag %q was deleted"):format(flagName))
    end
end)

Cleanup

OwlFlag.Destroy()

Destroys the module runtime state, cleans up Trove connections, unsubscribes from MessagingService and clears internal flag caches.

OwlFlag.Destroy()