TagAPI:Give

The TagAPI:Give method assigns a tag to a player. This method is server-side only and requires the CCTFF framework to be properly initialized. Tags are defined in your CCTFF configuration and can be used for roles, permissions, visual indicators, or player categorization.

Overview

Server/Client

Server-side only

Script Types

Script, ModuleScript

Returns

boolean, string

What It Does

Gives a tag to a player. The tag is added to their inventory and can be equipped.

Syntax

lua

TagAPI:Give(player: Player, tagId: string)

Parameters

Parameter	Type	Description
`player`	`Player`	The player instance who should receive the tag
`tagId`	`string`	The tag identifier as defined in your CCTFF config

Basic Usage

Give a single tag to a player when they join the game.

lua

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

game.Players.PlayerAdded:Connect(function(player)
    TagAPI:Give(player, "Newcomer")
end)

Multiple Tags at Once

Assign multiple tags to a player using a loop.

lua

local tagsToGive = {"VIP", "EarlySupporter", "BetaTester"}

game.Players.PlayerAdded:Connect(function(player)
    for _, tagId in ipairs(tagsToGive) do
        TagAPI:Give(player, tagId)
    end
end)

Conditional Tag Assignment

Give tags based on player data, such as user ID or group membership.

lua

local adminUserIds = {123456, 789012, 345678}

game.Players.PlayerAdded:Connect(function(player)
    if table.find(adminUserIds, player.UserId) then
        TagAPI:Give(player, "Admin")
    end
end)

Group Rank Based Tags

Assign tags based on player's rank in a Roblox group.

lua

local GROUP_ID = 123456

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

Achievement-Based Tags

Award tags when players complete achievements or milestones.

lua

local function onPlayerReachedLevel(player, level)
    if level >= 100 then
        TagAPI:Give(player, "Centurion")
    elseif level >= 50 then
        TagAPI:Give(player, "Veteran")
    elseif level >= 10 then
        TagAPI:Give(player, "Explorer")
    end
end

-- Connect to your leveling system
player.leaderstats.Level.Changed:Connect(function(newLevel)
    onPlayerReachedLevel(player, newLevel)
end)

Purchase-Based Tags

Give tags when players purchase products or game passes.

lua

local MarketplaceService = game:GetService("MarketplaceService")

MarketplaceService.PromptGamePassPurchaseFinished:Connect(function(player, gamePassId, wasPurchased)
    if wasPurchased then
        if gamePassId == 12345 then
            TagAPI:Give(player, "VIP")
        elseif gamePassId == 67890 then
            TagAPI:Give(player, "Premium")
        end
    end
end)

Time-Based Tags

Award tags based on player playtime or session duration.

lua

local PLAYTIME_THRESHOLD = 3600 -- 1 hour in seconds

game.Players.PlayerAdded:Connect(function(player)
    local joinTime = os.time()
    
    task.wait(PLAYTIME_THRESHOLD)
    
    if player and player.Parent then
        TagAPI:Give(player, "Dedicated")
    end
end)

Event-Based Tags

Assign limited-time event tags to all players during special occasions.

lua

local currentDate = os.date("*t")
local isHolidayEvent = currentDate.month == 12 and currentDate.day >= 20

game.Players.PlayerAdded:Connect(function(player)
    if isHolidayEvent then
        TagAPI:Give(player, "HolidayParticipant")
    end
end)

DataStore Integration

Load and apply saved 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, savedTags = pcall(function()
        return playerDataStore:GetAsync(player.UserId)
    end)
    
    if success and savedTags then
        for _, tagId in ipairs(savedTags) do
            TagAPI:Give(player, tagId)
        end
    end
end)

Command System Integration

Allow administrators to give tags via commands.

lua

local function giveTagCommand(admin, targetPlayerName, tagId)
    local targetPlayer = game.Players:FindFirstChild(targetPlayerName)
    
    if targetPlayer then
        TagAPI:Give(targetPlayer, tagId)
        return true, "Tag given successfully!"
    else
        return false, "Player not found"
    end
