TagAPI:GetOwned

The TagAPI:GetOwned method retrieves all tags that a player currently owns. This method can be called from both server and client contexts, making it versatile for inventory systems, UI displays, and server-side validation.

Overview

Execution Context

Server, Client

Script Type

Server Script, Local Script

Returns

table (array of tag IDs)

Side Effects

None - read-only operation

Syntax

local ownedTags = TagAPI:GetOwned(player: Player)

Parameter	Type	Description
`player`	`Player`	The player instance to retrieve owned tags from

Return Values

Return	Type	Description
`ownedTags`	`table`	An array containing all tag IDs the player owns (e.g., {"VIP", "Admin", "Tester"})

Basic Usage

Retrieve all tags owned by a player.

Lua

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

local ownedTags = TagAPI:GetOwned(player)
print("Player owns " .. #ownedTags .. " tags")

for _, tagId in ipairs(ownedTags) do
    print("Owned tag: " .. tagId)
end

Check Tag Ownership

Verify if a player owns a specific tag.

Lua

local function hasTag(player, tagId)
    local ownedTags = TagAPI:GetOwned(player)
    return table.find(ownedTags, tagId) ~= nil
end

if hasTag(player, "VIP") then
    print("Player owns VIP tag!")
else
    print("Player does not own VIP tag")
end

Display Owned Count

Show how many tags a player has collected.

Lua

game.Players.PlayerAdded:Connect(function(player)
    local ownedTags = TagAPI:GetOwned(player)
    
    -- Create leaderstats display
    local leaderstats = Instance.new("Folder")
    leaderstats.Name = "leaderstats"
    leaderstats.Parent = player
    
    local tagsOwned = Instance.new("IntValue")
    tagsOwned.Name = "Tags Owned"
    tagsOwned.Value = #ownedTags
    tagsOwned.Parent = leaderstats
end)

UI Tag Inventory

Populate a GUI with all owned tags for player selection.

Lua

-- LocalScript
local player = game.Players.LocalPlayer
local TagAPI = CCTFF.TagAPI

local ownedTags = TagAPI:GetOwned(player)
local tagInventoryFrame = script.Parent.TagInventoryFrame

-- Clear existing buttons
for _, child in ipairs(tagInventoryFrame:GetChildren()) do
    if child:IsA("TextButton") then
        child:Destroy()
    end
end

-- Create button for each owned tag
for i, tagId in ipairs(ownedTags) do
    local button = Instance.new("TextButton")
    button.Name = tagId
    button.Text = tagId
    button.Size = UDim2.new(0.45, 0, 0, 40)
    button.Position = UDim2.new(
        (i % 2 == 0) and 0.52 or 0.03,
        0,
        0.05 + math.floor((i - 1) / 2) * 0.12,
        0
    )
    button.Parent = tagInventoryFrame
    
    button.MouseButton1Click:Connect(function()
        -- Fire equip request to server
        equipRemote:FireServer(tagId)
    end)
end

Filter by Tag Type

Separate owned tags by category or rarity.

Lua

local TAG_CATEGORIES = {
    Admin = {"Owner", "Admin", "Moderator"},
    Premium = {"VIP", "Premium", "Supporter"},
    Achievement = {"Champion", "Veteran", "Explorer"}
}

local function getOwnedByCategory(player, category)
    local ownedTags = TagAPI:GetOwned(player)
    local categoryTags = TAG_CATEGORIES[category] or {}
    local result = {}
    
    for _, tagId in ipairs(ownedTags) do
        if table.find(categoryTags, tagId) then
            table.insert(result, tagId)
        end
    end
    
    return result
end

-- Get all admin tags player owns
local adminTags = getOwnedByCategory(player, "Admin")
print("Player owns " .. #adminTags .. " admin tags")

Count Specific Tags

Count how many tags from a specific list the player owns.

Lua

local RARE_TAGS = {"Legendary", "Mythical", "Godlike", "Ultimate"}

local function countRareTags(player)
    local ownedTags = TagAPI:GetOwned(player)
    local count = 0
    
    for _, tagId in ipairs(ownedTags) do
        if table.find(RARE_TAGS, tagId) then
            count = count + 1
        end
    end
    
    return count
end

local rareCount = countRareTags(player)
print("Player owns " .. rareCount .. " rare tags")

Unlock Progress Tracker

Calculate percentage of all available tags the player has unlocked.

Lua

local function getUnlockProgress(player)
    local ownedTags = TagAPI:GetOwned(player)
    local allTags = TagAPI:GetAllTags() -- Returns all available tags
    
    local progress = (#ownedTags / #allTags) * 100
    return math.floor(progress * 10) / 10 -- Round to 1 decimal
end

local progress = getUnlockProgress(player)
print("Collection progress: " .. progress .. "%")

DataStore Save Integration

Save owned tags to DataStore when player leaves.

Lua

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

game.Players.PlayerRemoving:Connect(function(player)
    local ownedTags = TagAPI:GetOwned(player)
    
    local success, err = pcall(function()
        playerDataStore:SetAsync(player.UserId, {
            OwnedTags = ownedTags,
            LastSaved = os.time()
        })
    end)
    
    if success then
        print("Saved " .. #ownedTags .. " tags for " .. player.Name)
    else
        warn("Failed to save tags: " .. err)
    end
end)

Reward System Check

Award bonuses based on number of tags owned.

Lua

local function checkCollectionRewards(player)
    local ownedTags = TagAPI:GetOwned(player)
    local tagCount = #ownedTags
    
    if tagCount >= 50 then
        TagAPI:Give(player, "Master Collector")
        player.leaderstats.Coins.Value += 10000
    elseif tagCount >= 25 then
        TagAPI:Give(player, "Tag Collector")
        player.leaderstats.Coins.Value += 5000
    elseif tagCount >= 10 then
        TagAPI:Give(player, "Tag Enthusiast")
        player.leaderstats.Coins.Value += 1000
    end
end

-- Check on player join
game.Players.PlayerAdded:Connect(checkCollectionRewards)

Compare Two Players

Compare tag collections between two players.

Lua

local function compareTagCollections(player1, player2)
    local tags1 = TagAPI:GetOwned(player1)
    local tags2 = TagAPI:GetOwned(player2)
    
    local uniqueToPlayer1 = {}
    local uniqueToPlayer2 = {}
    local shared = {}
    
    -- Find unique to player1
    for _, tag in ipairs(tags1) do
        if table.find(tags2, tag) then
            table.insert(shared, tag)
        else
            table.insert(uniqueToPlayer1, tag)
        end
    end
    
    -- Find unique to player2
    for _, tag in ipairs(tags2) do
        if not table.find(tags1, tag) then
            table.insert(uniqueToPlayer2, tag)
        end
    end
    
    return {
        Shared = shared,
        UniqueToPlayer1 = uniqueToPlayer1,
        UniqueToPlayer2 = uniqueToPlayer2
    }
end

local comparison = compareTagCollections(player1, player2)
print("Shared tags: " .. #comparison.Shared)

Admin Command: List Owned

Create an admin command to view player's owned tags.

Lua

local function listOwnedCommand(admin, args)
    local targetName = args[1]
    if not targetName then
        return false, "Usage: !listowned [player]"
    end
    
    local targetPlayer = game.Players:FindFirstChild(targetName)
    if not targetPlayer then
        return false, "Player not found"
    end
    
    local ownedTags = TagAPI:GetOwned(targetPlayer)
    
    local message = targetPlayer.Name .. " owns " .. #ownedTags .. " tags:\n"
    message = message .. table.concat(ownedTags, ", ")
    
    return true, message
end

-- Register command
adminCommands["listowned"] = listOwnedCommand

Find Missing Tags

Identify which tags a player doesn't own yet.

Lua

local function getMissingTags(player)
    local ownedTags = TagAPI:GetOwned(player)
    local allTags = TagAPI:GetAllTags()
    local missing = {}
    
    for _, tagId in ipairs(allTags) do
        if not table.find(ownedTags, tagId) then
            table.insert(missing, tagId)
        end
    end
    
    return missing
end

local missingTags = getMissingTags(player)
print("Still need to unlock: " .. table.concat(missingTags, ", "))

Rarity Distribution

Analyze the rarity distribution of owned tags.

Lua

local TAG_RARITIES = {
    Common = {"Newcomer", "Member", "Player"},
    Rare = {"VIP", "Supporter", "Premium"},
    Epic = {"Veteran", "Champion", "Elite"},
    Legendary = {"Owner", "Admin", "Mythical"}
}

local function getRarityDistribution(player)
    local ownedTags = TagAPI:GetOwned(player)
    local distribution = {
        Common = 0,
        Rare = 0,
        Epic = 0,
        Legendary = 0
    }
    
    for _, tagId in ipairs(ownedTags) do
        for rarity, tags in pairs(TAG_RARITIES) do
            if table.find(tags, tagId) then
                distribution[rarity] += 1
                break
            end
        end
    end
    
    return distribution
end

local dist = getRarityDistribution(player)
print("Common: " .. dist.Common .. " | Rare: " .. dist.Rare)

Trade Validation

Check if player owns tags before allowing trade.

Lua

local function canTradeTag(player, tagId)
    local ownedTags = TagAPI:GetOwned(player)
    
    -- Check ownership
    if not table.find(ownedTags, tagId) then
        return false, "You don't own this tag"
    end
    
    -- Check if tag is tradeable
    local tagConfig = TagAPI:GetTagConfig(tagId)
    if not tagConfig.Tradeable then
        return false, "This tag cannot be traded"
    end
    
    return true, "Tag is tradeable"
end

local canTrade, message = canTradeTag(player, "VIP")
print(message)

Client-Side Display

Show owned tags in a LocalScript for UI purposes.

Lua

-- LocalScript
local player = game.Players.LocalPlayer
local TagAPI = CCTFF.TagAPI

local ownedTags = TagAPI:GetOwned(player)
local tagListLabel = script.Parent.TagListLabel

-- Update UI
tagListLabel.Text = "You own " .. #ownedTags .. " tags"

-- Listen for updates
TagAPI.OnTagAdded:Connect(function(addedPlayer, tagId)
    if addedPlayer == player then
        ownedTags = TagAPI:GetOwned(player)
        tagListLabel.Text = "You own " .. #ownedTags .. " tags"
    end
end)

Achievement Unlock Check

Verify if player has unlocked all tags in a set.

Lua

local ACHIEVEMENT_SETS = {
    Starter = {"Newcomer", "Explorer", "Adventurer"},
    Combat = {"Fighter", "Warrior", "Champion"},
    Social = {"Friend", "Popular", "Celebrity"}
}

local function hasCompleteSet(player, setName)
    local ownedTags = TagAPI:GetOwned(player)
    local requiredTags = ACHIEVEMENT_SETS[setName]
    
    if not requiredTags then
        return false
    end
    
    for _, tagId in ipairs(requiredTags) do
        if not table.find(ownedTags, tagId) then
            return false
        end
    end
    
    return true
end

if hasCompleteSet(player, "Starter") then
    print("Starter set complete! Awarding bonus...")
    TagAPI:Give(player, "StarterMaster")
end