gfx-squad-remake

A full-featured squad/party system for FiveM with a React-based NUI interface. Players can create squads, invite members, chat, and track teammates with map blips, nametags, and a HUD overlay showing member health and armor. Supports optional friendly fire protection between squad members.

Info

Dependencies

Installation

1. Copy the resource folder

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

2. Add to server.cfg

ensure gfx-lib
ensure gfx-squad-remake

Make sure gfx-lib starts before gfx-squad-remake.

3. Configure Discord Bot Token (optional)

If you want player avatars fetched from Discord, set your bot token in config/server_config.lua:

Config = {
    DiscordBotToken = "YOUR_BOT_TOKEN_HERE",
}

Configuration

Client Config (config/client_config.lua)

Config = {
    FriendlyFire = false,         -- false = squad members cannot damage each other
    HudInterval = 5000,           -- HUD update interval in milliseconds (used for infinity mode, currently disabled)
    Theme = {
        ["primary"] = '#FF2F2F',                    -- Primary UI color
        ["primary-content"] = '#900000',            -- Primary content/accent color
        ["primary-opacity"] = "rgba(255, 47, 47, 0.2)", -- Primary color with transparency
    }
}

Server Config (config/server_config.lua)

local modules = exports["gfx-lib"]:getModules()

Config = {
    DiscordBotToken = "",               -- Discord bot token for fetching player avatars
    Notify = function(source, message)  -- Notification function (customizable)
        modules.Notify(source, message)
    end,
}

Locale (config/locale.lua)

The script supports localization. Set the active locale:

Locale = 'en'

All UI strings are defined in the Locales table and can be translated by adding a new language key.

Exports

All exports are server-side.

GetSquadMembers

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

-- Server-side
local memberIds = exports['gfx-squad-remake']:GetSquadMembers(source)
-- Returns: { 1, 4, 7 } (table of server IDs) or {} if not in a squad

Returns: table - Array of server IDs of squad members, or empty table if the player is not in a squad.

GetSquadData

Returns the full squad data object for the player's current squad.

-- Server-side
local squad = exports['gfx-squad-remake']:GetSquadData(source)
--[[
Returns:
{
    id = 123456,              -- Unique squad ID
    name = "Squad Name",      -- Squad name
    owner = 4,                -- Owner's server ID
    image = "https://...",    -- Squad avatar image URL
    privacy = "public",       -- "public" or "private"
    memberLimit = 12,         -- Maximum member count
    members = { ... },        -- Array of member objects
    chat = { ... }            -- Array of chat messages
}
]]

Returns: table - Full squad data object, or empty table if not in a squad.

HasMemberGotASquad

Checks whether a player is currently in any squad.

-- Server-side
local inSquad = exports['gfx-squad-remake']:HasMemberGotASquad(source)
-- Returns: true or false

Returns: boolean - true if the player is in a squad, false otherwise.

GetSquadId

Returns the squad ID of the player's current squad.

-- Server-side
local squadId = exports['gfx-squad-remake']:GetSquadId(source)
-- Returns: 123456 (number) or nil

Returns: number|nil - The squad ID, or nil if the player is not in a squad.

Events

No public API events found. All events used by this script are internal (NUI communication, member sync, relationship handling).

Commands

Features

• Squad Creation - Create squads with a custom name, avatar image, privacy setting (public/private), and member limit
• Squad Browsing - Browse and join public squads through the NUI menu
• Invite System - Squad owners can invite other players; invited players receive a notification and pending invite count
• Squad Chat - Real-time in-squad text chat with timestamps and player avatars
• Member HUD - On-screen HUD overlay showing squad member names, health bars, and armor values (position and alignment configurable per player)
• Map Blips - Squad members appear as blips on the minimap with their name, updated every 5 seconds
• Nametags - GTA MP-style gamer tags above squad members showing name and health bar with color-coded health (green > yellow > red)
• Friendly Fire Protection - Optional feature that prevents squad members from damaging each other using GTA relationship groups
• Squad Settings - Owners can update squad name, avatar, privacy, and member limit after creation
• Kick Members - Squad owners can kick members from the squad
• Player Avatars - Automatic avatar fetching from Discord (via bot token) or Steam profile pictures
• Personal Settings - Each player can toggle HUD, nametags, and blips visibility, and choose HUD alignment (left/center/right)
• Waypoint Sharing - Click on a squad member in the UI to set a waypoint to their location
• Auto-Cleanup - When an owner disconnects, the squad is deleted; when a member disconnects, they leave the squad automatically
• Localization - Full locale support with all UI strings configurable
• Theme Customization - Configurable primary colors for the NUI interface
• React NUI - Modern React-based user interface

Troubleshooting