TagAPI:RemoveLeaderboardTag

The TagAPI:RemoveLeaderboardTag method removes a leaderboard tag from a player, clearing both ownership and any associated dynamic text. This is useful when players fall off leaderboards or when resetting rankings.

Overview

Execution Context
Server
Script Type
Server Script
Returns
boolean, string
Side Effects
Removes leaderboard tag and dynamic text

Syntax

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

Parameter Type Description
player Player The player instance whose leaderboard tag should be removed
tagId string The leaderboard tag identifier to remove

Return Values

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

Basic Usage

Remove a leaderboard tag from a player.

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

local success, message = TagAPI:RemoveLeaderboardTag(player, "TopCoins")
if success then
    print("Leaderboard tag removed")
else
    print("Error: " .. message)
end

Rank Demotion

Remove leaderboard tag when player drops below threshold.

Lua
local function checkRankEligibility(player, currentRank)
    -- Remove tag if player falls below top 10
    if currentRank > 10 and TagAPI:HasTag(player, "TopCoins") then
        TagAPI:RemoveLeaderboardTag(player, "TopCoins")
        print(player.Name .. " removed from top 10")
    end
end

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

Season End Cleanup

Remove all seasonal leaderboard tags at season end.

Lua
local function endSeasonLeaderboards()
    for _, player in ipairs(game.Players:GetPlayers()) do
        if TagAPI:HasTag(player, "SeasonRank") then
            TagAPI:RemoveLeaderboardTag(player, "SeasonRank")
        end
    end
    
    print("All seasonal leaderboard tags cleared")
end

-- Call at season end
endSeasonLeaderboards()

Daily Reset

Clear daily leaderboard tags at midnight.

Lua
local function resetDailyLeaderboards()
    for _, player in ipairs(game.Players:GetPlayers()) do
        -- Remove all daily tags
        local dailyTags = {"DailyTop", "DailyKills", "DailyWins"}
        
        for _, tagId in ipairs(dailyTags) do
            if TagAPI:HasTag(player, tagId) then
                TagAPI:RemoveLeaderboardTag(player, tagId)
            end
        end
    end
    
    print("Daily leaderboard tags reset")
end

-- Schedule for midnight
local function scheduleReset()
    local now = os.date("*t")
    local secondsUntilMidnight = (24 - now.hour) * 3600 - now.min * 60 - now.sec
    
    task.wait(secondsUntilMidnight)
    resetDailyLeaderboards()
    
    -- Repeat daily
    while true do
        task.wait(86400) -- 24 hours
        resetDailyLeaderboards()
    end
end

task.spawn(scheduleReset)

Tier Demotion

Remove tier tag when player loses rank.

Lua
local function updatePlayerTier(player, newElo)
    local oldTier = nil
    
    -- Find current tier tag
    local tierTags = {"Grandmaster", "Master", "Diamond", "Platinum"}
    for _, tier in ipairs(tierTags) do
        if TagAPI:HasTag(player, tier) then
            oldTier = tier
            break
        end
    end
    
    -- Calculate new tier
    local newTier = calculateTierFromElo(newElo)
    
    -- Remove old tier if different
    if oldTier and oldTier ~= newTier then
        TagAPI:RemoveLeaderboardTag(player, oldTier)
        print(player.Name .. " demoted from " .. oldTier)
    end
    
    -- Give new tier
    if newTier then
        TagAPI:GiveLeaderboardTag(player, newTier, newElo .. " ELO")
    end
end

updatePlayerTier(player, 1750)

Punishment System

Remove achievement tags as penalty.

Lua
local function punishPlayer(player, reason)
    -- Remove all achievement leaderboard tags
    local achievementTags = {
        "TopCoins", "TopKills", "TopWins", 
        "HighScore", "Champion"
    }
    
    for _, tagId in ipairs(achievementTags) do
        if TagAPI:HasTag(player, tagId) then
            TagAPI:RemoveLeaderboardTag(player, tagId)
        end
    end
    
    print("Removed achievement tags from " .. player.Name .. " - Reason: " .. reason)
end

punishPlayer(player, "Cheating detected")

Event Participation End

Remove event leaderboard tags when event ends.

Lua
local function endEvent(eventTagId)
    for _, player in ipairs(game.Players:GetPlayers()) do
        if TagAPI:HasTag(player, eventTagId) then
            TagAPI:RemoveLeaderboardTag(player, eventTagId)
        end
    end
    
    print("Event " .. eventTagId .. " ended - tags removed")
end

-- End summer event
endEvent("SummerEvent2025")

Streak Broken

Remove streak tag when player breaks their streak.

Lua
local function checkLoginStreak(player, lastLoginTime)
    local hoursSinceLogin = (os.time() - lastLoginTime) / 3600
    
    -- If more than 24 hours, streak is broken
    if hoursSinceLogin > 24 then
        if TagAPI:HasTag(player, "LoginStreak") then
            TagAPI:RemoveLeaderboardTag(player, "LoginStreak")
            print(player.Name .. "'s login streak was broken")
            
            -- Notify player
            local notifyRemote = ReplicatedStorage.NotifyPlayer
            notifyRemote:FireClient(player, "Your login streak was broken!")
        end
    end
end

game.Players.PlayerAdded:Connect(function(player)
    local lastLogin = getLastLoginTime(player)
    checkLoginStreak(player, lastLogin)
end)

Guild Removal

