TagAPI:GetLeaderboardTagText

The TagAPI:GetLeaderboardTagText method retrieves the current dynamic text for a player's leaderboard tag. Returns nil if the player doesn't have the specified leaderboard tag.

Overview

Execution Context

Server, Client

Script Type

Server Script, Local Script

Returns

string or nil

Side Effects

None - read-only operation

Syntax

local dynamicText = TagAPI:GetLeaderboardTagText(player: Player, tagId: string)

Parameter	Type	Description
`player`	`Player`	The player instance to query
`tagId`	`string`	The leaderboard tag identifier

Return Values

Return	Type	Description
`dynamicText`	`string` or `nil`	The dynamic text currently set for the leaderboard tag, or nil if not found

Basic Usage

Get the current text of a leaderboard tag.

Lua

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

local rankText = TagAPI:GetLeaderboardTagText(player, "TopCoins")
if rankText then
    print(player.Name .. "'s rank: " .. rankText)
else
    print("Player doesn't have TopCoins tag")
end

Display Current Rank

Show player's current rank to them.

Lua

local function showCurrentRank(player)
    local rankText = TagAPI:GetLeaderboardTagText(player, "TopCoins")
    
    if rankText then
        local message = "Your current rank: " .. rankText
        local notifyRemote = ReplicatedStorage.NotifyPlayer
        notifyRemote:FireClient(player, message)
    else
        local notifyRemote = ReplicatedStorage.NotifyPlayer
        notifyRemote:FireClient(player, "You are not ranked yet")
    end
end

showCurrentRank(player)

Compare Rankings

Compare leaderboard positions between two players.

Lua

local function compareRankings(player1, player2, tagId)
    local rank1 = TagAPI:GetLeaderboardTagText(player1, tagId)
    local rank2 = TagAPI:GetLeaderboardTagText(player2, tagId)
    
    if not rank1 and not rank2 then
        return "Neither player is ranked"
    elseif not rank1 then
        return player2.Name .. " is ranked: " .. rank2
    elseif not rank2 then
        return player1.Name .. " is ranked: " .. rank1
    else
        return player1.Name .. ": " .. rank1 .. " vs " .. 
               player2.Name .. ": " .. rank2
    end
end

local comparison = compareRankings(player1, player2, "TopCoins")
print(comparison)

Extract Numeric Rank

Parse numeric rank from tag text.

Lua

local function getNumericRank(player, tagId)
    local rankText = TagAPI:GetLeaderboardTagText(player, tagId)
    
    if not rankText then
        return nil
    end
    
    -- Extract number from text like "#5" or "Top 10"
    local number = rankText:match("%d+")
    return tonumber(number)
end

local rank = getNumericRank(player, "TopCoins")
if rank then
    print("Numeric rank: " .. rank)
    
    if rank <= 3 then
        print("Player is in top 3!")
    end
end

UI Display

Show leaderboard tag text in player's GUI.

Lua

-- LocalScript
local player = game.Players.LocalPlayer
local TagAPI = CCTFF.TagAPI
local rankLabel = script.Parent.RankLabel

local function updateRankDisplay()
    local rankText = TagAPI:GetLeaderboardTagText(player, "TopCoins")
    
    if rankText then
        rankLabel.Text = "🏆 " .. rankText
        rankLabel.TextColor3 = Color3.fromRGB(255, 215, 0)
        rankLabel.Visible = true
    else
        rankLabel.Visible = false
    end
end

-- Update every 5 seconds
while true do
    updateRankDisplay()
    task.wait(5)
end

Validation Check

Verify leaderboard tag text matches expected format.

Lua

local function validateRankFormat(player, tagId)
    local rankText = TagAPI:GetLeaderboardTagText(player, tagId)
    
    if not rankText then
        return false, "No rank text found"
    end
    
    -- Check if format is valid (e.g., "#1", "#10")
    if rankText:match("^#%d+$") then
        return true, "Valid rank format"
    else
        return false, "Invalid rank format: " .. rankText
    end
