gfx-squad

A FiveM squad/party system that allows players to create, join, and manage squads with up to 4 members. Includes member blips on the map, GamerTag name displays, world markers, friendly fire protection, and a HUD showing squad member health/armor status.

Info

Dependencies

None. This script is standalone and does not require any framework (QBCore, ESX, etc.).

Installation

1. Copy the resource folder

Place gfx-squad into your server's resources directory.

2. Add to server.cfg

ensure gfx-squad

3. Configure

Edit config.lua to customize squad behavior (see Configuration section below).

Configuration

All configuration is in config.lua:

Config = {
    MenuCommand = "squad",      -- Command name to open the squad menu
    FriendlyFire = false,       -- false = squad members cannot damage each other
    MemberBlips = true,         -- Show blips for squad members on the minimap
    GamerTags = true,           -- Show GamerTag names above squad members' heads
    MarkerTimer = 3,            -- Marker display duration (seconds)
    NoImage = "https://...",    -- Fallback avatar URL when Steam profile picture is unavailable
    MarkerType = 1              -- Marker type ID
}

Locales

Notification messages can be customized in the Locales table inside config.lua:

Exports

All exports are server-side.

GetSquadId

Returns the squad ID for a given player.

-- Server-side
local squadId = exports['gfx-squad']:GetSquadId(source)
-- @param source number - The player's server ID
-- @return number|nil - The squad ID, or nil if the player is not in a squad

GetSquad

Returns the full squad data for a given squad ID.

-- Server-side
local squad = exports['gfx-squad']:GetSquad(squadId)
-- @param squadId number - The squad ID
-- @return table|nil - Squad data table containing: owner (identifier), private (bool), members (table)

Returned squad structure:

{
    owner = "steam:xxxxx",   -- Identifier of the squad leader
    private = false,         -- Whether the squad is private (not joinable)
    members = {
        [1] = {
            name = "PlayerName",
            image = "https://...",  -- Steam profile picture URL
            source = 1              -- Player server ID
        },
        -- ...
    }
}

GetSquadMembers

Returns a list of server IDs of all members in the player's squad.

-- Server-side
local members = exports['gfx-squad']:GetSquadMembers(source)
-- @param source number - The player's server ID
-- @return table|nil - Array of server IDs of squad members, or nil if player has no squad

Example:

local members = exports['gfx-squad']:GetSquadMembers(source)
if members then
    for _, memberId in ipairs(members) do
        print("Squad member server ID:", memberId)
    end
end

Events

This script does not expose any public API events intended for external use. All events are internal to the resource's client-server communication.

Commands

Both commands have default key bindings that players can rebind through FiveM's key binding settings.

Features

• Squad Creation -- Create a squad that other players can find and join (up to 4 members).
• Public/Private Toggle -- Squad leaders can toggle the squad between public (joinable) and private (invite only).
• Member Management -- Squad leaders can kick members. Members can leave at any time.
• Member Blips -- Squad members appear on each other's minimap with directional blips showing heading.
• GamerTags -- Floating name tags with health bars displayed above squad members' heads, color-coded by health level (green > 66%, yellow > 33%, red below).
• World Markers -- Squad members can place temporary markers in the world (via raycast) visible to all squad members, showing distance and the marker owner's name.
• Friendly Fire Protection -- When enabled, squad members cannot damage each other (uses relationship groups).
• HUD -- NUI-based HUD displaying squad members' names, health, and armor in real time.
• Steam Avatars -- Automatically fetches Steam profile pictures for squad member display.
• Auto Cleanup -- When a player disconnects, they are automatically removed from their squad. If the leader disconnects, the squad is deleted.

Troubleshooting