TagAPI:GiveLeaderboardTag

The TagAPI:GiveLeaderboardTag method assigns a special leaderboard tag to a player with dynamic text that updates based on player stats or rankings. Unlike regular tags, leaderboard tags support dynamic text replacement (using %s placeholder) that can be updated without re-giving the tag.

Overview

Execution Context

Server

Script Type

Server Script

Returns

boolean, string

Side Effects

Gives tag to player with dynamic text

Syntax

local success, message = TagAPI:GiveLeaderboardTag(player: Player, tagId: string, dynamicText: string)

Parameter	Type	Description
`player`	`Player`	The player instance who should receive the leaderboard tag
`tagId`	`string`	The leaderboard tag identifier (must be defined in Config.LeaderboardTags)
`dynamicText`	`string`	The text to replace the %s placeholder in the tag (e.g., "#1", "Top 10")

Return Values

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

Basic Usage

Give a leaderboard tag with rank text.

Lua

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

-- Give "TopCoins" tag with "#1" rank displayed
local success, message = TagAPI:GiveLeaderboardTag(player, "TopCoins", "#1")
if success then
    print("Leaderboard tag given: " .. message)
else
    print("Error: " .. message)
end

Ranking System

Award leaderboard tags based on player rankings.

Lua

local function updatePlayerRank(player, rank)
    local rankText = "#" .. rank
    
    if rank == 1 then
        TagAPI:GiveLeaderboardTag(player, "TopCoins", rankText)
        TagAPI:Equip(player, "TopCoins")
    elseif rank <= 10 then
        TagAPI:GiveLeaderboardTag(player, "TopCoins", "Top " .. rank)
        TagAPI:Equip(player, "TopCoins")
    elseif rank <= 100 then
        TagAPI:GiveLeaderboardTag(player, "TopCoins", "Top 100")
    end
end

-- Usage
updatePlayerRank(player, 1) -- Gives "TopCoins #1"
updatePlayerRank(player, 5) -- Gives "TopCoins Top 5"

Multiple Stat Leaderboards

Track multiple leaderboard stats with different tags.

Lua

local function updateLeaderboardTags(player, coinsRank, killsRank, winsRank)
    -- Coins leaderboard
    if coinsRank <= 10 then
        TagAPI:GiveLeaderboardTag(player, "TopCoins", "#" .. coinsRank)
    end
    
    -- Kills leaderboard
    if killsRank <= 10 then
        TagAPI:GiveLeaderboardTag(player, "TopKills", "#" .. killsRank)
    end
    
    -- Wins leaderboard
    if winsRank <= 10 then
        TagAPI:GiveLeaderboardTag(player, "TopWins", "#" .. winsRank)
    end
end

updateLeaderboardTags(player, 1, 5, 3)

Percentage Display

Show player's percentile ranking.

Lua

local function givePercentileTag(player, percentile)
    local displayText = "Top " .. percentile .. "%"
    
    TagAPI:GiveLeaderboardTag(player, "TopPlayers", displayText)
    TagAPI:Equip(player, "TopPlayers")
    
    print(player.Name .. " is in the " .. displayText)
end

-- Player in top 5%
givePercentileTag(player, 5)

Seasonal Leaderboards

Award seasonal ranking tags with season identifier.

Lua

local CURRENT_SEASON = "S3"

local function awardSeasonRank(player, rank)
    local rankText = CURRENT_SEASON .. " #" .. rank
    
    TagAPI:GiveLeaderboardTag(player, "SeasonRank", rankText)
    TagAPI:Equip(player, "SeasonRank")
    
    print("Awarded " .. rankText .. " to " .. player.Name)
end

-- Season 3 rank #1
awardSeasonRank(player, 1)

Level-Based Tags

Display player level in leaderboard tag.

Lua

local function updateLevelTag(player, level)
    local levelText = "Lvl " .. level
    
    TagAPI:GiveLeaderboardTag(player, "LevelTag", levelText)
    
    -- Auto-equip for high levels
    if level >= 100 then
        TagAPI:Equip(player, "LevelTag")
    end
end

player.leaderstats.Level.Changed:Connect(function(newLevel)
    updateLevelTag(player, newLevel)
end)

Score Threshold Display

Show achievement threshold reached.

Lua

local SCORE_TIERS = {
    {threshold = 100000, text = "100K Club"},
    {threshold = 50000, text = "50K Club"},
    {threshold = 10000, text = "10K Club"}
}

local function checkScoreTiers(player, score)
    for _, tier in ipairs(SCORE_TIERS) do
        if score >= tier.threshold then
            TagAPI:GiveLeaderboardTag(player, "ScoreClub", tier.text)
            TagAPI:Equip(player, "ScoreClub")
            break
        end
    end
end

player.leaderstats.Score.Changed:Connect(function(newScore)
    checkScoreTiers(player, newScore)
end)

Competitive Tier System

Display competitive rank tier.

