TagAPI:UpdateLeaderboardTag

The TagAPI:UpdateLeaderboardTag method updates the dynamic text of an existing leaderboard tag without removing and re-giving it. This is useful for real-time updates to rankings, scores, or stats that change frequently.

Overview

Execution Context

Server

Script Type

Server Script

Returns

boolean, string

Side Effects

Updates dynamic text for equipped tag

Syntax

local success, message = TagAPI:UpdateLeaderboardTag(player: Player, tagId: string, newDynamicText: string)

Parameter	Type	Description
`player`	`Player`	The player instance whose leaderboard tag should be updated
`tagId`	`string`	The leaderboard tag identifier to update
`newDynamicText`	`string`	The new text to display in place of %s placeholder

Return Values

Return	Type	Description
`success`	`boolean`	True if tag was updated successfully, false otherwise
`message`	`string`	Descriptive message about the operation result

Basic Usage

Update a player's leaderboard tag text.

Lua

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local CCTFF = require(ReplicatedStorage:WaitForChild("CCTFF"))
local TagAPI = CCTFF.TagAPI

-- Update rank from #2 to #1
local success, message = TagAPI:UpdateLeaderboardTag(player, "TopCoins", "#1")
if success then
    print("Tag updated successfully")
else
    print("Error: " .. message)
end

Real-Time Rank Updates

Update rankings as player stats change.

Lua

local function updatePlayerRanking(player, newRank)
    if not TagAPI:HasTag(player, "TopCoins") then
        -- Give tag first time
        TagAPI:GiveLeaderboardTag(player, "TopCoins", "#" .. newRank)
        TagAPI:Equip(player, "TopCoins")
    else
        -- Update existing tag
        TagAPI:UpdateLeaderboardTag(player, "TopCoins", "#" .. newRank)
    end
end

player.leaderstats.Coins.Changed:Connect(function()
    local rank = calculatePlayerRank(player)
    updatePlayerRanking(player, rank)
end)

Live Score Counter

Update score display in real-time.

Lua

player.leaderstats.Score.Changed:Connect(function(newScore)
    if TagAPI:HasTag(player, "ScoreTag") then
        local scoreText = newScore .. " pts"
        TagAPI:UpdateLeaderboardTag(player, "ScoreTag", scoreText)
    end
end)

Timer Display

Show elapsed time or countdown timer.

Lua

local function startTimerDisplay(player)
    TagAPI:GiveLeaderboardTag(player, "Timer", "0:00")
    TagAPI:Equip(player, "Timer")
    
    local startTime = tick()
    
    while player.Parent do
        local elapsed = tick() - startTime
        local minutes = math.floor(elapsed / 60)
        local seconds = math.floor(elapsed % 60)
        
        local timeText = string.format("%d:%02d", minutes, seconds)
        TagAPI:UpdateLeaderboardTag(player, "Timer", timeText)
        
        task.wait(1)
    end
end

task.spawn(function()
    startTimerDisplay(player)
end)

Kill/Death Ratio

Update KD ratio dynamically.

Lua

local function updateKDRatio(player)
    local kills = player.leaderstats.Kills.Value
    local deaths = player.leaderstats.Deaths.Value
    
    local kd = deaths > 0 and (kills / deaths) or kills
    local kdText = string.format("%.2f KD", kd)
    
    if not TagAPI:HasTag(player, "KDRatio") then
        TagAPI:GiveLeaderboardTag(player, "KDRatio", kdText)
        TagAPI:Equip(player, "KDRatio")
    else
        TagAPI:UpdateLeaderboardTag(player, "KDRatio", kdText)
    end
end

player.leaderstats.Kills.Changed:Connect(function()
    updateKDRatio(player)
end)

player.leaderstats.Deaths.Changed:Connect(function()
    updateKDRatio(player)
end)

Win Rate Display

Show player's win percentage.

Lua