end

-- Example command handler
adminCommands["givetag"] = giveTagCommand

Leaderboard-Based Tags

Award tags to top players on the leaderboard.

lua

local function updateLeaderboardTags()
    local players = game.Players:GetPlayers()
    
    table.sort(players, function(a, b)
        return a.leaderstats.Points.Value > b.leaderstats.Points.Value
    end)
    
    -- Top 3 players get special tags
    if players[1] then
        TagAPI:Give(players[1], "Champion")
    end
    if players[2] then
        TagAPI:Give(players[2], "RunnerUp")
    end
    if players[3] then
        TagAPI:Give(players[3], "ThirdPlace")
    end
end

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

Premium Subscription Tags

Give tags to Roblox Premium subscribers.

lua

game.Players.PlayerAdded:Connect(function(player)
    if player.MembershipType == Enum.MembershipType.Premium then
        TagAPI:Give(player, "PremiumMember")
    end
end)

Badge-Based Tags

Award tags when players earn specific badges.

lua

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

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

Team-Based Tags

Assign tags when players join specific teams.

lua

game.Players.PlayerAdded:Connect(function(player)
    player:GetPropertyChangedSignal("Team"):Connect(function()
        local team = player.Team
        
        if team then
            if team.Name == "Red" then
                TagAPI:Give(player, "RedTeamMember")
            elseif team.Name == "Blue" then
                TagAPI:Give(player, "BlueTeamMember")
            end
        end
    end)
end)

Friend-Based Tags

Give tags to players who are friends with specific users.

lua

local DEVELOPER_USER_ID = 123456

game.Players.PlayerAdded:Connect(function(player)
    local success, isFriend = pcall(function()
        return player:IsFriendsWith(DEVELOPER_USER_ID)
    end)
    
    if success and isFriend then
        TagAPI:Give(player, "FriendOfDev")
    end
end)

Stat Threshold Tags

Award tags when player stats reach certain thresholds.

lua

local function checkStatTags(player)
    local coins = player.leaderstats.Coins.Value
    
    if coins >= 1000000 then
        TagAPI:Give(player, "Millionaire")
    elseif coins >= 100000 then
        TagAPI:Give(player, "Wealthy")
    elseif coins >= 10000 then
        TagAPI:Give(player, "Prosperous")
    end
end

game.Players.PlayerAdded:Connect(function(player)
    player.leaderstats.Coins.Changed:Connect(function()
        checkStatTags(player)
    end)
end)

Referral System Tags

Give tags to players who refer others to the game.

lua

local function onPlayerReferred(referrer, referralCount)
    if referralCount >= 10 then
        TagAPI:Give(referrer, "Ambassador")
    elseif referralCount >= 5 then
        TagAPI:Give(referrer, "Recruiter")
    elseif referralCount >= 1 then
        TagAPI:Give(referrer, "Inviter")
    end
end

-- Connect to your referral tracking system
ReferralSystem.PlayerReferred:Connect(onPlayerReferred)

Combat Achievement Tags

Award tags based on combat statistics and kills.

lua

local function onPlayerKill(player, kills)
    if kills >= 1000 then
        TagAPI:Give(player, "Legendary")
    elseif kills >= 500 then
        TagAPI:Give(player, "Elite")
    elseif kills >= 100 then
        TagAPI:Give(player, "Veteran")
    elseif kills >= 10 then
        TagAPI:Give(player, "Fighter")
    end
end

-- Connect to your combat system
CombatSystem.PlayerKilled:Connect(onPlayerKill)

Season Pass Tags

Assign tags to players who own the current season pass.

lua

local SEASON_PASS_PRODUCT_ID = 123456

game.Players.PlayerAdded:Connect(function(player)
    local ownsPass = MarketplaceService:UserOwnsGamePassAsync(player.UserId, SEASON_PASS_PRODUCT_ID)
    
    if ownsPass then
        TagAPI:Give(player, "SeasonPassHolder")
    end
end)