end

local isValid, message = validateRankFormat(player, "TopCoins")
print(message)

Achievement Tracking

Track when player reaches milestone ranks.

Lua

local previousRanks = {}

local function checkRankMilestones(player, tagId)
    local currentRank = getNumericRank(player, tagId)
    local previousRank = previousRanks[player.UserId]
    
    if currentRank and previousRank and currentRank < previousRank then
        -- Rank improved
        local milestones = {1, 5, 10, 25, 50, 100}
        
        for _, milestone in ipairs(milestones) do
            if currentRank <= milestone and previousRank > milestone then
                -- Reached milestone
                local achievementTag = "Top" .. milestone
                if not TagAPI:HasTag(player, achievementTag) then
                    TagAPI:Give(player, achievementTag)
                    print(player.Name .. " reached top " .. milestone .. "!")
                end
            end
        end
    end
    
    previousRanks[player.UserId] = currentRank
end

checkRankMilestones(player, "TopCoins")

Leaderboard Display

Build a leaderboard from tag texts.

Lua

local function buildLeaderboard(tagId)
    local leaderboard = {}
    
    for _, player in ipairs(game.Players:GetPlayers()) do
        local rankText = TagAPI:GetLeaderboardTagText(player, tagId)
        
        if rankText then
            table.insert(leaderboard, {
                Player = player,
                RankText = rankText,
                NumericRank = getNumericRank(player, tagId)
            })
        end
    end
    
    -- Sort by numeric rank
    table.sort(leaderboard, function(a, b)
        return (a.NumericRank or 999) < (b.NumericRank or 999)
    end)
    
    return leaderboard
end

local topPlayers = buildLeaderboard("TopCoins")
for i, entry in ipairs(topPlayers) do
    print(i .. ". " .. entry.Player.Name .. " - " .. entry.RankText)
end

Conditional Rewards

Award rewards based on rank text.

Lua

local function awardRankRewards(player, tagId)
    local rankText = TagAPI:GetLeaderboardTagText(player, tagId)
    
    if not rankText then
        return false, "No rank"
    end
    
    local rank = getNumericRank(player, tagId)
    local reward = 0
    
    if rank == 1 then
        reward = 10000
    elseif rank <= 3 then
        reward = 5000
    elseif rank <= 10 then
        reward = 2500
    elseif rank <= 50 then
        reward = 1000
    elseif rank <= 100 then
        reward = 500
    end
    
    if reward > 0 then
        player.leaderstats.Coins.Value += reward
        return true, "Awarded " .. reward .. " coins for rank " .. rankText
    end
    
    return false, "No reward for this rank"
end

local success, message = awardRankRewards(player, "TopCoins")
print(message)

Logging System

Log rank changes for analytics.

Lua

local rankHistory = {}

local function logRankChange(player, tagId)
    local currentRank = TagAPI:GetLeaderboardTagText(player, tagId)
    
    if not rankHistory[player.UserId] then
        rankHistory[player.UserId] = {}
    end
    
    table.insert(rankHistory[player.UserId], {
        TagId = tagId,
        Rank = currentRank,
        Timestamp = os.time()
    })
    
    -- Keep only last 100 entries
    if #rankHistory[player.UserId] > 100 then
        table.remove(rankHistory[player.UserId], 1)
    end
end

-- Log rank every hour
while true do
    for _, player in ipairs(game.Players:GetPlayers()) do
        logRankChange(player, "TopCoins")
    end
    task.wait(3600) -- 1 hour
end

Multi-Tag Status

Check status across multiple leaderboard tags.

Lua

local function getPlayerLeaderboardStatus(player)
    local leaderboardTags = {"TopCoins", "TopKills", "TopWins"}
    local status = {}
    
    for _, tagId in ipairs(leaderboardTags) do
        local rankText = TagAPI:GetLeaderboardTagText(player, tagId)
        status[tagId] = rankText or "Not Ranked"
    end
    
    return status