local function updateWinRate(player)
    local wins = player.leaderstats.Wins.Value
    local losses = player.leaderstats.Losses.Value
    local totalGames = wins + losses
    
    if totalGames > 0 then
        local winRate = (wins / totalGames) * 100
        local rateText = string.format("%.1f%%", winRate)
        
        if TagAPI:HasTag(player, "WinRate") then
            TagAPI:UpdateLeaderboardTag(player, "WinRate", rateText)
        else
            TagAPI:GiveLeaderboardTag(player, "WinRate", rateText)
            TagAPI:Equip(player, "WinRate")
        end
    end
end

player.leaderstats.Wins.Changed:Connect(function()
    updateWinRate(player)
end)

Level Progress

Update level tag as player progresses.

Lua

player.leaderstats.Level.Changed:Connect(function(newLevel)
    local levelText = "Lvl " .. newLevel
    
    if TagAPI:HasTag(player, "LevelTag") then
        TagAPI:UpdateLeaderboardTag(player, "LevelTag", levelText)
    else
        TagAPI:GiveLeaderboardTag(player, "LevelTag", levelText)
        
        if newLevel >= 50 then
            TagAPI:Equip(player, "LevelTag")
        end
    end
end)

Combo Counter

Display and update active combo count.

Lua

local playerCombos = {}

local function updateComboTag(player, comboCount)
    local comboText = comboCount .. "x Combo"
    
    if comboCount >= 5 then
        if not TagAPI:HasTag(player, "Combo") then
            TagAPI:GiveLeaderboardTag(player, "Combo", comboText)
            TagAPI:Equip(player, "Combo")
        else
            TagAPI:UpdateLeaderboardTag(player, "Combo", comboText)
        end
    elseif comboCount == 0 and TagAPI:HasTag(player, "Combo") then
        TagAPI:Remove(player, "Combo")
    end
end

-- Usage in combat system
local function onKill(player)
    playerCombos[player.UserId] = (playerCombos[player.UserId] or 0) + 1
    updateComboTag(player, playerCombos[player.UserId])
end

Distance Traveled

Track and display total distance moved.

Lua

local playerDistances = {}

local function updateDistanceTag(player, totalDistance)
    local distanceKm = totalDistance / 1000
    local distText = string.format("%.1f km", distanceKm)
    
    if TagAPI:HasTag(player, "Distance") then
        TagAPI:UpdateLeaderboardTag(player, "Distance", distText)
    else
        TagAPI:GiveLeaderboardTag(player, "Distance", distText)
        TagAPI:Equip(player, "Distance")
    end
end

-- Track distance in loop
game:GetService("RunService").Heartbeat:Connect(function(dt)
    for _, player in ipairs(game.Players:GetPlayers()) do
        local character = player.Character
        if character and character:FindFirstChild("HumanoidRootPart") then
            local hrp = character.HumanoidRootPart
            local distance = hrp.Velocity.Magnitude * dt
            
            playerDistances[player.UserId] = (playerDistances[player.UserId] or 0) + distance
            
            -- Update every 100 studs
            if playerDistances[player.UserId] % 100 < distance then
                updateDistanceTag(player, playerDistances[player.UserId])
            end
        end
    end
end)

Session Time Tracker

Show how long player has been in current session.

Lua

local sessionStartTimes = {}

game.Players.PlayerAdded:Connect(function(player)
    sessionStartTimes[player.UserId] = tick()
    
    TagAPI:GiveLeaderboardTag(player, "SessionTime", "0m")
    TagAPI:Equip(player, "SessionTime")
    
    task.spawn(function()
        while player.Parent do
            local elapsed = tick() - sessionStartTimes[player.UserId]
            local minutes = math.floor(elapsed / 60)
            
            local timeText = minutes .. "m"
            if minutes >= 60 then
                local hours = math.floor(minutes / 60)
                timeText = hours .. "h"
            end
            
            TagAPI:UpdateLeaderboardTag(player, "SessionTime", timeText)
            task.wait(60) -- Update every minute
        end
    end)
end)

Currency Balance

Live update of player currency.

Lua