Remove guild rank tag when player leaves guild.

Lua
local function onPlayerLeaveGuild(player, guildName)
    -- Remove guild rank tag
    if TagAPI:HasTag(player, "GuildRank") then
        TagAPI:RemoveLeaderboardTag(player, "GuildRank")
        print(player.Name .. " left " .. guildName .. " - rank tag removed")
    end
    
    -- Remove guild-specific achievement tags
    local guildTags = {"GuildChampion", "GuildOfficer", "GuildFounder"}
    for _, tagId in ipairs(guildTags) do
        if TagAPI:HasTag(player, tagId) then
            TagAPI:RemoveLeaderboardTag(player, tagId)
        end
    end
end

onPlayerLeaveGuild(player, "Dragons")

Conditional Removal

Remove tag only if specific conditions are met.

Lua
local function conditionalRemove(player, tagId, condition)
    if not TagAPI:HasTag(player, tagId) then
        return false, "Player doesn't have this tag"
    end
    
    if condition then
        local success, message = TagAPI:RemoveLeaderboardTag(player, tagId)
        return success, message
    else
        return false, "Condition not met for removal"
    end
end

-- Only remove if player has less than 1000 coins
local belowThreshold = player.leaderstats.Coins.Value < 1000
conditionalRemove(player, "TopCoins", belowThreshold)

Admin Command

Admin command to remove leaderboard tags.

Lua
local function removeLbTagCommand(admin, args)
    local targetName = args[1]
    local tagId = args[2]
    
    if not targetName or not tagId then
        return false, "Usage: !removelbtag [player] [tagId]"
    end
    
    local targetPlayer = game.Players:FindFirstChild(targetName)
    if not targetPlayer then
        return false, "Player not found"
    end
    
    local success, message = TagAPI:RemoveLeaderboardTag(targetPlayer, tagId)
    
    if success then
        return true, "Removed " .. tagId .. " from " .. targetPlayer.Name
    else
        return false, message
    end
end

adminCommands["removelbtag"] = removeLbTagCommand

Batch Removal

Remove multiple leaderboard tags at once.

Lua
local function removeMultipleLeaderboardTags(player, tagList)
    local removedCount = 0
    local failedTags = {}
    
    for _, tagId in ipairs(tagList) do
        local success = TagAPI:RemoveLeaderboardTag(player, tagId)
        
        if success then
            removedCount = removedCount + 1
        else
            table.insert(failedTags, tagId)
        end
    end
    
    return removedCount, failedTags
end

local tagsToRemove = {"TopCoins", "TopKills", "TopWins"}
local removed, failed = removeMultipleLeaderboardTags(player, tagsToRemove)

print("Removed " .. removed .. " tags")
if #failed > 0 then
    print("Failed to remove: " .. table.concat(failed, ", "))
end

Notification on Removal

Notify player when their leaderboard tag is removed.

Lua
local function removeWithNotification(player, tagId, reason)
    local success, message = TagAPI:RemoveLeaderboardTag(player, tagId)
    
    if success then
        local notifyRemote = ReplicatedStorage.NotifyPlayer
        local notifMessage = "Your " .. tagId .. " tag was removed"
        
        if reason then
            notifMessage = notifMessage .. " - " .. reason
        end
        
        notifyRemote:FireClient(player, notifMessage)
        print("Removed " .. tagId .. " from " .. player.Name)
    end
    
    return success, message
end

removeWithNotification(player, "TopCoins", "Fell below top 10")

Reset All Leaderboards

Remove all leaderboard tags from all players.

Lua
local function resetAllLeaderboards()
    local leaderboardTags = {}
    
    -- Get all leaderboard tag IDs from config
    for tagId, config in pairs(Config.LeaderboardTags) do
        if config.Enabled then
            table.insert(leaderboardTags, tagId)
        end
    end
    
    -- Remove from all players
    for _, player in ipairs(game.Players:GetPlayers()) do
        for _, tagId in ipairs(leaderboardTags) do
            if TagAPI:HasTag(player, tagId) then
                TagAPI:RemoveLeaderboardTag(player, tagId)
            end
        end
    end
    
    print("Reset all leaderboards - removed tags from all players")
end

-- Call for full reset
resetAllLeaderboards()

Expire Old Rankings

Remove outdated leaderboard tags based on timestamp.

Lua
local leaderboardTimestamps = {}

local function giveTimestampedLeaderboardTag(player, tagId, dynamicText)
    TagAPI:GiveLeaderboardTag(player, tagId, dynamicText)
    leaderboardTimestamps[player.UserId] = leaderboardTimestamps[player.UserId] or {}
    leaderboardTimestamps[player.UserId][tagId] = os.time()
end

local function expireOldLeaderboardTags(maxAgeSeconds)
    local currentTime = os.time()
    
    for _, player in ipairs(game.Players:GetPlayers()) do
        local userTimestamps = leaderboardTimestamps[player.UserId]
        
        if userTimestamps then
            for tagId, timestamp in pairs(userTimestamps) do
                local age = currentTime - timestamp
                
                if age > maxAgeSeconds then
                    TagAPI:RemoveLeaderboardTag(player, tagId)
                    userTimestamps[tagId] = nil
                    print("Expired " .. tagId .. " for " .. player.Name)
                end
            end
        end
    end
end

-- Remove tags older than 7 days
expireOldLeaderboardTags(7 * 24 * 60 * 60)