TagAPI:Unequip

The TagAPI:Unequip method unequips a currently equipped tag from a player, removing it from chat display while preserving ownership. This method is server-side only and requires the CCTFF framework to be properly initialized. Players retain the tag in their inventory and can re-equip it later.

Overview

Server/Client

Server-side only

Script Types

Script, ModuleScript

Returns

boolean, string

What It Does

Unequips a tag from chat display. Player still owns the tag and can re-equip it later.

Syntax

lua

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

Parameters

Parameter	Type	Description
`player`	`Player`	The player instance who should unequip the tag
`tagId`	`string`	The tag identifier to unequip (must be currently equipped)

Return Values

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

Basic Usage

Unequip a single tag from a player.

lua

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

local success, msg = TagAPI:Unequip(player, "VIP")
if success then
    print("Tag unequipped successfully!")
else
    warn("Failed to unequip tag: " .. msg)
end

Unequip Multiple Tags

Unequip several tags at once.

lua

local tagsToUnequip = {"Developer", "Tester", "VIP"}

for _, tagId in ipairs(tagsToUnequip) do
    local success, msg = TagAPI:Unequip(player, tagId)
    
    if success then
        print("Unequipped: " .. tagId)
    else
        warn("Could not unequip " .. tagId .. ": " .. msg)
    end
end

Check Before Unequipping

Verify tag is equipped before attempting to unequip.

lua

local function safeUnequip(player, tagId)
    -- Check if tag is equipped
    if not TagAPI:IsEquipped(player, tagId) then
        return false, "Tag is not equipped"
    end
    
    -- Unequip the tag
    return TagAPI:Unequip(player, tagId)
end

local success, msg = safeUnequip(player, "Champion")
print(success, msg)

Unequip All Tags

Remove all equipped tags from a player at once.

lua

local success, msg = TagAPI:UnequipAll(player)

if success then
    print("All tags unequipped for " .. player.Name)
else
    warn("Failed to unequip all: " .. msg)
end

Swap Tags

Unequip one tag and equip another in its place.

lua

local function swapTags(player, oldTag, newTag)
    -- Unequip old tag
    local unequipSuccess = TagAPI:Unequip(player, oldTag)
    
    if not unequipSuccess then
        return false, "Failed to unequip " .. oldTag
    end
    
    -- Equip new tag
    local equipSuccess, msg = TagAPI:Equip(player, newTag)
    
    if not equipSuccess then
        -- Re-equip old tag if new one fails
        TagAPI:Equip(player, oldTag)
        return false, "Failed to equip " .. newTag
    end
    
    return true, "Swapped tags successfully"
end

swapTags(player, "Newcomer", "Veteran")

Make Room for Priority Tag

Unequip lowest priority tag to make room for a higher priority one.

lua

