TagAPI:Equip

The TagAPI:Equip method equips a tag that a player already owns, making it visible in chat. This method is server-side only and requires the CCTFF framework to be properly initialized. Players can only equip tags they own, and the system respects maximum slot limits defined in your configuration.

Overview

Server/Client

Server-side only

Script Types

Script, ModuleScript

Returns

boolean, string

What It Does

Equips a tag the player owns, making it visible in chat. Player must own the tag first.

Syntax

lua

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

Parameters

Parameter	Type	Description
`player`	`Player`	The player instance who should equip the tag
`tagId`	`string`	The tag identifier to equip (must be owned by player)

Return Values

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

Basic Usage

Equip a single tag for a player.

lua

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

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

Give and Equip Together

Common pattern: Give a tag and immediately equip it.

lua

game.Players.PlayerAdded:Connect(function(player)
    -- Give the tag first
    local giveSuccess = TagAPI:Give(player, "Newcomer")
    
    if giveSuccess then
        -- Then equip it
        local equipSuccess, msg = TagAPI:Equip(player, "Newcomer")
        
        if not equipSuccess then
            warn("Failed to equip Newcomer tag: " .. msg)
        end
    end
end)

Equip Multiple Tags

Equip several tags at once, respecting slot limits.

lua

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

for _, tagId in ipairs(tagsToEquip) do
    local success, msg = TagAPI:Equip(player, tagId)
    
    if not success then
        warn("Could not equip " .. tagId .. ": " .. msg)
    else
        print("Equipped: " .. tagId)
    end
end

Check Before Equipping

Verify player owns tag and has available slots before equipping.

lua

local function safeEquip(player, tagId)
    -- Check if player owns the tag
    if not TagAPI:HasTag(player, tagId) then
        return false, "Player does not own this tag"
    end
    
    -- Check if already equipped
    if TagAPI:IsEquipped(player, tagId) then
        return false, "Tag is already equipped"
    end
    
    -- Check available slots
    local availableSlots = TagAPI:GetAvailableSlots(player)
    if availableSlots <= 0 then
        return false, "No available slots (max: " .. TagAPI:GetMaxSlots() .. ")"
    end
    
    -- Equip the tag
    return TagAPI:Equip(player, tagId)
end

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

Auto-Equip on Purchase

Automatically equip tags when players purchase game passes.

lua

local MarketplaceService = game:GetService("MarketplaceService")
local VIP_PASS_ID = 123456

MarketplaceService.PromptGamePassPurchaseFinished:Connect(function(player, passId, wasPurchased)
    if wasPurchased and passId == VIP_PASS_ID then
        -- Give the tag
        TagAPI:Give(player, "VIP")
        
        -- Auto-equip it
        local success, msg = TagAPI:Equip(player, "VIP")
        
        if success then
            -- Notify player
            game:GetService("StarterGui"):SetCore("ChatMakeSystemMessage", {
                Text = "[System] VIP tag equipped!",
                Color = Color3.fromRGB(0, 255, 0)
            })
        end
    end
end)

Equip with Priority Sorting

Tags are automatically sorted by priority when equipped.

lua

-- Equip multiple tags with different priorities
-- Lower priority number = higher priority display

TagAPI:Equip(player, "Owner")      -- Priority 1 (highest)
TagAPI:Equip(player, "Developer")  -- Priority 2
TagAPI:Equip(player, "Tester")     -- Priority 3

-- Tags will display in order: Owner, Developer, Tester
-- Even if equipped in different order

Smart Slot Management

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

lua

