CLFF API Reference

All CLFF API methods live on G.CLFF and must be called from server scripts only. The API provides secure stat updates with built-in validation, type checking, and rate limiting.

API

CLFF:Update

Set a stat to a specific value with validation.

Jump to method & use cases

CLFF:Get

Read the current value of a stat.

Jump to method & use cases

CLFF:Increment

Add or subtract from a numeric stat.

Jump to method & use cases

CLFF:Set

Alias for Update for clearer intent.

Jump to method & use cases

CLFF:SetDebugMode

Toggle internal debug logging.

Jump to method & use cases

CLFF:SetSortingStat

Choose which stat drives sort order.

Jump to method & use cases

CLFF:Update

The CLFF:Update method sets a stat to a specific value with full server-side validation and throttling.

Method Details

Syntax

local success = G.CLFF:Update(player: Player, statName: string, newValue: number)

Parameter	Type	Description
`player`	Player	Player whose stat should be updated.
`statName`	string	Stat name defined in CLFFConfig.Stats e.g. "Coins".
`newValue`	number	New value to assign to the stat.

Use Cases

1. Basic set with checks

Set the player's coins and handle failure cases cleanly.

Lua

local success = G.CLFF:Update(player, "Coins", 10000)
if success then
    print("Coins updated successfully")
else
    warn("Failed to update coins")
end

2. Load from DataStore

Apply saved values to CLFF stats when the player joins.

Lua

local DataStoreService = game:GetService("DataStoreService")
local PlayerData = DataStoreService:GetDataStore("PlayerData")

game.Players.PlayerAdded:Connect(function(player)
    local ok, data = pcall(function()
        return PlayerData:GetAsync(player.UserId)
    end)
    
    if ok and data then
        G.CLFF:Update(player, "Coins", data.Coins or 0)
        G.CLFF:Update(player, "Kills", data.Kills or 0)
        G.CLFF:Update(player, "Level", data.Level or 1)
    end
end)

3. Purchase handler

Deduct coins when the player buys an item.

Lua

local function handlePurchase(player, itemName, price)
    local coins = G.CLFF:Get(player, "Coins")
    if not coins or coins < price then
        return false, "Not enough coins"
    end
    
    local ok = G.CLFF:Update(player, "Coins", coins - price)
    if not ok then
        return false, "Failed to update balance"
    end
    
    giveItem(player, itemName)
    return true, "Purchase successful"
end

CLFF:Get

The CLFF:Get method returns the current numeric value of a stat, or nil if it doesn't exist.

Method Details

Syntax

local value = G.CLFF:Get(player: Player, statName: string)

Use Cases

1. Show current balance

Read and print the player's coin balance.

Lua

local coins = G.CLFF:Get(player, "Coins")
if coins then
    print(player.Name .. " has " .. coins .. " coins")
else
    warn("Could not read coins for " .. player.Name)
end

2. Gate area by level

Deny access to an area if the player is under a required level.

Lua

local REQUIRED_LEVEL = 10

local function canEnterArea(player)
    local level = G.CLFF:Get(player, "Level")
    if level and level >= REQUIRED_LEVEL then
        return true
    else
        return false, "You need level " .. REQUIRED_LEVEL .. " to enter"
    end
end

CLFF:Increment

The CLFF:Increment method adjusts a numeric stat by a delta. Use negative values to subtract.

Method Details

Syntax

local success = G.CLFF:Increment(player: Player, statName: string, amount: number)

Use Cases

1. Reward for kills

Give coins and increment kills when the player defeats an enemy.

Lua

-- Player defeats an enemy
G.CLFF:Increment(player, "Coins", 100)
G.CLFF:Increment(player, "Kills", 1)

2. Death penalty

Subtract 10% of the player's coins when they die.

Lua

local function applyDeathPenalty(player)
    local coins = G.CLFF:Get(player, "Coins") or 0
    local penalty = math.floor(coins * 0.1)
    G.CLFF:Increment(player, "Coins", -penalty)
end

CLFF:Set

CLFF:Set is a convenience alias for CLFF:Update, useful when you want code to read like setting a stat.

Method Details

Syntax

local success = G.CLFF:Set(player: Player, statName: string, value: number)

Use Cases

1. Reset player stats

Restore all stats back to their default values.

Lua

local function resetStats(player)
  G.CLFF:Set(player, "Coins", 0)
  G.CLFF:Set(player, "Kills", 0)
  G.CLFF:Set(player, "Deaths", 0)
  G.CLFF:Set(player, "Level", 1)
end

2. Admin override

Allow admins to set exact values for debugging or support.

Lua

local function adminSetStat(admin, target, statName, value)
  if not isAdmin(admin) then return false, "No permission" end
  local ok = G.CLFF:Set(target, statName, value)
  if ok then
    return true, "Set " .. statName .. " to " .. value
  else
    return false, "Failed to set stat"
  end
end

CLFF:SetDebugMode

CLFF:SetDebugMode toggles CLFF's internal logging for debugging purposes.

Method Details

Syntax

G.CLFF:SetDebugMode(enabled: boolean)

Use Cases

1. Enable in Studio only

Toggle verbose logging while testing locally in Studio.

Lua

local RunService = game:GetService("RunService")

if RunService:IsStudio() then
  G.CLFF:SetDebugMode(true)
else
  G.CLFF:SetDebugMode(false)
end

CLFF:SetSortingStat

CLFF:SetSortingStat selects which stat CLFF uses to sort players in the leaderboard UI.

Method Details

Syntax

local success = G.CLFF:SetSortingStat(statName: string)

Use Cases

1. Sort by kills

Switch sort order from coins to kills.

Lua

local ok = G.CLFF:SetSortingStat("Kills")
if ok then
  print("Now sorting by Kills")
end

2. Event-specific sorting

Sort by different stats during limited-time events.

Lua

local function startCoinsEvent()
  G.CLFF:SetSortingStat("Coins")
end

local function startWinsEvent()
  G.CLFF:SetSortingStat("Wins")
end