Server Exports

In these examples, source is the player's server ID.
Some exports accept a citizen ID. This is the character identifier (citizenid on QB / Qbox, identifier on ESX).

👥 Gangs & Members

GetGangs

Returns a list of every gang.

local gangs = exports['kartik-gangs']:GetGangs()
for _, g in ipairs(gangs) do
    print(g.id, g.name, g.level, g.online .. '/' .. g.members)
end

Each gang has: id, name, color, logo, level, xp, members, online.

GetGang

Returns one gang's details, or nil.

local gang = exports['kartik-gangs']:GetGang(gangId)

Field	Description
`id`, `name`, `color`, `logo`	Gang identity
`level`, `xp`	Progression
`cash`, `dirty`	Treasury balances
`upgrades`	Upgrade levels
`stats`	Gang statistics
`ranks`	Rank list (same as `GetGangRanks`)
`members`, `online`	Member counts
`createdAt`	When the gang was created

GetGangRanks

Returns a gang's ranks, highest first.

local ranks = exports['kartik-gangs']:GetGangRanks(gangId)

Each rank has: priority, label, perms, members.

GetPlayerGang

Returns an online player's gang, or nil.

local gang = exports['kartik-gangs']:GetPlayerGang(source)
if gang then
    print(gang.name, gang.rank, gang.isLeader)
end

Fields: id, name, color, logo, level, rank, priority, isLeader, alias, cid.

GetGangByCid

Same as GetPlayerGang, but works for offline characters using their citizen ID.

local gang = exports['kartik-gangs']:GetGangByCid('ABC12345')

IsPlayerInGang

Returns true if the player is in any gang, or in a specific gang when you pass a gang ID.

local inAny = exports['kartik-gangs']:IsPlayerInGang(source)
local inThis = exports['kartik-gangs']:IsPlayerInGang(source, gangId)

HasGangPermission

Returns true if the player's rank has a permission.

if exports['kartik-gangs']:HasGangPermission(source, 'treasury') then
    -- allowed
end

GetGangMembers

Returns every member of a gang.

local members = exports['kartik-gangs']:GetGangMembers(gangId)

Each member has: cid, name, alias, rank, priority, isLeader, online, source (if online), joinedAt, lastSeen.

GetOnlineGangMembers

Returns the server IDs of a gang's online members.

for _, playerId in ipairs(exports['kartik-gangs']:GetOnlineGangMembers(gangId)) do
    TriggerClientEvent('ox_lib:notify', playerId, { description = 'Meeting at the hideout' })
end

SetPlayerGang

Adds a player to a gang, or changes their rank if they're already in it. Accepts a server ID or citizen ID. The rank is optional and defaults to the lowest.

local ok, err = exports['kartik-gangs']:SetPlayerGang(source, gangId, 3)

Returns true, or false and an error reason.

RemovePlayerFromGang

Removes a player from their gang. Accepts a server ID or citizen ID.

exports['kartik-gangs']:RemovePlayerFromGang(source)

CreateGang

Creates a new gang. Returns the new gang ID, or nil and an error reason.

local gangId, err = exports['kartik-gangs']:CreateGang({
    name = 'Ballas',
    color = '#a855f7',
    logo = '',             -- optional image URL
    bossLabel = 'OG',      -- optional leader rank name
    leader = source,       -- optional server ID or citizen ID
})

DeleteGang

Permanently deletes a gang with all its members and ranks.

exports['kartik-gangs']:DeleteGang(gangId)

💰 Money, XP & Stats

AddGangMoney / RemoveGangMoney

Adds money to or removes money from a gang treasury. See account names.

exports['kartik-gangs']:AddGangMoney(gangId, 'cash', 5000)
exports['kartik-gangs']:AddGangMoney(gangId, 'dirty', 12000)

local ok = exports['kartik-gangs']:RemoveGangMoney(gangId, 'cash', 2500)

RemoveGangMoney returns false if the gang doesn't have enough.

AddGangXp

Gives a gang XP. A negative amount takes XP away.

exports['kartik-gangs']:AddGangXp(gangId, 250, 'heist')

AddGangStat

Increases one of a gang's statistics. Built-in stats include captures, contracts, warsWon, sprays, rackets and drugSales, but you can use your own names too.

exports['kartik-gangs']:AddGangStat(gangId, 'heists', 1)

🗺️ Territory

GetTurfAt

Returns the turf at a position, or nil.

local turf = exports['kartik-gangs']:GetTurfAt(GetEntityCoords(GetPlayerPed(source)))
if turf then
    print(turf.id, turf.label, turf.owner)