Lua

local RANK_TIERS = {
    {minElo = 2000, name = "Grandmaster"},
    {minElo = 1800, name = "Master"},
    {minElo = 1600, name = "Diamond"},
    {minElo = 1400, name = "Platinum"},
    {minElo = 1200, name = "Gold"},
    {minElo = 1000, name = "Silver"},
    {minElo = 0, name = "Bronze"}
}

local function updateRankTier(player, elo)
    for _, tier in ipairs(RANK_TIERS) do
        if elo >= tier.minElo then
            TagAPI:GiveLeaderboardTag(player, "RankTier", tier.name)
            TagAPI:Equip(player, "RankTier")
            break
        end
    end
end

updateRankTier(player, 1850) -- Gives "Master" tier

Daily Leaderboard Reset

Reset and update daily leaderboard tags.

Lua

local function resetDailyLeaderboard()
    for _, player in ipairs(game.Players:GetPlayers()) do
        -- Remove old daily tag
        if TagAPI:HasTag(player, "DailyTop") then
            TagAPI:Remove(player, "DailyTop")
        end
    end
end

local function updateDailyRankings()
    local sortedPlayers = {} -- Sort by daily points
    
    for i, player in ipairs(sortedPlayers) do
        if i <= 3 then
            local suffix = {"st", "nd", "rd"}
            local rankText = i .. (suffix[i] or "th")
            TagAPI:GiveLeaderboardTag(player, "DailyTop", rankText)
            TagAPI:Equip(player, "DailyTop")
        end
    end
end

-- Reset at midnight
resetDailyLeaderboard()
updateDailyRankings()

Streak Counter

Display win/login streak in tag.

Lua

local function updateStreakTag(player, streakCount)
    local streakText = streakCount .. " Day"
    if streakCount ~= 1 then
        streakText = streakText .. "s"
    end
    
    TagAPI:GiveLeaderboardTag(player, "LoginStreak", streakText)
    
    -- Auto-equip for milestones
    if streakCount >= 7 or streakCount >= 30 or streakCount >= 100 then
        TagAPI:Equip(player, "LoginStreak")
    end
end

updateStreakTag(player, 15) -- "15 Days"

Guild/Team Ranking

Show guild rank within organization.

Lua

local function updateGuildRank(player, guildName, rank)
    local rankText = guildName .. " #" .. rank
    
    TagAPI:GiveLeaderboardTag(player, "GuildRank", rankText)
    TagAPI:Equip(player, "GuildRank")
end

updateGuildRank(player, "Dragons", 3) -- "Dragons #3"

Time-Limited Event Rank

Award event-specific ranking tags.

Lua

local function awardEventRank(player, eventName, placement)
    local rankText = eventName .. " #" .. placement
    
    TagAPI:GiveLeaderboardTag(player, "EventRank", rankText)
    
    -- Auto-equip top 3
    if placement <= 3 then
        TagAPI:Equip(player, "EventRank")
    end
    
    print(player.Name .. " placed " .. placement .. " in " .. eventName)
end

awardEventRank(player, "Summer2025", 1)

Achievement Point Display

Show total achievement points earned.

Lua

local function updateAchievementTag(player, totalPoints)
    local pointsText = totalPoints .. "pts"
    
    TagAPI:GiveLeaderboardTag(player, "AchievementPoints", pointsText)
    
    -- Equip at milestones
    if totalPoints >= 1000 then
        TagAPI:Equip(player, "AchievementPoints")
    end
end

player.leaderstats.AchievementPoints.Changed:Connect(function(points)
    updateAchievementTag(player, points)
end)

Power Level/Rating

Display combat power or rating number.

Lua

local function updatePowerLevel(player, powerLevel)
    local powerText = "⚡" .. powerLevel
    
    TagAPI:GiveLeaderboardTag(player, "PowerLevel", powerText)
    
    -- Equip for high power players
    if powerLevel >= 9000 then
        TagAPI:Equip(player, "PowerLevel")
        print("IT'S OVER 9000!")
    end
end

updatePowerLevel(player, 9500)

Wealth Display

Show total wealth with formatted numbers.

Lua

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

local function updateWealthTag(player, coins)
    local wealthText = "$" .. formatNumber(coins)
    
    TagAPI:GiveLeaderboardTag(player, "Wealth", wealthText)
    
    if coins >= 1000000 then
        TagAPI:Equip(player, "Wealth")
    end
end

updateWealthTag(player, 2500000) -- "$2.5M"

Prestige Level

Display prestige level achieved.

Lua

local function updatePrestigeTag(player, prestigeLevel)
    local prestigeText = "P" .. prestigeLevel
    
    TagAPI:GiveLeaderboardTag(player, "Prestige", prestigeText)
    TagAPI:Equip(player, "Prestige")
    
    print(player.Name .. " reached Prestige " .. prestigeLevel)
end

updatePrestigeTag(player, 10) -- "P10"