Create and retire gamer tags with their players

A gamer tag is an overhead display with separately controlled components such as a name, crew marker, voice icon and health bar. The official gamer-tag manual documents those components, but its sample must be read alongside the actual creation-native contract .

CreateMpGamerTagWithCrewColor takes a client player index, not a ped handle, as its first argument. It has a void return: the created tag’s ID is the player index. Do not write tag = CreateMpGamerTagWithCrewColor(...) and pass that nonexistent return value to subsequent natives. Resolve player server IDs separately using network and local IDs.

One resource owns a player’s tag

Player-associated tag slots are shared game state. Coordinate with an existing nameplate resource before installing a replacement. This example does not delete a pre-existing tag that it does not own. It waits for a slot to be free by trying again on a later bounded polling interval, rather than blocking indefinitely during tag teardown.

The client script owns at most one tag per other locally active player. It uses GetActivePlayers() instead of an assumed fixed slot range. A changed ped or server-session association retires the old owned tag before attempting to create its replacement.


local tags = {}
 
local function removeTag(player)
    local entry = tags[player]
    if entry then
        RemoveMpGamerTag(entry.tag)
        tags[player] = nil
    end
end
 
CreateThread(function()
    while true do
        local visible = {}
        for _, player in ipairs(GetActivePlayers()) do
            if player ~= PlayerId() then
                local ped = GetPlayerPed(player)
                if ped ~= 0 and DoesEntityExist(ped) then
                    visible[player] = true
                    local serverId = GetPlayerServerId(player)
                    local entry = tags[player]
                    if entry and (entry.ped ~= ped or entry.serverId ~= serverId) then
                        removeTag(player)
                        entry = nil
                    end
                    if not entry and not IsMpGamerTagActive(player) and IsMpGamerTagFree(player) then
                        local label = ('%s [%d]'):format(GetPlayerName(player) or 'Player', serverId)
                        CreateMpGamerTagWithCrewColor(player, label, false, false, '', 0, 0, 0, 0)
                        entry = { ped = ped, serverId = serverId, tag = player }
                        tags[player] = entry
                        SetMpGamerTagVisibility(entry.tag, 0, true)
                    end
                    if entry then
                        SetMpGamerTagVisibility(entry.tag, 4, NetworkIsPlayerTalking(player))
                    end
                end
            end
        end
        for player in pairs(tags) do
            if not visible[player] then removeTag(player) end
        end
        Wait(200)
    end
end)
 
AddEventHandler('onResourceStop', function(resource)
    if resource ~= GetCurrentResourceName() then return end
    for player in pairs(tags) do removeTag(player) end
end)

The 200 ms interval is an example response/CPU tradeoff, not a universal setting. These component properties do not require an unyielding loop. A production interface may use character names rather than the user-controlled platform name; do not treat either display string as an authorization key. Avoid running multiple competing tag writers: checking a shared slot once is not a cross-resource locking protocol.

Opacity and color are separate from visibility

SetMpGamerTagVisibility(tag, component, visible) shows or hides a component. SetMpGamerTagAlpha(tag, component, alpha) sets opacity. The health/armour component, ID 2, starts with zero opacity in the documented behavior, so enabling visibility alone is insufficient.

Use SetMpGamerTagHealthBarColour(tag, hudColor) for the health bar and SetMpGamerTagColour(tag, component, hudColor) for other component colors. HUD color IDs are not RGB arrays; use the HUD color catalog. Apply only the components your interface needs, and record any special visibility policy for spectators or hidden players.

Component catalog

Official source · Snapshot: 2026-09-23 · Download complete JSON

31 of 31 entries

Components list
ID	Name
0	GAMER_NAME
1	CREW_TAG
2	healthArmour
3	BIG_TEXT
4	AUDIO_ICON
5	MP_USING_MENU
6	MP_PASSIVE_MODE
7	WANTED_STARS
8	MP_DRIVER
9	MP_CO_DRIVER
10	MP_TAGGED
11	GAMER_NAME_NEARBY
12	ARROW
13	MP_PACKAGES
14	INV_IF_PED_FOLLOWING
15	RANK_TEXT
16	MP_TYPING
17	MP_BAG_LARGE
18	MP_TAG_ARROW
19	MP_GANG_CEO
20	MP_GANG_BIKER
21	BIKER_ARROW
22	MC_ROLE_PRESIDENT
23	MC_ROLE_VICE_PRESIDENT
24	MC_ROLE_ROAD_CAPTAIN
25	MC_ROLE_SARGEANT
26	MC_ROLE_ENFORCER
27	MC_ROLE_PROSPECT
28	MP_TRANSMITTER
29	MP_BOMB

Examples and illustrations
Preview	Context
	Gamer Tags

The structured catalog retains the source’s component list and illustration. Its JSON snapshot includes every row, not just the first visible page. Images are served locally; stored-byte integrity and current remote freshness are separate checks.

Verify cleanup and identity changes

Test another player entering/leaving scope, changing model, talking, disconnecting and reconnecting, and stopping only this resource. A pre-existing tag owned by another resource must not be removed. An owned tag awaiting teardown must not be immediately overwritten. Test the health bar with visibility on but alpha zero, then with an explicit alpha, to distinguish the two settings.

The example’s native signature and lifecycle are source-reviewed, but rendering and client scope changes still require FiveM. For a non-player ped, use the appropriate ped-tag native rather than passing a ped handle to this player-specific function. See native context and the reference directory.