end

Fields: id, label, owner (gang ID or nil).

GetPlayerTurf

Same as GetTurfAt, using the player's position.

local turf = exports['kartik-gangs']:GetPlayerTurf(source)

GetTurfOwner

Returns the gang ID that owns a turf, or nil.

local ownerId = exports['kartik-gangs']:GetTurfOwner(turfId)

GetTurfShares

Returns every gang's influence in a turf, highest first.

for _, s in ipairs(exports['kartik-gangs']:GetTurfShares(turfId)) do
    print(s.name, s.points, s.percent .. '%')
end

Each entry has: gangId, name, color, points, percent.

IsPlayerTurfOwner

Returns true if the player's gang owns the turf.

local owns = exports['kartik-gangs']:IsPlayerTurfOwner(source, turfId)

AddTurfInfluence

Adds (or with a negative amount, removes) a gang's influence in a turf.

exports['kartik-gangs']:AddTurfInfluence(turfId, gangId, 100, 'event')

IsTurfInRivalry

Returns true if a rivalry is running on the turf.

local rivalry = exports['kartik-gangs']:IsTurfInRivalry(turfId)

🚨 Street Crime

ReportRobbery

Call this from your robbery script when a player robs something. Inside a turf, it affects influence, alerts police and lowers nearby racket payouts.

exports['kartik-gangs']:ReportRobbery(source, 'store')

Instead of using the export, you can list your robbery script's events in shared/territory.lua under Crimes → Robbery → Events.

ReportVehicleTheft

Call this from a car theft or hotwire script. Normal car jackings are already detected automatically.

exports['kartik-gangs']:ReportVehicleTheft(source, NetworkGetNetworkIdFromEntity(vehicle))

Drug Sales

DrugSold

Report a drug sale from your own drug script. It then counts towards turf influence, drug wars, rivalries and contracts.

-- source, item, amount, total price
exports['kartik-gangs']:DrugSold(source, 'weed', 2, 180)

BusinessSale

Report a sale from another business script (restaurant, shop, player business). The gang that owns the turf gets a cut, stored at the nearest racket shop for members to collect. See Rackets.

-- where: player source, or coords (vector3) when nobody is at the business
-- returns the cut given to the gang (0 when no gang owns the turf)
local cut = exports['kartik-gangs']:BusinessSale(source, 1500, 'burgershot')

Argument	Meaning
`where`	Player server ID, or a `vector3` of the business
`amount`	Sale amount
`business`	Business name, used for per-business cuts in `Rackets.BusinessSales.Businesses`

Tax or bonus: take the returned cut off the sale, or ignore it.

-- Tax: the business owner gets less
local cut = exports['kartik-gangs']:BusinessSale(source, price, 'burgershot')
payBusiness(price - cut)

-- Bonus: the business keeps everything, the gang's cut is extra
exports['kartik-gangs']:BusinessSale(source, price, 'burgershot')
payBusiness(price)

GetCornerHeat

Returns a player's corner selling heat (0 – 100).

local heat = exports['kartik-gangs']:GetCornerHeat(source)

📜 External contracts

Put your own job on every gang's Contracts page. Your resource runs the gameplay. Gangs handles the level lock, start permission, cooldowns, time limit, XP, rewards and the HUD.

External contracts are always listed. They aren't part of the daily random board. If your resource stops, its contracts are removed and any running ones fail.

RegisterExternalContract

exports['kartik-gangs']:RegisterExternalContract('bank_job', {
    label = 'Fleeca Job',
    description = 'Hit the Fleeca on Route 68 and get away clean.',
    level = 5,
    xp = 400,
    timeoutMinutes = 30,
    cooldownMinutes = 20,
    steps = 3,                    -- only for the "3 steps" label on the card
    image = 'https://…/fleeca.png',
    rewards = {
        { kind = 'cash', amount = 25000, label = '$25,000', rarity = 'purple' },
    },
})

Returns true when registered. You can't replace a built-in contract, or one registered by another resource. rewards uses the same format as contract files.

Your resource must export GangContractCanStart. It's called when a member presses Start:

exports('GangContractCanStart', function(src, key, gangId)
    if bankOnCooldown() then return false, 'The bank was hit recently.' end -- message shown to the player
    return true
end)

Running the job

Listen for the start and end events, then report the result:

AddEventHandler('kartik-gangs:externalContractStarted', function(key, src, runId, gangId)
    if key ~= 'bank_job' then return end
    startBankJob(src, runId)
end)