local function formatCurrency(amount)
    if amount >= 1000000 then
        return string.format("$%.1fM", amount / 1000000)
    elseif amount >= 1000 then
        return string.format("$%.1fK", amount / 1000)
    else
        return "$" .. amount
    end
end

player.leaderstats.Coins.Changed:Connect(function(newAmount)
    local balanceText = formatCurrency(newAmount)
    
    if TagAPI:HasTag(player, "Balance") then
        TagAPI:UpdateLeaderboardTag(player, "Balance", balanceText)
    end
end)

Health Percentage

Show current health as percentage.

Lua

player.CharacterAdded:Connect(function(character)
    local humanoid = character:WaitForChild("Humanoid")
    
    TagAPI:GiveLeaderboardTag(player, "Health", "100%")
    TagAPI:Equip(player, "Health")
    
    humanoid.HealthChanged:Connect(function(health)
        local percent = math.floor((health / humanoid.MaxHealth) * 100)
        local healthText = percent .. "%"
        
        TagAPI:UpdateLeaderboardTag(player, "Health", healthText)
    end)
end)

Rank Change Notification

Notify player when rank changes.

Lua

local previousRanks = {}

local function updateRankWithNotification(player, newRank)
    local oldRank = previousRanks[player.UserId]
    
    if TagAPI:HasTag(player, "TopCoins") then
        TagAPI:UpdateLeaderboardTag(player, "TopCoins", "#" .. newRank)
        
        if oldRank and newRank < oldRank then
            -- Rank improved
            local notifyRemote = ReplicatedStorage.NotifyPlayer
            notifyRemote:FireClient(
                player,
                "Rank Up! You're now #" .. newRank
            )
        end
    end
    
    previousRanks[player.UserId] = newRank
end

updateRankWithNotification(player, 3)

Auto-Update Loop

Continuously update leaderboard tags.

Lua

local function startLeaderboardUpdates()
    while true do
        task.wait(30) -- Update every 30 seconds
        
        for _, player in ipairs(game.Players:GetPlayers()) do
            if TagAPI:HasTag(player, "TopCoins") then
                local rank = calculatePlayerRank(player)
                TagAPI:UpdateLeaderboardTag(player, "TopCoins", "#" .. rank)
            end
        end
        
        print("Leaderboard tags updated")
    end
end

task.spawn(startLeaderboardUpdates)

Conditional Updates

Only update when value exceeds threshold.

Lua

local lastUpdateValues = {}

local function conditionalUpdate(player, statName, threshold)
    local currentValue = player.leaderstats[statName].Value
    local lastValue = lastUpdateValues[player.UserId] or 0
    
    -- Only update if difference exceeds threshold
    if math.abs(currentValue - lastValue) >= threshold then
        local displayText = statName .. ": " .. currentValue
        
        if TagAPI:HasTag(player, "StatDisplay") then
            TagAPI:UpdateLeaderboardTag(player, "StatDisplay", displayText)
        end
        
        lastUpdateValues[player.UserId] = currentValue
    end
end

-- Update only when coins change by 100+
player.leaderstats.Coins.Changed:Connect(function()
    conditionalUpdate(player, "Coins", 100)
end)

Multi-Stat Display

Combine multiple stats in one tag.

Lua

local function updateMultiStatTag(player)
    local kills = player.leaderstats.Kills.Value
    local deaths = player.leaderstats.Deaths.Value
    local wins = player.leaderstats.Wins.Value
    
    local statsText = string.format("%dK/%dD/%dW", kills, deaths, wins)
    
    if TagAPI:HasTag(player, "Stats") then
        TagAPI:UpdateLeaderboardTag(player, "Stats", statsText)
    else
        TagAPI:GiveLeaderboardTag(player, "Stats", statsText)
        TagAPI:Equip(player, "Stats")
    end
end

-- Update on any stat change
for _, statName in ipairs({"Kills", "Deaths", "Wins"}) do
    player.leaderstats[statName].Changed:Connect(function()
        updateMultiStatTag(player)
    end)
end