All resources

rsg-gangs documentation#

For server owners and developers. Version 3.5.0.

Contents#

  1. Overview and architecture
  2. Files
  3. Configuration reference
  4. Database
  5. Ranks and permissions
  6. The gang wagon
  7. Camp equipment, crafting and the strongbox
  8. Territories, raids, upkeep and other features
  9. Server exports
  10. Events and callbacks
  11. Staff admin panel
  12. Integration examples
  13. Security model
  14. Server owner how-tos
  15. Troubleshooting

1. Overview and architecture#

rsg-society owns who is in a gang. A gang's name, label, colour, tag, owner, ranks, permissions, members and bank all live in rsg-society (3.1.0 or newer). rsg-gangs keeps the gameplay on top of it: the wagon, camp equipment, crafting, strongbox, territories, raids, upkeep, bounties, rivals, leaderboard and the staff panel. It reads the society data on demand (label, colour, tag, owner and bank are never copied) and keeps an in-memory list of members that rsg-society's events keep current. Members, ranks and money can be changed in either menu and both stay in step.

rsg-gangs keeps its own gameplay state on the server (RSGGangs.Gangs in server/main.lua) and mirrors it to the database. The NUI and the client scripts only send requests; every request is validated again on the server (membership, rank permission, distance, amounts, cooldown).

 NUI (html/)  ->  client/*.lua  ->  server net event / callback  ->  validation  ->  memory + database
                                                                         |
                                                       RSGGangs.BroadcastGangUpdate -> client:setState -> NUI

Props and the wagon are created by a player's client (not the server), and the server keeps a registry of them:

ThingSpawned byServer keepsRemoved by
Wagonnearest player within Config.RespawnProximityRadiusone registry entry per gang, kept alive by heartbeatsclients, when the server sends despawnGangWagon
Camp equipmentnearest player within Config.RespawnProximityRadiusequipmentEntities[gang][item][instance] = netIdserver DeleteEntity plus the owning client on stop

Dependencies: rsg-core, rsg-inventory, rsg-target, rsg-gizmo, rsg-wellpump, rsg-society, oxmysql. Optional integrations: rsg-log, rsg-reputation, rsg-bountyhunter. No ox_lib and no ox_target.


2. Files#

FilePurpose
fxmanifest.luaResource manifest and dependencies
shared/config.luaAll settings
server/main.luaGang state, database setup, ranks, bank, membership, exports, the shared RSGGangs helper table (cooldowns, grants, distance checks)
server/commands.luaPlayer and admin chat commands
server/wagon.luaWagon registry, heartbeats, parking-spot saving, spawn and despawn streaming
server/equipment.luaCamp equipment placement, packing and proximity streaming
server/crafting.luaCrafting at deployed stations and well pump bucket filling
server/stash.luaStrongbox stash and tier upgrades
server/features.luaTerritories, raids, upkeep, activity log, member blips, honor, bounties, rivalries, tags, leaderboard, webhook
server/admin.luaStaff panel callback rsg-gangs:server:admin and /gangadmin
server/sv_config.luaServer-only settings (Discord webhook)
server/versionchecker.luaOptional update check
client/main.luaNUI focus (with push-to-talk), state, NUI callbacks that forward to the server
client/vehicle.luaWagon spawn, wagon target, heartbeats, driving restriction, leftover-wagon sweep
client/equipment.luaProp spawn, rsg-gizmo placement, rsg-target options for stations, the well pump and the strongbox
client/crafting.luaOpens the crafting view
client/features.luaTerritory and member blips, log and territory NUI callbacks
client/admin.luaOpens the staff panel and relays NUI calls to the server callback
html/NUI: index.html, style.css, app.js (gang menu) and admin.css, admin.js (staff panel). All text comes from the locale files
locales/*.jsonen, de, el, es, fr, ja, nl, pl, pt-br, ro, ru (identical keys)
installation/rsg-gangs.sqlManual schema (kept identical to the automatic one)

3. Configuration reference#

Everything is in shared/config.lua unless stated.

OptionDefaultDescription
Config.AutoDatabasetrueCreate tables on start. false = import installation/rsg-gangs.sql yourself
Config.VersionChecktruePrint a console message when a newer version exists
Config.Command'setupgang'Command that opens the gang menu
Config.Adminenabledenabled, command ('gangadmin'), permission ('admin'), logLines (100)
Config.CreateGangCost5000Cash cost to found a gang
Config.MinNameLength / MaxNameLength3 / 20Gang name length
Config.MaxMembers15Member limit (0 = unlimited)
Config.MaxBankBalance2000000000Largest bank balance (database column is a signed 32-bit int)
Config.InviteExpireSeconds120How long an invite stays valid
Config.Ranks5 ranksOnly the staff panel's rank choices (name, label, weight = rank level, isLeader). The real ranks and permissions are set per gang in rsg-society
Config.GangColors10 hex coloursColours a gang can pick
Config.Notify.duration5000Notification length in ms
Config.Loggingdisabledenabled, channel (needs rsg-log)
Config.AllowPushToTalkWhileOpentrueKeep push-to-talk usable while the UI is open
Config.PushToTalkControls{ 0x4BC9DABB }Controls left active while the UI is open
Config.WagonInteractDistance40.0Max distance from the wagon for equipment actions and wagon reset
Config.StationInteractDistance6.0Max distance from a crafting station, the well pump or the strongbox
Config.GangVehiclesee belowWagon model, spawn search, driving restriction, target menu
Config.RespawnProximityRadius80.0A saved wagon or prop is only spawned when a player is this close
Config.DespawnProximityRadius100.0A spawned wagon or prop is removed when nobody is this close
Config.ProximityCheckInterval5000ms between streaming checks
Config.DebugWagonfalsePrint wagon spawn, save and despawn steps to the server console
Config.GangEquipment7 items (tent, torch, hitchingpost, campfire, crafttable, wellpump, strongbox)id, label, prop, initialDistance, maxPlacementDistance, maxDeployed
Config.WellPumpenabledWell pump targets on the wellpump equipment: equipmentId, targetIcon, drink, drinkIcon, requirePermission. Bucket items, uses, fill time and drinking are in rsg-wellpump
Config.CraftingenabledStations and recipes
Config.GangStashenabledStrongbox, minWeight, storage tiers
Config.ActivityLogenabledkeep (200), show (50), minWeight (2)
Config.MemberBlipsenabledinterval ms (3000)
Config.UpkeepenabledintervalHours (168), cost (2500), maxMissed (3)
Config.TerritoriesenabledmaxPerGang, incomeIntervalMinutes, requireOnlineMember, list
Config.ReputationenabledclaimAction, refreshMinutes (needs rsg-reputation)
Config.BountiesenabledminReward, maxReward, maxActive, expireHours, targetPlayers, targetGangs (needs rsg-bountyhunter 3.4.0+)
Config.RivalryenabledpairCooldownSeconds (300)
Config.RaidsenabledminAttackers, holdSeconds, durationSeconds, cooldownMinutes, protectMinutes, requireDefenderOnline
Config.TagsenabledminLength, maxLength
Config.Leaderboardenabledsize, turfPoints, killPoints, monthlyReset
SvConfig.WebhookdisabledIn server/sv_config.lua: Enabled, Url, Name, Actions

Config.GangVehicle:

Config.GangVehicle = {
    enabled = true,
    model = 'chuckwagon002x',
    spawnDistance = 6.0,   -- metres in front of the founder to try first
    checkRadius = 3.0,     -- area around the spawn point that must be clear
    maxAttempts = 6,       -- how many times the spawn point is pushed further out
    attemptStep = 2.5,     -- metres added per retry
    restrictDriving = true,
    useTargetMenu = true,  -- open the gang menu from a target on the wagon instead of the chat command
}

The server prints configuration warnings on start (duplicate rank names, missing items in recipes, unknown equipment ids). It never stops the resource for them.


4. Database#

Tables are created on start when Config.AutoDatabase = true. ensureDatabase in server/main.lua runs the same statements as installation/rsg-gangs.sql and adds missing columns (rsg_gang_members.name, rsg_gangs.upkeep_due, upkeep_missed, tag) with non-destructive ALTER TABLE statements after checking INFORMATION_SCHEMA. Keep the two schemas identical when you change one.

TableColumns
rsg_gangsname (key, the same as the rsg-society gang name), wagon_x/y/z/heading, stash_tier, stash_id, upkeep_due (unix time), upkeep_missed, created_at. label, color, owner and tag are only a mirror of rsg-society and bank is no longer used (the money is in rsg-society). The row is the anchor that the equipment, logs, territories, bounties and rivals tables point at
rsg_gang_membersRetired. Kept only so rsg-society can import old members once. rsg-gangs no longer reads or writes it
rsg_gang_equipmentid, gang_name, item_id, x, y, z, heading, created_at
rsg_gang_logsid, gang_name, citizenid, actor, action, detail, created_at
rsg_gang_rivalsgang_name, rival_name, kills (kills by the first gang against the second)
rsg_gang_statekey (primary key, season), value (current leaderboard season, e.g. 2026-11)
rsg_gang_bountiesid, gang_name, reward, target_type (player or gang), target_id (citizenid or gang name), target_name, created_at (escrow ledger)
rsg_gang_territoriesterritory_id (key), gang_name, claimed_at

Members, equipment, logs and territories are removed automatically when their gang row is deleted (foreign keys with ON DELETE CASCADE). The strongbox lives in rsg-inventory under rsg_gang_stash_<stash_id>; rsg-inventory keeps that inventory after a gang is disbanded.

The wagon's saved parking spot is rsg_gangs.wagon_x/y/z/heading.


5. Ranks and permissions#

Ranks and what they may do are set per gang in rsg-society (Ranks tab). A rank's level is its weight here (0 is the lowest, the boss rank is the highest) and a rank's name is whatever the gang called it. rsg-gangs asks rsg-society for every permission check; the boss rank always has every permission.

rsg-gangs permissionrsg-society permissionAllows
invitehireInvite players
kickfireKick lower-ranked members
promote, demotepromoteChange the rank of lower-ranked members
deposit, withdrawdeposit, withdrawGang bank
upgradeupgradeStrongbox upgrades, claim, abandon and raid territories
bountybountyPost gang bounties
rename, setcolorsettingsRename the gang, set its tag, change its colour
disbanddisbandDisband the gang
equipmentequipmentWagon reset, set up and pack away camp equipment, crafting

Rules enforced on the server:

  • You can only kick, promote or demote members of a lower rank level than your own, and a promotion can never reach your own level.
  • The leader cannot leave while others remain; use leadership transfer first. The last member leaving removes the gang, its wagon and its equipment.
  • Opening the strongbox needs Config.GangStash.minWeight.

To make a new rank (for example a Quartermaster who may use equipment and upgrade), open rsg-society's menu, go to the Ranks tab and tick equipment, upgrade, deposit and withdraw for it.


6. The gang wagon#

The wagon is the gang's base: the "manage outfit" target opens the menu, and equipment is placed relative to it.

Lifecycle#

  1. Creation. When a gang is founded the server issues the founder two single-use grants (spot:<gang> and wagon:<gang>) and sends rsg-gangs:client:findGangVehicleSpot. The client finds a clear spot, reports it (gangVehicleSpotFound, validated against the player's real position), and spawns the wagon.
  2. Registration. The spawning client reports the net id (gangWagonSpawned). The server accepts it only with the grant, checks model and type only when it can see the entity, and creates the registry entry. The client also tags the entity with the rsgGangWagon state bag.
  3. Heartbeats. Every client within 120 m of the wagon sends rsg-gangs:server:wagonHeartbeat every 4 seconds. Any nearby client keeps the entry alive. Heartbeats from a member of the owning gang also update the live position, and when the wagon is standing still and no camp equipment is deployed, the new parking spot is written to the database.
  4. Despawn. When nobody is within Config.DespawnProximityRadius, the server drops the entry and broadcasts rsg-gangs:client:despawnGangWagon. Clients that have the entity delete it (asking for network control first).
  5. Respawn. When no entry exists and a player comes within Config.RespawnProximityRadius of the saved spot, the server grants that player the right to register a wagon and asks them to spawn it. The same happens when heartbeats stop for 20 seconds (destroyed wagon).
  6. Restart. On stop each client deletes the wagons it controls and removes the wagon target. The position was already saved by the heartbeats. On start, clients delete any wagon carrying the rsgGangWagon state bag that is not in the current registry (it must be seen that way on two checks in a row). The streaming loop then spawns a fresh one at the saved spot.

The server never needs to see the wagon entity, which is why saving and cleanup keep working even when server-side entity lookups of client-spawned vehicles fail.

The target#

The "manage outfit" option is registered once on the wagon model with exports['rsg-target']:addModel. Every client gets it, and it survives respawns and restarts. canInteract only shows it to members of the gang that owns that wagon (looked up by net id in the registry).

Restrictions#

  • restrictDriving: players outside the owning gang are forced out of the driver seat.
  • A gang member cannot drive the wagon while camp equipment is deployed (pack it away first), because equipment stays at its own position.
  • Camp equipment is never moved with the wagon. The parking spot is not saved while equipment is deployed.

Admin tools#

/setgangwagon <gang> (or the staff panel) saves your position as the wagon spot and removes the current wagon so it respawns there. The staff panel can also clear the spot.

Debugging#

Set Config.DebugWagon = true. Typical log for a restart:

[rsg-gangs:wagon] asked 1 to spawn the wagon of rex_gang
[rsg-gangs:wagon] registered wagon of rex_gang net id 74
[rsg-gangs:wagon] saved parking spot for rex_gang -155.69 541.06 114.81

7. Camp equipment, crafting and the strongbox#

Equipment#

Config.GangEquipment lists the items a gang can set up. id is the stable key used in the database and the recipe/stash links, so never rename an id that is in use.

{
    id = 'torch',
    label = 'Camp Torch',
    prop = 'p_torchpost01x',          -- prop model
    initialDistance = 2.0,            -- metres in front of the player where the ghost starts
    maxPlacementDistance = 10.0,      -- final spot must be within this of the wagon (server-enforced)
    maxDeployed = 5,                  -- how many can be out at once (server-enforced)
},

Placement flow (every step is checked on the server):

  1. deployEquipment(itemId): member with equipment, within Config.WagonInteractDistance of the wagon, below maxDeployed, no other placement in progress for that gang and item. The server issues a placement grant and tells the client to start rsg-gizmo.
  2. equipmentPlaced(itemId, coords, heading): consumes the grant, re-validates the spot (close to the wagon and to the player), inserts the row and asks a nearby client to spawn the prop.
  3. equipmentSpawned(...): the spawning client registers the prop with a single-use grant.
  4. packEquipment(itemId): removes the most recently placed instance.

Props only exist while a player is within Config.RespawnProximityRadius.

Crafting#

Stations are Config.Crafting.stations, each tied to an equipment id:

{
    id = 'campfire_cook',
    equipmentId = 'campfire',
    label = 'Campfire',
    targetLabel = 'Cook',
    targetIcon = 'fas fa-fire',
    intro = 'Cook food over the fire using ingredients from your own saddlebag.',
    recipes = {
        {
            id = 'cooked_meat',
            label = 'Cooked Meat',
            ingredients = { { item = 'raw_meat', amount = 1 } },
            output = { item = 'cooked_meat', amount = 1 },
        },
    },
},

The server checks permission, that the gang has the station deployed, that the player is next to it, the ingredients, and CanAddItem for the output. Ingredients are refunded if the reward cannot be given.

Well pump#

The wellpump equipment item (p_wellpumpnbx01x) gets Fill Bucket and Drink Water targets. Only members of the gang that owns the pump see it. The bucket logic lives in rsg-wellpump (a required dependency): it plays the animation, swaps the items and sets the uses on the filled bucket, so the bucket works the same in every resource. Which items, how many uses and how long the fill takes are set in rsg-wellpump's Config.EmptyItem, Config.FullItem, Config.BucketUses and Config.FillTime.

Config.WellPump in rsg-gangs:

Config.WellPump = {
    enabled = true,
    equipmentId = 'wellpump',    -- the Config.GangEquipment id
    targetIcon = 'fa-solid fa-droplet',
    drink = true,                -- also show Drink Water
    drinkIcon = 'fa-solid fa-glass-water',
    requirePermission = false,   -- true = only ranks with 'equipment'
}

Flow: the target calls exports['rsg-wellpump']:PlayFill() on the client (checks for an empty bucket, plays the progress bar), then fires rsg-gangs:server:fillBucket. The server checks the rate limit (80% of rsg-wellpump's fill time), gang membership, the optional equipment permission, that the gang has a pump deployed and that the player is next to it. Only then does it call exports['rsg-wellpump']:FillBucket(src).

Drinking works the same way: the client calls exports['rsg-wellpump']:PlayDrink() (checks thirst, plays the animation), then fires rsg-gangs:server:drinkWater. After the same gang and distance checks the server calls exports['rsg-wellpump']:Drink(src), which enforces rsg-wellpump's drink cooldown, picks the thirst amount and raises thirst on the client.

Strongbox#

Config.GangStash ties the stash to the strongbox equipment. Tiers (slots, maxWeight, upgradeCost) are bought with gang bank money by members with upgrade. The upgrade charges the bank and sets the tier in one SQL statement.


8. Territories, raids, upkeep and other features#

  • Activity log. RSGGangs.AddLog(gang, citizenid, action, ...) stores a row; the UI renders it with the log_<action> locale key, filling %s from the |-separated detail. Readable from Config.ActivityLog.minWeight. Rows are pruned to keep every 30 minutes.
  • Territories. claimTerritory(id) and abandonTerritory(id) need upgrade. A claim checks the config entry, that the player is inside the radius (server position), the per-gang limit, that the turf is free and the bank balance. The row is inserted with INSERT IGNORE first so two gangs cannot both win. Income is paid every incomeIntervalMinutes (only while a member is online when requireOnlineMember is true). Turf is freed when a gang is destroyed.
  • Raids. startRaid(id) needs upgrade, an owned unprotected territory of another gang, the caller inside it, minAttackers raiders inside, a defender online (if configured), and no active raid or cooldown. Every 5 seconds the server counts members inside (server positions); time counts toward holdSeconds only while attackers out-number defenders. Reaching it transfers ownership and starts protection; running out durationSeconds first defends it.
  • Upkeep. Checked every minute. When upkeep_due passes, the cost is taken from the bank. A failed payment adds to upkeep_missed; at maxMissed the gang is disbanded.
  • Member blips. The server sends each member only the positions of the other online members of their own gang, plus the live wagon position. Positions come from the server. Each player can hide themselves (client KVP, sent with setBlips).
  • Reputation. Gang honor is the rounded average of exports['rsg-reputation']:GetHonorByCitizenId over the members, refreshed every Config.Reputation.refreshMinutes. A territory claim calls ApplyAction(src, claimAction, region).
  • Rivalries. Listens to the server-only RSGCore:Server:OnPlayerKilled. A kill between members of two different gangs adds 1 to rsg_gang_rivals; the same killer and victim count once per pairCooldownSeconds.
  • Bounties. A bounty always names a target: one online player, or a rival gang. In the gang UI the member enters the amount, picks Player or Rival gang, and chooses the target from an HTML dropdown filled by the rsg-gangs:server:bountyTargets callback (players are listed by character name and sent back as server ids, gangs by label and sent back as gang names; the callback needs bounty). postBounty(amount, targetType, targetId) needs bounty and checks, on the server: the amount range, that the target still exists, that it is not the player themselves or anyone in the posting gang, that the gang has no bounty on that target already, maxActive, and the bank balance. Posts from one gang are serialised so two members cannot slip past maxActive. The amount moves from the bank into escrow (rsg_gang_bounties) and rsg-bountyhunter:PostBounty is called inside a pcall with targetCitizenid (player) or targetGang (gang), targetName and sponsorGang; if it fails the escrow is returned. A hunter follows a moving search area on the map and brings the target (or, for a gang bounty, any online member of that gang) to a sheriff's office dead, hogtied or cuffed. Members of the posting gang cannot take their own bounty, and a hunter cannot take a bounty on their own gang. When the poster closes, rsg-bountyhunter fires the server-only event rsg-bountyhunter:server:posterClosed(ref, reason, paid): on completed the unpaid remainder returns to the bank, otherwise the full amount does. Escrow left over from a restart is refunded on start. rsg-bountyhunter reads gang membership through the GetPlayerGang and GetGangOnlineSources exports.
  • Tags. setTag(tag) needs rename; it upper-cases, strips non-alphanumerics and checks minLength..maxLength.
  • Leaderboard. Score = turf x turfPoints + rival kills x killPoints. With monthlyReset, the first check in a new calendar month clears rsg_gang_rivals (the current season is stored in the rsg_gang_state table, not in resource KVP).
  • Webhook. server/sv_config.lua is server-only so the URL never reaches players. Messages are queued (one per 1.5 s, 50 max) and sent with allowed_mentions = { parse = {} }, so gang names cannot ping anyone. Only actions listed in SvConfig.Webhook.Actions are sent.

9. Server exports#

ExportReturns
GetPlayerGang(citizenid){ name, label, color, rank, level } or nil (rank is the rank name from rsg-society, level its number)
GetGangData(gangName)Full gang payload (label, color, bank, members, equipment, stash tiers, territories, ...) or nil
IsGangLeader(citizenid)boolean
HasGangPermission(citizenid, permission)boolean
GetGangMembers(gangName)List of { citizenid, name, rank, rankLabel, weight, online } or nil
GetGangBank(gangName)Balance or nil (the rsg-society account balance)
AddGangBank(gangName, amount, reason?)true on success (whole positive amount, capped by Config.MaxBankBalance); recorded in the rsg-society ledger
RemoveGangBank(gangName, amount, reason?)true on success (fails when funds are short)
GetGangTag(serverId)The player's gang tag or nil
GetGangOnlineSources(gangName)List of server ids of the gang's online members (empty if the gang does not exist); used by rsg-bountyhunter for gang bounties
-- Who is this player, and are they allowed to do the thing?
local Player = RSGCore.Functions.GetPlayer(src)
local citizenid = Player.PlayerData.citizenid

local gang = exports['rsg-gangs']:GetPlayerGang(citizenid)
if gang and exports['rsg-gangs']:HasGangPermission(citizenid, 'withdraw') then
    print(('%s is in %s as %s'):format(citizenid, gang.label, gang.rank))
end
-- Spend gang money, hand over the goods only when it worked
local ok = exports['rsg-gangs']:RemoveGangBank('delobo', 250, 'ammo order')
if ok then
    exports['rsg-inventory']:AddItem(src, 'ammo_rifle', 20, nil, nil, 'gang-ammo-order')
end

Other scripts that move gang money must do their own distance and permission checks first.


10. Events and callbacks#

Client-to-server events are internal. They are all validated and rate limited, and other resources should use the exports instead.

Server net events (rsg-gangs:server:*)#

EventArgumentsNeeds
requestStatenonein game
createGanglabelcash, not in a gang
disbandGangnonedisband
invitePlayerserverIdinvite
acceptInvite, declineInvitenonea pending invite
kickMember, promoteMember, demoteMember, transferLeadershipcitizenidkick / promote / demote / leader
leaveGangnonemember
depositMoney, withdrawMoneyamountdeposit / withdraw
renameGang, setColor, setTaglabel / color / tagrename / setcolor / rename
deployEquipment, packEquipmentitemIdequipment, near the wagon
equipmentPlaced, equipmentPlacementCancelled, equipmentSpawnedplacement dataserver grant
requestEquipmentRegistrynonecooldown
craftItemstationId, recipeIdequipment, near the station
openGangStash, upgradeGangStashnoneConfig.GangStash.minWeight / upgrade
resetWagonnoneequipment, near the wagon, 30 s cooldown
gangVehicleSpotFound, gangVehicleSpotFailed, gangWagonSpawnedwagon dataserver grant
wagonHeartbeatgang, netId, coords, heading, stationarynearby client
gangWagonMovedgang, coords, headingnearby gang member
requestWagonRegistrynonecooldown
claimTerritory, abandonTerritory, startRaidterritoryIdupgrade
requestTerritories, requestLogs, requestLeaderboardnonemember / rank
postBountyamount, targetType (player or gang), targetId (server id or gang name)bounty
setBlipsenabledcooldown

Server to client events (rsg-gangs:client:*)#

EventPurpose
setState(state)Full UI state for the player
openMenu, closeMenu, openCraftMenu(stationId), openAdminUI control
requestAccept, requestDeclineChat command relays
findGangVehicleSpot(gang), spawnGangWagonAt(gang, wagon), despawnGangWagon(gang, netId)Wagon spawn control
wagonRegistered, wagonUnregistered, wagonRegistrySyncWagon registry
spawnEquipmentAt, startEquipmentPlacement, equipmentRegistered, equipmentUnregistered, equipmentRegistrySyncEquipment control
territories, memberBlips, logs, leaderboardMap and tab data
adminTeleport(x, y, z)Staff teleport

Callbacks (rsg-core)#

CallbackDirectionPurpose
rsg-gangs:server:admin(action, payload)client to serverStaff panel (see section 11)

State bag#

Entity(wagon).state.rsgGangWagon = <gangName> marks a wagon spawned by this resource.

NUI callbacks#

close, refresh, createGang, disbandGang, invitePlayer, kickMember, leaveGang, promoteMember, demoteMember, transferLeadership, depositMoney, withdrawMoney, renameGang, setColor, deployEquipment, packEquipment, upgradeGangStash, resetWagon, craftItem, declineInvite, setBlips, requestLeaderboard, startRaid, setTag, requestLogs, postBounty, bountyTargets, claimTerritory, abandonTerritory, adminCall, adminClose. Each one only forwards to the matching server event; bountyTargets instead awaits the rsg-gangs:server:bountyTargets callback and returns its list to the dropdown.


11. Staff admin panel#

Opened with /gangadmin (Config.Admin.command, permission Config.Admin.permission, default admin). All traffic goes through the rsg-core callback rsg-gangs:server:admin(action, payload), which returns { ok = true, ... } or { ok = false, error = <localised text> }. The server re-checks the permission on every call, rate limits (150 ms reads, 500 ms writes) and runs the handler under pcall.

ActionPayloadEffect
snapshotnoneStats, all gangs, territories, ranks, stash tiers, colours and limits
gangnameGang detail (members, equipment, territories, upkeep) plus recent log
playersnoneOnline players with their gang
createGang, deleteGang, renameGang, setTag, setColorname, label/tag/colorGang lifecycle and look
bankname, mode (add/remove/set), amountBank change, capped by Config.MaxBankBalance
setStashname, tierSet the strongbox tier
resetUpkeepnameClear missed cycles and reschedule
addMember, removeMember, setRank, transferLeadername, citizenid/id, rankMembership and ranks
setWagonHere, clearWagon, packEquipment, clearRivalsnameAssets and rivalry data
setTerritoryid, gang or noneAssign or free turf (also ends a raid and clears protection)
teleportkind (wagon/territory), name/idStaff member goes to the spot

Each change adds an admin entry to the gang's activity log and an rsg-log entry.


12. Integration examples#

Pay a gang from a heist script#

-- server side of your heist resource
RegisterNetEvent('myheist:server:finish', function()
    local src = source
    local Player = RSGCore.Functions.GetPlayer(src)
    if not Player then return end

    -- your own checks first: did this player really finish the heist, are they near the vault, cooldown...
    local gang = exports['rsg-gangs']:GetPlayerGang(Player.PlayerData.citizenid)
    if gang then
        exports['rsg-gangs']:AddGangBank(gang.name, 1500, 'bank heist')
    end
end)

Show the gang tag in a chat or name resource#

local tag = exports['rsg-gangs']:GetGangTag(source) -- 'DLB' or nil
local name = tag and ('[%s] %s'):format(tag, playerName) or playerName

Gate a feature on a gang permission#

local function canUseGangArmoury(citizenid)
    return exports['rsg-gangs']:HasGangPermission(citizenid, 'equipment')
end

Open the gang menu from another script#

-- client side: the menu is a normal client event
TriggerEvent('rsg-gangs:client:openMenu')

Webhook setup (server/sv_config.lua)#

SvConfig.Webhook = {
    Enabled = true,
    Url = 'https://discord.com/api/webhooks/...',
    Name = 'rsg-gangs',
    Actions = { created = true, raid_won = true, raid_lost = true, territory_claim = true },
}

13. Security model#

  • Every action re-checks rank, permission and gang membership on the server. The NUI only sends requests.
  • Amounts must be whole, positive, finite and within limits. Bank changes update memory first and the database with a delta, so overlapping updates cannot overwrite each other. Deposits and withdrawals refund on failure.
  • Names, tags and labels are cleaned (control characters and markup removed) and length checked. The NUI escapes all text before inserting it. The Discord webhook sends allowed_mentions = { parse = {} }.
  • Per-player cooldowns on every action (RSGGangs.OnCooldown), cleared when the player leaves.
  • Grants. The server issues single-use, time-limited grants (RSGGangs.Grant / ConsumeGrant) for things a client may report once: the wagon or prop it was asked to spawn, a placement it was approved to start. A client cannot invent these reports.
  • Wagon. A wagon registration needs the grant. Heartbeats and parking reports must come from a player within 150 m of the reported position, and only members of the owning gang can change the saved spot.
  • Equipment. Placement needs the player at the wagon, a server grant, a spot within maxPlacementDistance, and respects maxDeployed.
  • Filling a bucket needs the player next to the gang's own deployed well pump; the server rate-limits it to the fill time, and rsg-wellpump checks the empty bucket and refunds it if the full one cannot be added.
  • Crafting and the stash need the player next to the gang's own deployed station; CanAddItem is checked and ingredients are refunded if the reward cannot be given.
  • The staff panel is server-gated by an rsg-core permission on every call.
  • Invites expire and are cleared when a gang is disbanded.
  • Territory ownership is reserved in memory before the database write, so two gangs cannot claim the same turf.
  • Bounty escrow is returned if rsg-bountyhunter errors.

14. Server owner how-tos#

  • Add equipment: add an entry to Config.GangEquipment with a unique id, a prop, maxPlacementDistance and maxDeployed.
  • Change what the pump gives: edit Config.EmptyItem, Config.FullItem and Config.BucketUses in rsg-wellpump; both items must exist in your rsg-core items.
  • Add a recipe: add it to a station in Config.Crafting.stations; its items must exist in your rsg-core items. The server prints a warning on start for missing items.
  • Add a territory: add { id, label, coords, region, radius, claimCost, income } to Config.Territories.list. Entries with bad coordinates or duplicate ids are ignored with a console warning.
  • Change the language: setr rsg:locale <code>.
  • Move a wagon: stand where it should be and run /setgangwagon <gang>, or drive it there and leave it (the spot is saved after it has stood still for a few seconds, as long as no camp equipment is deployed).
  • Push-to-talk while the UI is open: Config.AllowPushToTalkWhileOpen and Config.PushToTalkControls.
  • Logging: set Config.Logging.enabled = true and a channel that exists in rsg-log.
  • Manual database install: Config.AutoDatabase = false, then import installation/rsg-gangs.sql.

15. Troubleshooting#

ProblemFix
"Failed to load gangs" in the consoleTables are missing: enable Config.AutoDatabase or import the SQL
Wagon has no targetrsg-target must start before rsg-gangs; you must be in the gang that owns the wagon
Wagon never appearsCheck Config.GangVehicle.enabled; stand within Config.RespawnProximityRadius of the saved spot; use /setgangwagon if the spot is bad; turn on Config.DebugWagon
Wagon returns to its old spot after a restartCamp equipment is deployed (the spot is not saved then); pack it away, move the wagon, wait a few seconds
An old wagon is left standing after a restartA wagon spawned by an older version has no tag; remove it once by hand or restart the server
Two wagons for one gangShould not happen; turn on Config.DebugWagon and send the console lines
No "Fill Bucket" option on the well pumpDeploy the pump (wellpump) first; be in the gang that owns it; Config.WellPump.enabled must be true; rsg-target and rsg-wellpump must start before rsg-gangs
Placement does nothingrsg-gizmo must be started; stay within the placement range of the wagon
Config warning about an itemAdd the item to your items list or fix the recipe
/gangadmin says no permissionGive the player the rsg-core permission in Config.Admin.permission
Staff panel text missingLocale keys admin_*, ui_adm_* must exist in the active language file
Ranks cannot upgrade storageAdd 'upgrade' to that rank's permissions
Ranks cannot post bountiesAdd 'bounty' to that rank's permissions
Bounty dropdown is emptyNo other player is online (player bounties) or no other gang exists (gang bounties); Config.Bounties.targetPlayers / targetGangs can also be off
Bounty board shows no gang bountiesrsg-bountyhunter must be 3.4.0+ and started; older versions ignore the target fields
Upgrading: rsg_gang_bounties has no target columnsThey are added automatically on start. For a manual install run ALTER TABLE rsg_gang_bounties ADD COLUMN target_type varchar(10) NOT NULL DEFAULT 'player', ADD COLUMN target_id varchar(50) DEFAULT NULL, ADD COLUMN target_name varchar(100) DEFAULT NULL;

Support: https://rexshack.tebex.store