AddEventHandler('kartik-gangs:externalContractEnded', function(key, runId, status, reason)
    if key ~= 'bank_job' then return end
    cleanupBankJob(runId) -- timed out, abandoned, cancelled by an admin…
end)

Export	What it does
`CompleteExternalContract(runId, src)`	Finish the run. `src` is the player who finished it (gets item rewards)
`FailExternalContract(runId, reason)`	Fail the run. The contract goes on cooldown
`UnregisterExternalContract(key)`	Remove your contract from the page

exports['kartik-gangs']:CompleteExternalContract(runId, source)
exports['kartik-gangs']:FailExternalContract(runId, 'mission_failed')

🏆 Leaderboard

GetLeaderboard

Returns the live standings of the current weekly or monthly period, or nil if that period isn't running.

local rows = exports['kartik-gangs']:GetLeaderboard('weekly') -- or 'monthly'
for _, r in ipairs(rows or {}) do
    print(r.rank, r.name, r.score, r.eligible)
end

Each row has: rank, id, name, color, logo, level, score, eligible (meets the prize tier).

🪢 Restraints

IsPlayerRestrained

local tied = exports['kartik-gangs']:IsPlayerRestrained(source)

IsPlayerBagged

local bagged = exports['kartik-gangs']:IsPlayerBagged(source)

FreePlayer

Unties the player, removes their head bag and stops any escort.

exports['kartik-gangs']:FreePlayer(source)

📍 Tablet Map Markers

AddMapBlip

Adds a marker to the tablet map. It's removed automatically when your resource stops.

exports['kartik-gangs']:AddMapBlip('my_heist', {
    coords = vector3(254.0, 225.0, 101.0),
    label = 'Pacific Standard',
    description = 'Vault is open',
    icon = 'fa-solid fa-sack-dollar',
    color = '#22c55e',
    gangs = { 1, 4 },   -- optional: only these gangs see it
})

RemoveMapBlip

exports['kartik-gangs']:RemoveMapBlip('my_heist')

🚗 Garages

GetGangGarage

For garage scripts: returns the gang garage behind a garage ID, or nil.

local garage = exports['kartik-gangs']:GetGangGarage('kg_gang_3')
if garage then
    print(garage.gangId, garage.label)
end

Server Exports

👥 Gangs & MembersCopy Anchor Link

GetGangsCopy Anchor Link

GetGangCopy Anchor Link

GetGangRanksCopy Anchor Link

GetPlayerGangCopy Anchor Link

GetGangByCidCopy Anchor Link

IsPlayerInGangCopy Anchor Link

HasGangPermissionCopy Anchor Link

GetGangMembersCopy Anchor Link

GetOnlineGangMembersCopy Anchor Link

SetPlayerGangCopy Anchor Link

RemovePlayerFromGangCopy Anchor Link

CreateGangCopy Anchor Link

DeleteGangCopy Anchor Link

💰 Money, XP & StatsCopy Anchor Link

AddGangMoney / RemoveGangMoneyCopy Anchor Link

AddGangXpCopy Anchor Link

AddGangStatCopy Anchor Link

🗺️ TerritoryCopy Anchor Link

GetTurfAtCopy Anchor Link

GetPlayerTurfCopy Anchor Link

GetTurfOwnerCopy Anchor Link

GetTurfSharesCopy Anchor Link

IsPlayerTurfOwnerCopy Anchor Link

AddTurfInfluenceCopy Anchor Link

IsTurfInRivalryCopy Anchor Link

🚨 Street CrimeCopy Anchor Link

ReportRobberyCopy Anchor Link

ReportVehicleTheftCopy Anchor Link

Drug SalesCopy Anchor Link

DrugSoldCopy Anchor Link

BusinessSaleCopy Anchor Link

GetCornerHeatCopy Anchor Link

📜 External contractsCopy Anchor Link

RegisterExternalContractCopy Anchor Link

Running the jobCopy Anchor Link

🏆 LeaderboardCopy Anchor Link

GetLeaderboardCopy Anchor Link

🪢 RestraintsCopy Anchor Link

IsPlayerRestrainedCopy Anchor Link

IsPlayerBaggedCopy Anchor Link

FreePlayerCopy Anchor Link

📍 Tablet Map MarkersCopy Anchor Link

AddMapBlipCopy Anchor Link

RemoveMapBlipCopy Anchor Link

🚗 GaragesCopy Anchor Link

GetGangGarageCopy Anchor Link

On this page