✴️Global States

Global States are created or modified on the server and read by the client! We use Global States for most of our Gang Data in Gang System V2

GangData

GlobalState["GangData"] is a globally accessible table that contains information about all gangs currently loaded from the database. Each gang is keyed by its unique gang ID and contains detailed attributes for logic, display, and gameplay mechanics. This data is automatically populated and refreshed when the resource starts!

local gangData = GlobalState["GangData"]

Structure

GlobalState["GangData"] = {
    [gangID] = {
        id = number,                -- Unique ID of the gang
        name = string,              -- Full name of the gang (e.g., "Grim Reapers")
        tag = string,               -- Short tag used to identify the gang (e.g., "TES")
        type = string,              -- Type of gang (e.g., "mob", "crew", "community")
        home_turf = string,         -- Turf zone code that the gang owns (e.g., "MORN")
        last_blueprint = number,    -- Unix timestamp (seconds) of last blueprint event
        last_home_turf = number,    -- Unix timestamp (seconds) of last home turf claim
        last_gift = number,         -- Unix timestamp (seconds) of last gift received
        last_bm_shop = number,      -- Unix timestamp (seconds) of last black market shop use
        color = number,             -- Color ID for UI elements (e.g., map, HUD)
        prevalence = number,        -- Influence value used in turf control logic
        dirty_cash = number,        -- Amount of unlaundered money the gang has
        clean_cash = number,        -- Amount of laundered money the gang has
        penalty = number,           -- Penalty status (used for timeouts or bans from actions)
        last_active = number,       -- Last activity time in milliseconds (epoch)
        created_at = number         -- Gang creation time in milliseconds (epoch)
    },
    ...
}

• id (number) - Unique ID of the Gang

• name (string), — Full name of the gang (e.g. "Grim Reapers")

Example

local gangID = exports['cb-gangsystem']:GetGangID(playerID)
local gangData = GlobalState["GangData"][gangID]
if gangData then
    print("Gang Name:", gangData.name)
    print("Cash on Hand:", gangData.dirty_cash)
    print("Last Active:", os.date('%c', gangData.last_active / 1000))
end

---

GangPermissions

GlobalState["GangPermissions"] is a server-side global table that defines rank-based permissions for each gang. It is structured by gang ID and then by rank index, mapping what actions members of each rank are allowed to perform. This table is populated when the resource starts, which pulls data from the gang_perms SQL table.

local gangPerms = GlobalState["GangPermissions"]

Structure

GlobalState["GangPermissions"] = {
    [gangID] = {
        [rankIndex] = {
            gang_id = number,                  -- The gang's unique ID
            rankIndex = number,                -- The numeric index of the rank (e.g., 0 = leader, 1 = co-leader)
            rankName = string,                 -- Display name of the rank (e.g., "Boss", "Lieutenant")

            -- Permissions (stored as numbers: 1 = allowed, 0 = not allowed)
            rename_gang = number,              -- Can rename the gang
            change_rank_name = number,         -- Can rename ranks
            change_gang_color = number,        -- Can change the gang's color
            declare_home_turf = number,        -- Can set the gang's home turf
            change_hideout_password = number,  -- Can change the hideout password
            accept_gifts = number,             -- Can accept gift packages
            change_rank_permissions = number,  -- Can modify rank permissions
            manage_gang_members = number,      -- Can manage members
            remove_gang_fund = number,         -- Can withdraw from gang funds
            add_gang_fund = number,            -- Can deposit into gang funds
            transfer_gang_fund = number,       -- Can transfer gang money
            create_alliances = number,         -- Can form alliances
            cancel_alliances = number,         -- Can cancel alliances
            kick_members = number              -- Can remove members from the gang
        },
        ...
    },
    ...
}

Example

local gangID = exports['cb-gangsystem']:GetGangID(playerID)
local playerRank = GetPlayerGangRank(playerID)

local perms = GlobalState["GangPermissions"][gangID] and GlobalState["GangPermissions"][gangID][playerRank]
if perms and perms.rename_gang then
    print("Player can rename the gang.")
else
    print("Permission denied.")
end

---

GangMembers

Description

GlobalState["GangMembers"] is a lookup table that maps each gang member (by citizen_id) to their gang ID and rank. This is populated by querying your gang_members SQL table.

local gangMembers = GlobalState["GangMembers"]

Structure

GlobalState["GangMembers"] = {
    [citizen_id] = {
        citizen_id = string,
        gang_id = number,
        name = string,
        rank = number,
    },
    ...
}

Example

for _, member in pairs(GlobalState["GangMembers"]) do
    if member.gang_id == gangID then
        -- Do Stuff Here
    end
end

---