local function equipWithPriority(player, tagId)
    local success, msg = TagAPI:Equip(player, tagId)
    
    -- If slots full, try to unequip lowest priority tag
    if not success and msg:find("Maximum equipped") then
        local equipped = TagAPI:GetEquipped(player)
        
        -- Get the last tag (lowest priority)
        local lowestPriorityTag = equipped[#equipped]
        
        if lowestPriorityTag then
            TagAPI:Unequip(player, lowestPriorityTag)
            
            -- Try equipping again
            return TagAPI:Equip(player, tagId)
        end
    end
    
    return success, msg
end

equipWithPriority(player, "Champion")

Achievement-Based Auto-Equip

Equip tags automatically when players reach milestones.

lua

local function onLevelUp(player, newLevel)
    local tagToEquip = nil
    
    if newLevel >= 100 then
        tagToEquip = "Legendary"
    elseif newLevel >= 50 then
        tagToEquip = "Veteran"
    elseif newLevel >= 10 then
        tagToEquip = "Explorer"
    end
    
    if tagToEquip then
        -- Give and equip
        TagAPI:Give(player, tagToEquip)
        
        local success = TagAPI:Equip(player, tagToEquip)
        
        if success then
            print(player.Name .. " equipped " .. tagToEquip .. " tag!")
        end
    end
end

-- Connect to level system
player.leaderstats.Level.Changed:Connect(function(newLevel)
    onLevelUp(player, newLevel)
end)

Load Saved Equipped Tags

Restore equipped tags from DataStore when player joins.

lua

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

game.Players.PlayerAdded:Connect(function(player)
    local success, savedData = pcall(function()
        return playerDataStore:GetAsync(player.UserId)
    end)
    
    if success and savedData and savedData.EquippedTags then
        -- Equip each saved tag
        for _, tagId in ipairs(savedData.EquippedTags) do
            -- Give tag if player owns it
            if TagAPI:HasTag(player, tagId) then
                TagAPI:Equip(player, tagId)
            end
        end
    end
end)

Command System Integration

Allow players to equip tags via commands.

lua

local function equipCommand(player, args)
    local tagId = args[1]
    
    if not tagId then
        return false, "Usage: !equip [tagId]"
    end
    
    local success, msg = TagAPI:Equip(player, tagId)
    
    if success then
        return true, "Equipped tag: " .. tagId
    else
        return false, "Failed: " .. msg
    end
end

-- Register command
commands["equip"] = equipCommand

UI Selection System

Equip tags based on player selection from a GUI.

lua

local equipRemote = ReplicatedStorage:WaitForChild("EquipTagRemote")

equipRemote.OnServerEvent:Connect(function(player, tagId)
    -- Validate input
    if type(tagId) ~= "string" then
        return
    end
    
    -- Check ownership
    if not TagAPI:HasTag(player, tagId) then
        return
    end
    
    -- Equip the tag
    local success, msg = TagAPI:Equip(player, tagId)
    
    -- Send feedback to client
    if success then
        equipRemote:FireClient(player, "success", "Equipped: " .. tagId)
    else
        equipRemote:FireClient(player, "error", msg)
    end
end)

Group Rank Auto-Equip

Automatically equip appropriate tags based on group rank.

lua

local GROUP_ID = 123456

game.Players.PlayerAdded:Connect(function(player)
    local rank = player:GetRankInGroup(GROUP_ID)
    
    local tagToEquip = nil
    
    if rank >= 250 then
        tagToEquip = "Owner"
    elseif rank >= 200 then
        tagToEquip = "Admin"
    elseif rank >= 100 then
        tagToEquip = "Moderator"
    elseif rank >= 1 then
        tagToEquip = "Member"
    end
    
    if tagToEquip then
        TagAPI:Give(player, tagToEquip)
        TagAPI:Equip(player, tagToEquip)
    end
end)

Event-Exclusive Tags

Equip special event tags for limited-time events.

lua

local function startHolidayEvent()
    for _, player in ipairs(game.Players:GetPlayers()) do
        -- Give event tag
        TagAPI:Give(player, "HolidayEvent2025")
        
        -- Auto-equip if player has slots
        local available = TagAPI:GetAvailableSlots(player)
        
        if available > 0 then
            TagAPI:Equip(player, "HolidayEvent2025")
        end
    end
end

-- Start event
startHolidayEvent()

Temporary Tag Auto-Equip

Give and equip temporary tags with duration.

lua

local function giveTemporaryTag(player, tagId, duration)
    -- Give temporary tag
    TagAPI:Give(player, tagId)
    
    -- Equip it immediately
    TagAPI:Equip(player, tagId)
    
    -- Tag will auto-remove after duration
    -- Config must have Duration set for the tag
end

-- Give 1-hour boost tag
giveTemporaryTag(player, "2XP", 3600)

Badge-Based Equip

Equip exclusive tags when players earn badges.

lua

local BadgeService = game:GetService("BadgeService")
local ACHIEVEMENT_BADGE = 123456789

game.Players.PlayerAdded:Connect(function(player)
    local success, hasBadge = pcall(function()
        return BadgeService:UserHasBadgeAsync(player.UserId, ACHIEVEMENT_BADGE)
    end)
    
    if success and hasBadge then
        TagAPI:Give(player, "AchievementMaster")
        TagAPI:Equip(player, "AchievementMaster")
    end
end)

Rotation System

Rotate through owned tags automatically.

lua

local function rotatePlayerTags(player)
    local owned = TagAPI:GetOwned(player)
    local equipped = TagAPI:GetEquipped(player)
    
    if #owned <= #equipped then
        return -- Already equipping all owned tags
    end
    
    -- Find first unequipped tag
    for _, tagId in ipairs(owned) do
        if not TagAPI:IsEquipped(player, tagId) then
            -- Unequip first equipped tag
            if equipped[1] then
                TagAPI:Unequip(player, equipped[1])
            end
            
            -- Equip new tag
            TagAPI:Equip(player, tagId)
            break
        end
    end
end

-- Rotate every 60 seconds
while true do
    task.wait(60)
    
    for _, player in ipairs(game.Players:GetPlayers()) do
        rotatePlayerTags(player)
    end
end

Premium Subscriber Auto-Equip

Give and equip Premium tags to Roblox Premium members.

lua

game.Players.PlayerAdded:Connect(function(player)
    if player.MembershipType == Enum.MembershipType.Premium then
        TagAPI:Give(player, "Premium")
        
        local success = TagAPI:Equip(player, "Premium")
        
        if success then
            print(player.Name .. " equipped Premium tag!")
        end
    end
end)

Conditional Equip with Feedback

Provide detailed feedback about why equipping failed.

lua

local function equipWithFeedback(player, tagId)
    local success, msg = TagAPI:Equip(player, tagId)
    
    if not success then
        if msg:find("does not own") then
            print("You need to unlock this tag first!")
        elseif msg:find("already equipped") then
            print("This tag is already equipped!")
        elseif msg:find("Maximum equipped") then
            print("Unequip a tag to make room!")
        else
            print("Error: " .. msg)
        end
    else
        print("Successfully equipped: " .. tagId)
    end
    
    return success, msg
end

equipWithFeedback(player, "Champion")

OnTagEquipped Event Handler

Listen for when tags are equipped and perform actions.

lua

TagAPI.OnTagEquipped:Connect(function(player, tagId)
    print(player.Name .. " equipped tag: " .. tagId)
    
    -- Award bonus for equipping certain tags
    if tagId == "VIP" then
        player.leaderstats.Coins.Value += 1000
    end
    
    -- Update UI for all players
    local TagUpdateEvent = ReplicatedStorage:FindFirstChild("TagUpdateEvent")
    if TagUpdateEvent then
        TagUpdateEvent:FireAllClients("playerEquipped", {
            Player = player,
            TagId = tagId
        })
    end
end)