end

local status = getPlayerLeaderboardStatus(player)
for tagId, rank in pairs(status) do
    print(tagId .. ": " .. rank)
end

Admin Inspection

Admin command to view player's leaderboard tags.

Lua

local function inspectLeaderboardCommand(admin, args)
    local targetName = args[1]
    if not targetName then
        return false, "Usage: !inspectlb [player]"
    end
    
    local targetPlayer = game.Players:FindFirstChild(targetName)
    if not targetPlayer then
        return false, "Player not found"
    end
    
    local message = targetPlayer.Name .. "'s Leaderboard Tags:\n"
    local foundAny = false
    
    -- Check all leaderboard tags in config
    for tagId, _ in pairs(Config.LeaderboardTags) do
        local rankText = TagAPI:GetLeaderboardTagText(targetPlayer, tagId)
        if rankText then
            message = message .. "• " .. tagId .. ": " .. rankText .. "\n"
            foundAny = true
        end
    end
    
    if not foundAny then
        message = message .. "No leaderboard tags"
    end
    
    return true, message
end

adminCommands["inspectlb"] = inspectLeaderboardCommand

Threshold Alerts

Alert when player reaches specific rank thresholds.

Lua

local alertedPlayers = {}

local function checkRankAlerts(player, tagId)
    local rankText = TagAPI:GetLeaderboardTagText(player, tagId)
    
    if not rankText then
        return
    end
    
    local rank = getNumericRank(player, tagId)
    local thresholds = {1, 5, 10, 25, 50, 100}
    
    for _, threshold in ipairs(thresholds) do
        if rank <= threshold then
            local key = player.UserId .. "_" .. tagId .. "_" .. threshold
            
            if not alertedPlayers[key] then
                alertedPlayers[key] = true
                
                local notifyRemote = ReplicatedStorage.NotifyPlayer
                notifyRemote:FireClient(
                    player,
                    "🎉 You've reached Top " .. threshold .. " in " .. tagId .. "!"
                )
            end
            
            break -- Only alert for highest threshold reached
        end
    end
end

checkRankAlerts(player, "TopCoins")

Export to JSON

Export leaderboard tag data for external use.

Lua

local HttpService = game:GetService("HttpService")

local function exportLeaderboardData(tagId)
    local data = {}
    
    for _, player in ipairs(game.Players:GetPlayers()) do
        local rankText = TagAPI:GetLeaderboardTagText(player, tagId)
        
        if rankText then
            table.insert(data, {
                UserId = player.UserId,
                Username = player.Name,
                Rank = rankText,
                NumericRank = getNumericRank(player, tagId),
                Timestamp = os.time()
            })
        end
    end
    
    -- Sort by numeric rank
    table.sort(data, function(a, b)
        return (a.NumericRank or 999) < (b.NumericRank or 999)
    end)
    
    local json = HttpService:JSONEncode(data)
    return json
end

local jsonData = exportLeaderboardData("TopCoins")
print(jsonData)

Cache Management

Cache leaderboard tag texts for performance.

Lua

local tagTextCache = {}
local CACHE_DURATION = 30 -- seconds

local function getCachedLeaderboardTagText(player, tagId)
    local cacheKey = player.UserId .. "_" .. tagId
    local cached = tagTextCache[cacheKey]
    
    if cached and (os.time() - cached.timestamp) < CACHE_DURATION then
        return cached.text
    end
    
    -- Fetch fresh data
    local text = TagAPI:GetLeaderboardTagText(player, tagId)
    
    tagTextCache[cacheKey] = {
        text = text,
        timestamp = os.time()
    }
    
    return text
end

-- Use cached version for frequent calls
local rankText = getCachedLeaderboardTagText(player, "TopCoins")
print("Cached rank: " .. tostring(rankText))