local function makeRoomForTag(player, tagId)
    local available = TagAPI:GetAvailableSlots(player)
    
    -- If no slots available, unequip lowest priority tag
    if available <= 0 then
        local equipped = TagAPI:GetEquipped(player)
        
        -- Last tag has lowest priority due to sorting
        local lowestPriority = equipped[#equipped]
        
        if lowestPriority then
            local success = TagAPI:Unequip(player, lowestPriority)
            
            if success then
                print("Unequipped " .. lowestPriority .. " to make room")
                return true
            end
        end
        
        return false
    end
    
    return true
end

-- Make room then equip
if makeRoomForTag(player, "Champion") then
    TagAPI:Equip(player, "Champion")
end

Command System Integration

Allow players to unequip tags via commands.

lua

local function unequipCommand(player, args)
    local tagId = args[1]
    
    if not tagId then
        return false, "Usage: !unequip [tagId]"
    end
    
    local success, msg = TagAPI:Unequip(player, tagId)
    
    if success then
        return true, "Unequipped tag: " .. tagId
    else
        return false, "Failed: " .. msg
    end
end

-- Register command
commands["unequip"] = unequipCommand

UI Selection System

Unequip tags based on player selection from a GUI.

lua

local unequipRemote = ReplicatedStorage:WaitForChild("UnequipTagRemote")

unequipRemote.OnServerEvent:Connect(function(player, tagId)
    -- Validate input
    if type(tagId) ~= "string" then
        return
    end
    
    -- Check if equipped
    if not TagAPI:IsEquipped(player, tagId) then
        unequipRemote:FireClient(player, "error", "Tag not equipped")
        return
    end
    
    -- Unequip the tag
    local success, msg = TagAPI:Unequip(player, tagId)
    
    -- Send feedback to client
    if success then
        unequipRemote:FireClient(player, "success", "Unequipped: " .. tagId)
    else
        unequipRemote:FireClient(player, "error", msg)
    end
end)

Temporary Unequip

Unequip a tag temporarily and re-equip after duration.

lua

local function temporaryUnequip(player, tagId, duration)
    -- Unequip the tag
    local success = TagAPI:Unequip(player, tagId)
    
    if not success then
        return false
    end
    
    -- Wait for duration
    task.wait(duration)
    
    -- Re-equip if player still in game
    if player and player.Parent then
        TagAPI:Equip(player, tagId)
    end
    
    return true
end

-- Unequip for 60 seconds
temporaryUnequip(player, "VIP", 60)

Event-Based Unequip

Unequip event tags when event ends.

lua

local function endHolidayEvent()
    for _, player in ipairs(game.Players:GetPlayers()) do
        -- Unequip event tag but keep ownership
        TagAPI:Unequip(player, "HolidayEvent2025")
        
        print("Unequipped event tag for " .. player.Name)
    end
end

-- Call when event ends
EventSystem.EventEnded:Connect(endHolidayEvent)

Punishment System

Unequip privilege tags as punishment while preserving ownership.

lua

local function punishPlayer(player, severity)
    if severity == "severe" then
        -- Unequip all privilege tags
        TagAPI:Unequip(player, "VIP")
        TagAPI:Unequip(player, "Trusted")
        TagAPI:Unequip(player, "Premium")
        
        print("Severely punished: " .. player.Name)
    elseif severity == "moderate" then
        -- Only unequip trusted tag
        TagAPI:Unequip(player, "Trusted")
        
        print("Moderately punished: " .. player.Name)
    end
end

-- Usage
punishPlayer(player, "moderate")

Role Change Handling

Unequip old role tags when player's role changes.

lua

local function changePlayerRole(player, newRole)
    -- Unequip all role tags
    local roleTags = {"Owner", "Admin", "Moderator", "Helper", "Member"}
    
    for _, roleTag in ipairs(roleTags) do
        TagAPI:Unequip(player, roleTag)
    end
    
    -- Equip new role tag
    TagAPI:Give(player, newRole)
    TagAPI:Equip(player, newRole)
    
    print(player.Name .. " role changed to " .. newRole)
end

changePlayerRole(player, "Moderator")

Team Change Cleanup

Unequip team tags when players switch teams.

lua

game.Players.PlayerAdded:Connect(function(player)
    player:GetPropertyChangedSignal("Team"):Connect(function()
        -- Unequip all team tags
        TagAPI:Unequip(player, "RedTeam")
        TagAPI:Unequip(player, "BlueTeam")
        TagAPI:Unequip(player, "GreenTeam")
        
        -- Equip new team tag
        local team = player.Team
        if team then
            local teamTag = team.Name .. "Team"
            
            if TagAPI:HasTag(player, teamTag) then
                TagAPI:Equip(player, teamTag)
            end
        end
    end)
end)

Leaderboard Position Loss

Unequip ranking tags when players drop in leaderboard.

lua

local function updateLeaderboardTags()
    -- Unequip all ranking tags from everyone
    for _, player in ipairs(game.Players:GetPlayers()) do
        TagAPI:Unequip(player, "Champion")
        TagAPI:Unequip(player, "RunnerUp")
        TagAPI:Unequip(player, "ThirdPlace")
    end
    
    -- Sort players by score
    local players = game.Players:GetPlayers()
    table.sort(players, function(a, b)
        return a.leaderstats.Score.Value > b.leaderstats.Score.Value
    end)
    
    -- Equip top 3
    if players[1] then
        TagAPI:Equip(players[1], "Champion")
    end
    if players[2] then
        TagAPI:Equip(players[2], "RunnerUp")
    end
    if players[3] then
        TagAPI:Equip(players[3], "ThirdPlace")
    end
end

-- Update every 5 minutes
while true do
    task.wait(300)
    updateLeaderboardTags()
end

Cooldown System

Unequip tags during cooldown periods.

lua

local cooldowns = {}

local function usePowerUp(player)
    local userId = player.UserId
    
    -- Check cooldown
    if cooldowns[userId] and os.time() < cooldowns[userId] then
        return false, "Power-up on cooldown"
    end
    
    -- Unequip PowerUp tag to show it's active
    TagAPI:Unequip(player, "PowerUpReady")
    
    -- Apply power-up effect
    applyPowerUpEffect(player)
    
    -- Set cooldown
    cooldowns[userId] = os.time() + 60
    
    -- Re-equip after cooldown
    task.wait(60)
    
    if player and player.Parent then
        TagAPI:Equip(player, "PowerUpReady")
    end
    
    return true
end

Session-Based Unequip

Unequip session tags when players leave.

lua

game.Players.PlayerRemoving:Connect(function(player)
    -- Unequip all session-based tags
    TagAPI:Unequip(player, "Online")
    TagAPI:Unequip(player, "InMatch")
    TagAPI:Unequip(player, "ActivePlayer")
    
    print("Unequipped session tags for " .. player.Name)
end)

Save Equipped State

Save which tags are equipped when player leaves.

lua

local DataStoreService = game:GetService("DataStoreService")
local playerDataStore = DataStoreService:GetDataStore("PlayerTags")

game.Players.PlayerRemoving:Connect(function(player)
    local equipped = TagAPI:GetEquipped(player)
    
    local success = pcall(function()
        playerDataStore:SetAsync(player.UserId, {
            EquippedTags = equipped
        })
    end)
    
    if success then
        print("Saved equipped tags for " .. player.Name)
    else
        warn("Failed to save equipped tags")
    end
end)

Conditional Unequip with Feedback

Provide detailed feedback about why unequipping failed.

lua

local function unequipWithFeedback(player, tagId)
    local success, msg = TagAPI:Unequip(player, tagId)
    
    if not success then
        if msg:find("not equipped") then
            print("This tag is not currently equipped!")
        else
            print("Error: " .. msg)
        end
    else
        print("Successfully unequipped: " .. tagId)
        print("Available slots: " .. TagAPI:GetAvailableSlots(player))
    end
    
    return success, msg
end

unequipWithFeedback(player, "VIP")

OnTagUnequipped Event Handler

Listen for when tags are unequipped and perform actions.

lua

TagAPI.OnTagUnequipped:Connect(function(player, tagId)
    print(player.Name .. " unequipped tag: " .. tagId)
    
    -- Log analytics
    Analytics:LogEvent("TagUnequipped", {
        UserId = player.UserId,
        TagId = tagId,
        Timestamp = os.time()
    })
    
    -- Update UI for all players
    local TagUpdateEvent = ReplicatedStorage:FindFirstChild("TagUpdateEvent")
    if TagUpdateEvent then
        TagUpdateEvent:FireAllClients("playerUnequipped", {
            Player = player,
            TagId = tagId
        })
    end
end)

Premium Expiration

Unequip Premium tags when subscription expires.

lua

game.Players.PlayerAdded:Connect(function(player)
    -- Check Premium status periodically
    while player and player.Parent do
        task.wait(300) -- Check every 5 minutes
        
        if player.MembershipType ~= Enum.MembershipType.Premium then
            -- Unequip Premium tags
            TagAPI:Unequip(player, "Premium")
            TagAPI:Unequip(player, "PremiumMember")
            
            print("Unequipped Premium tags for " .. player.Name)
        end
    end
end)