💻Exports (Server)

Name Display Related

Toggle Name Visibility

Show player's name

local isVisible = exports['cats-advanced-name']:switchVisibleName(source, true)

Hide player's name

local isHidden = exports['cats-advanced-name']:switchVisibleName(source, false)

Toggle current state

local isToggled = exports['cats-advanced-name']:switchVisibleName(source)

Change Character Name

Change first and last name

local success = exports['cats-advanced-name']:changeName(source, 'John', 'Doe')
if success then
    print('Name changed successfully')
end

Name Label Management

Set a label (displayed above name)

local success = exports['cats-advanced-name']:changeNameLabel(source, 'Police Chief')

Remove the label

exports['cats-advanced-name']:removeNameLabel(source)

Get Current Display Name

Get the currently displayed name (nickname or real name)

local displayName = exports['cats-advanced-name']:getDisplayName(source)
print('Current display name: ' .. displayName)

Get Display Name by CitizenID (QBCore)

Get display name using QBCore citizenid

local displayName = exports['cats-advanced-name']:getDisplayNameByCitizenid('ABC12345')
print('Player name: ' .. displayName)

Get Display Name by Identifier

Get display name using player identifier (works with both QBCore and ESX)

local displayName = exports['cats-advanced-name']:getDisplayNameByIdentifier('license:1234567890abcdef')
print('Player name: ' .. displayName)

Nickname Management

Add Nickname

Add a new nickname

local success = exports['cats-advanced-name']:addNickname(source, 'Shadow')
if success then
    print('Nickname added successfully')
end

Use Nickname

Use a saved nickname

exports['cats-advanced-name']:useNickname(source, 'Shadow')

Revert to Character Name

Stop using nickname and return to real name

exports['cats-advanced-name']:useCharacterName(source)

Get Nickname List

Get list of saved nicknames

local nicknames = exports['cats-advanced-name']:getNicknames(source)
for i, nickname in ipairs(nicknames) do
    print(i .. ': ' .. nickname)
end

Delete Nickname

Delete a specific nickname

exports['cats-advanced-name']:deleteNickname(source, 'Shadow')

Mark Related

Toggle Mark

Toggle a specific mark (on→off or off→on)

local success = exports['cats-advanced-name']:toggleMark(source, 'police')
if success then
    print('Police mark toggled successfully')
end

Other mark examples

exports['cats-advanced-name']:toggleMark(source, 'ems')      -- EMS mark
exports['cats-advanced-name']:toggleMark(source, 'mechanic') -- Mechanic mark
exports['cats-advanced-name']:toggleMark(source, 'beginner') -- Beginner mark
exports['cats-advanced-name']:toggleMark(source, 'vip')      -- VIP mark

Get Player Marks List

Get marks list for a specific player

local playerMarks = exports['cats-advanced-name']:getPlayerMarks(source)

Check active marks

for markId, isActive in pairs(playerMarks) do
    if isActive then
        print('Active mark: ' .. markId)
    end
end

Check Mark Status

Check if a specific mark is active

local isPolice = exports['cats-advanced-name']:isMarkActive(source, 'police')
if isPolice then
    print('Police mark is active')
end

Check mark status for another player

local hasEMS = exports['cats-advanced-name']:isMarkActive(12, 'ems') -- Player ID 12

Advanced Examples

Complete Player Setup

-- Setup a new VIP player
function SetupVIPPlayer(source)
    -- Change name visibility
    exports['cats-advanced-name']:switchVisibleName(source, true)
    
    -- Add VIP nickname
    exports['cats-advanced-name']:addNickname(source, 'VIP_Member')
    exports['cats-advanced-name']:useNickname(source, 'VIP_Member')
    
    -- Set VIP label
    exports['cats-advanced-name']:changeNameLabel(source, '★ VIP ★')
    
    -- Add VIP mark
    exports['cats-advanced-name']:toggleMark(source, 'vip')
    
    print('VIP setup completed for player ' .. source)
end

Dynamic Label System

-- Auto-update labels based on job
function UpdatePlayerLabel(source)
    local label = ""
    
    if Framework == 'qbcore' then
        local Player = QBCore.Functions.GetPlayer(source)
        if Player then
            local job = Player.PlayerData.job
            if job and job.name ~= "unemployed" then
                label = "[" .. job.label .. "]"
            end
        end
    elseif Framework == 'esx' then
        local xPlayer = ESX.GetPlayerFromId(source)
        if xPlayer then
            local job = xPlayer.getJob()
            if job and job.name ~= "unemployed" then
                label = "[" .. job.label .. "]"
            end
        end
    end
    
    -- Apply or remove label
    if label ~= "" then
        exports['cats-advanced-name']:changeNameLabel(source, label)
    else
        exports['cats-advanced-name']:removeNameLabel(source)
    end
end

Permission System

-- Check access based on marks
function HasAccess(source, requiredMark)
    return exports['cats-advanced-name']:isMarkActive(source, requiredMark)
end

-- Usage in commands
RegisterCommand('viparea', function(source, args, rawCommand)
    if not HasAccess(source, 'vip') then
        TriggerClientEvent('chat:addMessage', source, {
            args = {"Error", "VIP access required"}
        })
        return
    end
    
    -- VIP area logic here
    print('Player ' .. source .. ' accessed VIP area')
end, false)

Chat System Integration

-- Enhanced chat with name display
RegisterNetEvent('chat:sendMessage', function(message)
    local source = source
    local playerName = exports['cats-advanced-name']:getDisplayName(source)
    local color = "^7" -- Default white
    
    -- Color based on marks
    if exports['cats-advanced-name']:isMarkActive(source, 'admin') then
        color = "^1" -- Red for admin
    elseif exports['cats-advanced-name']:isMarkActive(source, 'vip') then
        color = "^3" -- Yellow for VIP
    end
    
    TriggerClientEvent('chat:addMessage', -1, {
        args = {color .. playerName .. "^7", message}
    })
end)

Logging System

-- Log player actions with display names
function LogPlayerAction(source, action, details)
    local playerName = exports['cats-advanced-name']:getDisplayName(source)
    local timestamp = os.date("%Y-%m-%d %H:%M:%S")
    local logMessage = string.format("[%s] %s: %s - %s", 
        timestamp, 
        playerName, 
        action, 
        details or ""
    )
    
    print(logMessage)
    -- Save to file or database here
end

-- Usage examples
LogPlayerAction(source, "Vehicle Spawned", "Adder")
LogPlayerAction(source, "Money Transfer", "$5000 to John Doe")