Installation Guide
Step-by-step setup for oxide-gangs — prerequisites, load order, database, admin permissions, the minimap file, and first-time setup in game.
This guide takes you from a fresh download to a working gang system. Follow it in order and you will be running in about ten minutes. You do not need to know how to program.
Prerequisites
Required resources
| Resource | Minimum Version | Purpose |
|---|---|---|
ox_lib | 3.32.0+ | Text used by the resource (translations), shared runtime |
oxmysql | 2.12.0+ | The database driver — the piece that lets a resource talk to your MySQL database |
o-link | 1.6.6+ | The bridge that lets this resource run on any framework. Update to the latest release whenever you update this resource |
| Framework | latest | One of qb-core, qbx_core, or es_extended |
o-link 1.6.6 or newer is required
1.6.6 is the release that completed the gang side of the bridge. On 1.6.5 and older, four of the functions listed in the API Reference are missing altogether, so a script that calls one errors rather than falling back quietly. Some admin tools (like the Entity picker) also need the newest o-link.
Recommended resources
| Resource | Why you want it |
|---|---|
| An inventory | The gang base stash needs one. Any inventory o-link supports works — ox_inventory, qb-inventory, qs-inventory, ps-inventory, codem-inventory, core_inventory, origen_inventory, tgiann-inventory, jpr-inventory, hex_4_inventory, ak47_qb_inventory. Without one, everything else still works and members are told the stash is unavailable. |
| A target resource | The stash and garage points at a gang base are interaction points you walk up to and press a key on. Any target resource o-link supports works — ox_target, qb-target, tgiann-target, or sleepless_interact. Without one, those points cannot be used. |
Optional resources
None of these are needed. Install them and the matching feature switches itself on.
| Resource | What it adds |
|---|---|
oxide-dispatch | Territory and war alerts become proper dispatch calls with blips and a response list |
oxide-radio | A private radio channel per gang, locked to its members |
oxide-banking | Gang treasuries held as real gang_<name> bank accounts instead of a plain balance |
oxide-police | A Gang Intel tab in the police MDT showing gangs, turf, and wars |
oxide-blackmarket | Extra reputation for selling on your own gang's turf |
oxide-weed, oxide-meth, oxide-cocaine, oxide-drugselling | Territory modifiers tune yield, growth speed, sale price, and buyer density per district |
Supported frameworks
| Framework | Support |
|---|---|
QBCore (qb-core) | Full |
QBX / Qbox (qbx_core) | Full |
ESX Legacy (es_extended) | Full |
What o-link needs to provide
If you installed o-link following its own guide, this is already covered. For reference, oxide-gangs uses these parts of the bridge: character identity and names, jobs, money, inventory (stash), notifications, target zones, menus, callbacks, in-world placement (for the admin panel's pickers), vehicle properties, vehicle keys, fuel, banking, dispatch, logging, and the player lifecycle events.
Installation Steps
Place the resource
Copy the whole oxide-gangs folder into your server's resources folder. If you already run other Oxide resources, they are probably grouped in a folder called [oxide] — put oxide-gangs in there next to them:
resources/
└── [oxide]/
├── o-link/
├── oxide-police/
└── oxide-gangs/ <- hereThe folder must be named exactly oxide-gangs.
Add it to server.cfg
If you start an [oxide] folder with ensure [oxide], you do not need to edit server.cfg at all. That one line starts every resource in the folder, and o-link sorts before oxide-gangs alphabetically, so the start order is already right.
Otherwise, find the block of ensure lines and add:
ensure oxide-gangsIt must come after o-link. See Load Order below for exactly where it goes.
Start the server
That is it for the files. The database tables are created for you the first time the resource starts — see Database Setup if you would rather do it by hand or your database user is not allowed to create tables.
Load Order
Every Oxide resource follows the same four-tier order in server.cfg. Use this structure as-is:
# 1. Framework — everything your framework requires (qb-core, es_extended, qbx_core, etc.)
ensure <framework>
# 2. Scripts — your other resources (inventory, target, phone, garages, etc.)
ensure <your-other-scripts>
# 3. o-link — the bridge. Starts after your framework/scripts, before any Oxide resource.
ensure o-link
# 4. Oxide resources — keep these together, ideally in a folder named [oxide]
ensure oxide-gangsThere is no required order within a tier. The only thing that matters is that o-link starts after your framework and before any Oxide resource.
Grouping in [oxide]
If you run several Oxide resources, put them all in a folder literally named [oxide] and replace tier 4 with a single line:
ensure [oxide]FiveM starts every resource inside a bracketed folder with that one line, and it does so alphabetically — so o-link inside [oxide] starts before every oxide-* resource on its own. Many servers still add an explicit ensure o-link just above it to make the intent obvious; both work.
Worked examples
ensure qb-core
ensure [qb]
ensure [standalone]
ensure ox_lib
ensure o-link
ensure [oxide]ensure oxmysql
ensure ox_lib
ensure ox_target
ensure [core]
ensure [standalone]
ensure ox_inventory
ensure o-link
ensure [oxide]ensure ox_lib
ensure qbx_core
ensure ox_target
ensure [ox]
ensure [qbx]
ensure [standalone]
ensure [oxide]oxide-gangs only requires ox_lib, oxmysql, and o-link to be running before it starts, and it tells you clearly in the server console if any of them is not.
Database Setup
You do not have to do anything here. oxide-gangs creates every table it needs the first time it starts, and it adds any new columns a future update introduces. For most servers this section is informational only.
Do it manually if your database user is not allowed to create tables, or if you simply prefer to see the schema first. Import sql/install.sql into your server's database using whatever database tool you use — HeidiSQL, phpMyAdmin, DBeaver, or your host's control panel.
The install creates:
| Table | Holds |
|---|---|
gang_gangs | The gangs themselves — name, display name, colour, motto, treasury balance |
gang_grades | Each gang's rank ladder and what each rank may do |
gang_members | Who is in which gang, at which rank |
gang_applications | Written applications to join a gang |
gang_requests | Player requests to create a new gang, and their form answers |
gang_transactions | The treasury ledger |
gang_bases | Gang bases, their stash and garage points, and spawn bays |
gang_vehicles | The gang fleet, with mods, fuel, and damage |
gang_logs | The per-gang activity log |
gang_territories | The territory map — polygons, colours, owners, contest state |
gang_territory_influence | How much influence each gang holds in each territory |
gang_wars | War records, stakes, clocks, and results |
gang_war_scores | Per-member kills, deaths, captures, and score in each war |
oxide_settings | Shared settings table used by every Oxide resource. Created if it does not exist; existing rows are left alone |
If the import fails
The schema uses JSON columns, which need MySQL 5.7+ or MariaDB 10.2+. On an older database server the import fails with an error mentioning the JSON columns. Check your version with:
SELECT VERSION();If you are below those versions, ask your host to upgrade your database — every currently supported MySQL and MariaDB release is new enough.
Admin Permissions
Staff commands (/gangs admin, /gangs settings, /gangs create, and the rest) need admin permission. oxide-gangs asks o-link, which accepts an admin two ways:
- The player holds the
commandACE, or - the player holds the
adminACE.
An "ACE" is FiveM's built-in permission system — a named permission you grant to a group of players in server.cfg.
Most servers are already covered. Stock QBCore, QBX, and ESX configs ship with this line, which grants your admins the command ACE:
add_ace group.admin command allowIf you have that line, admins can use the gang staff commands with no further changes.
If you do not, add both of these, replacing the identifier with your own:
add_principal identifier.license:YOUR_LICENSE_HERE group.admin
add_ace group.admin admin allowThe first line puts a player in the admin group. The second grants that group the admin permission. Being a member of group.admin is not enough on its own — you need the second line too.
The server console always counts as an admin, so you can run any staff command from your console or txAdmin without setting anything up.
The Minimap File
The resource folder contains a file called MINIMAP_LOADER.gfx. Do not delete it, rename it, or move it.
It is the stock GTA V minimap file, and oxide-gangs uses it to anchor the territory turf fill — the translucent coloured areas gang members see on the minimap and the pause map — to real world coordinates. Without it the rest of the resource still works, but the turf fill silently does nothing and each player's F8 console (the client console, opened in game with F8 — not the server console) prints:
[oxide-gangs] territory fill disabled: MINIMAP_LOADER.gfx is missing from the resourceThere is no setup to do. Leave the file where it is and the turf map works.
If you do not want the turf fill at all, turn it off properly in /gangs settings → Territory → Member turf map → Enabled, rather than by deleting the file.
Framework Setup
There is no framework-specific setup to do. Install the resource, start it, and it configures itself for whichever framework you run. This section explains what it does behind the scenes so you know what to expect.
Every gang is pushed into QBCore's gang list at boot, and each member's gang and rank is written into their player data. Other scripts that read PlayerData.gang keep working with no changes on your side.
This push is runtime only — nothing is written to qb-core/shared/gangs.lua. The full set is re-pushed every time the server starts, so the database stays the single source of truth. You can leave your existing gangs.lua exactly as it is; entries there are simply not managed by this resource.
The same, using qbx_core's own gang API. Nothing is written to your qbx_core files.
One thing to know: oxide-gangs gives each character one gang. qbx_core defaults to qbx:max_gangs_per_player 1 and qbx:setgang_replaces true, which matches exactly — so on a default Qbox install there is nothing to change. If you have raised qbx:max_gangs_per_player above 1 for another resource, be aware that oxide-gangs still enforces one gang per character in its own registry.
ESX has no gang system of its own, so there is nothing to mirror into. oxide-gangs becomes the gang system: any resource that asks o-link about a player's gang is answered from this registry. No ESX configuration is needed.
On every framework, when a player loads in their gang is re-applied from the database. That means a gang change made while they were offline sticks, and any third-party script that changed their gang behind this resource's back is corrected on their next login.
Inventory Items
oxide-gangs does not add any inventory items. There is nothing to register in ox_inventory/data/items.lua, qb-core/shared/items.lua, or an ESX items database table. No icons to copy either.
The only inventory feature is the gang base stash, which is a shared container created automatically for each gang that has a base with a stash point on it. It needs an inventory resource o-link supports, but no items and no setup.
Verification
Start the server and watch the console as it boots.
Check for dependency errors. If something is missing you will see a clear red message naming it:
[ERROR] oxide-gangs requires o-link but it is not running (state: missing). Ensure it is started before oxide-gangs.
[ERROR] oxide-gangs cannot start due to missing dependencies listed above.If you see that, fix the load order and restart. On a healthy boot you instead see a handful of [INFO] lines from oxide-gangs — "loaded 0 gangs from database" and "oxide-gangs initialized" among them.
Confirm the tables exist. Open your database tool and look for a table called gang_gangs. If it is there, the schema installed correctly.
Confirm the resource is running. Type ensure oxide-gangs in the live server console. No red text means it is up.
Open the admin panel. Join the server and type /gangs admin. A panel should open with a Requests list and a Gangs list, both empty on a fresh install. If you get "You do not have permission to do that", see Admin Permissions.
Check the territory map. In the admin panel, open Territories. You should see 34 Los Santos districts already drawn. They are seeded once, on the first boot against an empty table.
Open the settings editor. Type /gangs settings. A panel should open with categories down the left (Core, Economy, World, System). Nearly every setting in Configuration is in there.
First-Time Setup In Game
A sensible first run, in order:
/gangs settings — set Creation mode (do players request gangs, or do you create them?), Max members per gang, and any Creation fee. Then look through Territory and Wars and decide whether you want either turned on at all. All of this is changeable later at any time.
/gangs admin → Create gang — make a test gang. Give it an internal name in lowercase (e.g. ballas) and a display name (e.g. The Ballas).
Add yourself to it — with the gang selected, use Add member with your own server ID, or run /gangs setgang <your id> ballas 3 to join at the boss rank.
Place its base — with the gang selected, open Base. Walk to where you want the base, place the base position, then the stash point, then the garage point, then add a spawn bay or two.
Add a vehicle — in the same gang's Fleet section, add a model like buccaneer.
Test it — /gangs dashboard should open your gang panel. Walk to the base: you should see its blip on your map, be able to open the stash at the stash point, and take the car out at the garage point.
Check the turf map — open the pause map. As a gang member you should see the territory districts filled in with translucent colour.
If any of that does not happen, Troubleshooting covers each case.
Notes
Configuration lives in the database
shared/config.lua and shared/config/*.lua are factory defaults only. On the first boot their values are copied into the oxide_settings database table, and from then on that table is what the resource actually reads.
That means:
- Edit settings in game with
/gangs settings, not by editing the files. Changes apply immediately with no restart. - Editing the files after the first boot has no effect on an existing install — the database value wins.
- When an update adds a new setting, it is filled in from the file automatically. Your existing values are never overwritten.
Two things are the exception and stay file-only:
shared/config/grades.lua— the rank ladder template applied to newly created gangs. Editing it changes what new gangs start with; existing gangs manage their own ranks from the dashboard.shared/config/territories.lua— the shipped territory map, read once on first boot when the territory table is empty. After that your drawn map is authoritative and this file is never read again.
The user interface is already built
The manifest points at web/dist/index.html, which ships ready to use. There is no build step and nothing to install — just start the resource.
Locales
All text lives in locales/*.json and is loaded through ox_lib. English (en.json) ships. To add another language, drop a <lang>.json next to it and set this in your server.cfg:
setr ox:locale <lang>Updating
Replace the oxide-gangs folder and restart. Your settings, gangs, members, bases, fleets, territories, and war history all live in the database and are untouched. Any new setting an update adds is filled in from the shipped defaults automatically, and any new database column is added for you at boot.