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
Serverboolean, stringSyntax
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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)