Overview

Owl - Flags is a modern, reliable feature flag and feature-toggle library built for Roblox. It allows server-side management of dynamic configuration flags, user rollout targeting, whitelisting, blacklisting and cross-server synchronization via DataStoreService and MessagingService.

Key Features

• Cross-Server Synchronization: Instant propagation of flag updates across server instances using Roblox's MessagingService.
• Data Persistence: Automatic persistence to DataStoreService (OwlFlags_v1), ensuring flag configurations survive server restarts.
• Resilient Fallback: Built-in fallback polling loop in case MessagingService experiences disruptions.
• Targeted Rollouts: Consistent user bucket hashing using a stable string hashing algorithm (stableHash) to seamlessly control percentage-based feature rollouts.
• Scope & Access Control: Support for Public, Private, and Shared flag scopes, along with granular User ID Whitelist and Blacklist checks.
• Trove Lifecycle Integration: Automated cleanup and task handling using Trove.

Types & Data Structures

Defines the visibility scope of a flag:

export type FlagScope = "Public" | "Private" | "Shared"

FlagState

Represents the internal state of a feature flag stored in memory and persisted in the DataStore:

export type FlagState = {
    Name: string,
    Scope: FlagScope,
    Enabled: boolean,
    RolloutPercent: number,
    Whitelist: {[number]: boolean},
    Blacklist: {[number]: boolean},
    UpdatedAt: number,
    Version: number,
}

FlagConfig

Configuration structure provided when creating or modifying a flag:

export type FlagConfig = {
    Scope: FlagScope?,
    Enabled: boolean?,
    RolloutPercent: number?,
    Whitelist: {number}?,
    Blacklist: {number}?,
}

Flag Evaluation Logic (IsEnabled)

When OwlFlag.IsEnabled(flagName, player) is evaluated, the module executes the following checks in order:

1. Existence Check: Defaults to false if the flag is unknown.
2. Blacklist Check: Immediately returns false if plr.UserId is blacklisted.
3. Whitelist Check: Immediately returns true if plr.UserId is whitelisted.
4. Global Toggle: Returns false if Enabled is set to false.
5. Rollout Bounds: Returns true if RolloutPercent >= 100, or false if RolloutPercent <= 0.
6. Deterministic Hash: Uses stableHash(flagName, userId) to determine if the player falls within the rollout threshold (0-99).

Comparison: Owl Flags vs Standard Methods