Developers
FiveM resource (fivedash)
Architecture, install, every option in config.lua, loja.lua and logs.lua, convars, authentication, sync, protocol and updates of the fivedash resource.
Architecture, install, every option in config.lua, loja.lua and logs.lua, convars, authentication, sync, protocol and updates of the fivedash resource.
fivedash is the resource that links your city to FiveDash. It runs on the FXServer server side, detects the framework on its own and applies in game what the panel decides: it grants and removes whitelist, delivers store purchases and sends your scripts’ logs. This page is for server admins and script developers who want to understand how it works inside.
fxmanifest.lua asks for node_version "22". Use a recent FXServer artifact.oxmysql, ghmattimysql or mysql-async. Without a driver, the panel connection works, but the whitelist stays on Discord and the store doesn’t deliver.fivedash. Scripts call exports.fivedash:… and check GetResourceState("fivedash").City (FXServer) FiveDash
┌───────────────────────────────┐ HTTPS (out) ┌──────────────────────┐
│ fivedash/server/main.js │ ──────────────▶ │ POST /api/fivem/sync │
│ ├─ framework detection │ ◀────────────── │ pending commands │
│ ├─ Discord module (whitelist) │ └──────────────────────┘
│ ├─ Store module (deliveries) │ HTTPS (out) ┌──────────────────────┐
│ └─ Logs module (export) │ ──────────────▶ │ log service │
│ City MySQL (oxmysql…) │ └──────────────────────┘
└───────────────────────────────┘
server/main.js (a single bundle). client/main.js is empty: nothing runs in players’ games, and the resource registers no network events (RegisterNetEvent). Players can’t send it commands or logs.whitelist.allow) and removes it from whoever leaves Discord (whitelist.revoke).exports.fivedash:log(...) from scripts and sends them in batches.| File | What it is | Updated automatically? |
|---|---|---|
fxmanifest.lua | Resource manifest (fx_version "cerulean", game "common", node_version "22") | Yes |
server/main.js | All the server code | Yes |
client/main.js | Client side (empty for now) | Yes |
config.lua | Key and general options. Read by the server only | Never. New options are appended at the end |
loja.lua | Store delivery options | Never. Created on first boot if missing |
logs.lua | Options for logs sent through the export | Never. Created on first boot if missing |
The .lua settings files aren’t listed in files in the manifest: they never reach players.
In the panel, go to Server → Overview, on the Game connection card click Connect server, then Generate key. Click Download fivedash.zip: its config.lua already has the key.
Extract the fivedash folder into resources (or a subfolder like resources/[fivedash]).
In server.cfg, put ensure fivedash after the database driver and the framework:
ensure oxmysql
ensure qb-core
ensure fivedash
Restart the server (or type refresh and ensure fivedash in the console). The console shows [FiveDash] Connected to FiveDash as "Example City". and the panel shows Connected.
Already had the resource installed? Just paste the new key into fivedash/config.lua:
FiveDash = {
Key = "fdk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
Framework = "auto",
AutoUpdate = true,
Debug = false,
}
Read by the server only. After changing something, run restart fivedash.
| Option | What it does | Default |
|---|---|---|
Key | The server’s key in FiveDash (starts with fdk_). Empty, the resource doesn’t connect and warns in the console | "" |
Framework | "auto" detects on its own. To force one: "creative-enchanted", "qbox", "qbcore", "esx", "ox-core" or "vrp". Forced and not found, none is used and the console shows an error | "auto" |
AutoUpdate | Installs new resource versions on its own (the .lua settings files stay as they are). Off, it only warns in the console | true |
Debug | Prints every sync and command in the console, plus the detection evidence | false |
Two options aren’t in the file, but are accepted:
| Option | What it does | Default |
|---|---|---|
Url | The panel’s address. The resource you download from the panel already has this line set to https://fivedash.fivex.gg; leave it as it came | https://fivedash.fivex.gg (in the download) |
Locale | Console language before the first connection: "pt-BR" or "en". After that, the panel’s City language wins. The download already includes this line for cities that aren’t in Portuguese | Portuguese |
When a new version brings an option your file doesn’t have, the resource appends that option (with its comment and default value) before the closing }, without changing or removing what you wrote. Before that, it keeps a copy in config.lua.bak (or loja.lua.bak, logs.lua.bak). The console says which options were added. If the file doesn’t have the FiveDash = { ... } shape, it isn’t touched and new options use their defaults.
Store delivery options in the city. Details on each delivery type in In-game delivery.
| Option | What it does | Default |
|---|---|---|
Enabled | Turns store deliveries on in this city. Off, the store’s site stops selling until you turn it back on | true |
Notify | Shows the player a notice when the purchase arrives | true |
NotifyTitle | The notice’s title (up to 40 characters). "Loja" shows in the city’s language (“Store” in English cities) | "Loja" |
Announce | Announces to the whole city who bought what (once per order; gifts aren’t announced) | false |
SpawnDelay | Seconds between the player picking their character and the delivery (0 to 120) | 10 |
AllowedCommands | Console commands the store may run. Empty allows any, except the blocked ones. To lock it, list the start of each: { "givecoins", "addcar" } | {} |
Commands always blocked in command deliveries, even with AllowedCommands empty: quit, stop, start, restart, ensure, refresh, exec, set, sets, setr, seta, rcon_password, sv_licensekey, sv_hostname, sv_maxclients, endpoint_add_tcp, endpoint_add_udp, load_server_icon and fivedash. One line is one command: ; and line breaks are refused. Each command runs at most 100 times per delivery.
Options for logs sent through the exports.fivedash:log export. Webhooks don’t depend on this file.
| Option | What it does | Default |
|---|---|---|
Enabled | Turns sending logs through the export on. Off, calls are ignored | true |
PlayerInfo | Reads the character ID and name of each player in the log, through the framework | true |
Identifiers | Player identifiers sent with each log. Accepted: license, license2, discord, steam, fivem, xbl, live, ip | { "license", "discord" } |
Coords | Keeps the first player’s position when the script sends no coords | true |
Disabled | Log keys that never leave the city. E.g. { "chat" } | {} |
AllowedResources | Resources allowed to send logs. Empty lets any. E.g. { "vrp", "inventory" } | {} |
Echo | Prints each log in the console as it comes in (testing only) | false |
The send pace is fixed: one batch a second, up to 250 logs per batch, and up to 20,000 logs kept in the queue while the panel is away. Old lines like FlushInterval, BatchSize and MaxQueue stay in the file but are ignored.
Convars win over config.lua. Use set in server.cfg, never sets (sets publishes the value to the server list, and the key would be visible).
| Convar | Same as | Example |
|---|---|---|
fivedash_key | Key | set fivedash_key "fdk_xxxxxxxxxxxxxxxx" |
fivedash_framework | Framework | set fivedash_framework "qbox" |
fivedash_debug | Debug (use 1 to turn on) | set fivedash_debug 1 |
fivedash_locale | Locale | set fivedash_locale "en" |
fivedash_url | Url | set fivedash_url "https://fivedash.fivex.gg" (only if your config.lua has no Url) |
Convars must be in server.cfg before ensure fivedash.
fdk_ + 32 characters. The panel stores only its hash and shows just the last 4 characters (Resource …a1b2). It’s shown in full once, when generated.Authorization: Bearer fdk_….X-FiveDash-Instance). If the same key is running on two servers at once, the panel keeps the one already syncing and refuses the other (409) until the first has been quiet for 10 seconds (a restart). That way no delivery goes to the wrong city or happens twice.The resource runs one sync after another with POST /api/fivem/sync. Each carries the city’s state and the results of the previous commands; the answer brings new commands. When there’s nothing, the panel holds the answer for up to 3 seconds (long polling), so an unlock or a purchase reaches the city within a few seconds.
| Rule | Value |
|---|---|
| Max frequency | 1 sync per second per server (faster gets 429) |
| Hold without commands | up to 3 seconds |
| Call timeout | 45 seconds |
| Offline | retries from 2 s, doubling up to 60 s, and warns in the console only once |
| Parallel commands | up to 8 |
{
"protocol": 1,
"resource": "0.6.0",
"framework": {
"id": "qbcore",
"name": "QBCore",
"version": "1.3.0",
"features": ["whitelist", "store"],
"idKind": "discord",
"warnings": []
},
"players": 48,
"maxPlayers": 64,
"results": [{ "id": "cmd_example", "ok": true }],
"store": { "enabled": true, "problem": null, "kinds": ["group", "vehicle", "money", "item", "command"], "idLabel": "Citizen ID", "waiting": 2 },
"deliveries": [{ "id": "<order>:0:0", "state": "done", "reason": null, "at": "2026-11-09T18:00:00.000Z" }],
"hold": true
}
| Field | What it is |
|---|---|
protocol | The resource’s protocol version (1 today) |
resource | The resource version |
framework | Detected framework: id, name, version, features (whitelist, store), idKind (account, token or discord) and warnings (in the city’s language). null without a framework |
players, maxPlayers | Players now and sv_maxclients (default 32) |
results | Each command’s result: { "id", "ok": true } or { "id", "ok": false, "code", "message" } |
store | Store state in the city: on, problem, what it delivers, ID name and waiting deliveries |
deliveries | Deliveries that changed state (done, waiting, failed), up to 200 per sync |
hold | false on the first sync (and after an outage), so the panel answers right away |
{
"server": { "name": "Example City" },
"commands": [
{ "id": "cmd_example", "type": "whitelist.allow", "gameId": "1234567", "discordId": "123456789012345678" }
],
"update": null,
"locale": "en"
}
| Command type | What it does in the city |
|---|---|
whitelist.allow | Unlocks the ID (and links the Discord, when sent) in the framework’s whitelist |
whitelist.revoke | Removes whitelist by ID and/or Discord and, if kickMessage is set, drops the player with that message |
store.deliver | Receives an order’s deliveries (with retry: true on Send again, only what failed runs again) |
store.cancel | Order refunded: drops what’s still waiting in the city |
store.lookup | Asks who a purchase would go to (character ID and name, and whether they’re online) |
Every command is idempotent: if a result gets lost and the command comes back, the resource answers what it already did, without running it again. Error codes: not_found (the ID doesn’t exist in the database), unsupported (the framework can’t do it), invalid (wrong ID format) and failed (anything else, with message).
| Status | Error | What the resource does |
|---|---|---|
200 | Applies the commands and goes on | |
400 | bad_request | Invalid body or larger than 256 KB. Retries with backoff |
401 | invalid_key | Invalid or replaced key. Shows the error and retries in 60 s |
409 | in_use | The key is running on another server now. Retries in 10 s |
426 | outdated | Resource version no longer accepted. Retries in 10 min |
429 | too_many | Too fast (or too many wrong keys from the same IP). Waits for Retry-After |
Export logs don’t go through the sync: they take a separate path, so a busy city never slows commands down.
GET /api/fivem/logs/channels (with the same key). The map says which log keys exist and where to send them, and it’s valid for a short time.POST /api/fivem/logs, gzipped when the batch is over 1 KB.Logs with a key that doesn’t exist in the panel yet wait in the queue until you create the log. See Logs API and Exports, events and commands.
The resource and the panel agree on the message format through the protocol field (GAME_PROTOCOL, 1 today). When the panel changes something that breaks old versions, it bumps that number and answers 426 to older resources, which print “this resource version is no longer accepted” in the console and ask you to download the new one. Changes that don’t break anything don’t touch the number.
With AutoUpdate = true (default), the resource updates itself:
fxmanifest.lua, server/*.js and client/*.js can be updated (up to 10 MB each). The .lua settings files are never touched.restart fivedash in the console. The resource never restarts itself.The panel shows on the Game connection card: “Version X of the resource is available…”. If an update fails, the resource tries again in 10 minutes. With AutoUpdate = false, it only warns in the console: FiveDash X is available (this is Y). AutoUpdate is off in config.lua.
To update by hand: on the Game connection card, click Connect server, then Download the latest version. That zip comes without a key: replace only fxmanifest.lua, server/ and client/ and keep your .lua settings files.
The resource creates these tables in the city’s MySQL (with CREATE TABLE IF NOT EXISTS). Don’t delete them: they hold what must survive a restart.
| Table | What for |
|---|---|
fivedash_identities | The license, license2, Discord, Steam and FiveM of whoever tries to join. Links a Discord to its licenses (whitelist by Discord and purchases by Discord) |
fivedash_whitelist_grants | Unlocks FiveDash gave in the QBCore, Qbox and esx_whitelist whitelists, re-applied on every boot |
fivedash_ace_groups | ACE groups given by the store (group.vip, for example), re-applied on every boot |
fivedash_store_deliveries | Every store delivery and its state. Makes sure nothing is delivered twice |
fivedash_store_groups | Timed groups bought in the store, to remove them when they expire |
Every line from the resource starts with [FiveDash].
| Message | What to do |
|---|---|
| “No dashboard key: this server isn’t connected to FiveDash.” | Paste the key into Key in fivedash/config.lua |
| “The dashboard key doesn’t look right (it starts with fdk_).” | Check that you copied the whole key |
| “key refused by the dashboard” | The key was replaced or the server was disconnected. Generate a new one and replace Key |
| “this key is already in use by another server that’s running right now” | Each server has its own key. If you just restarted, it gets back in by itself in a few seconds |
| “this resource version is no longer accepted” | Download the new version from the panel |
| “No connection to the dashboard (…). Retrying automatically.” | Network or panel problem. The resource retries on its own |
| “No known framework found…” | Run fivedash detect to see the evidence, or force one with Framework |
Do I need to open a port on the server? No. The resource only makes outbound HTTPS calls.
Can I use the same key on two servers (test and production)? No. Each FiveDash server has its own key and only one city is linked at a time. Create another server in the panel for the test environment.
Does auto-update erase my settings?
No. config.lua, loja.lua and logs.lua are never overwritten. New options are only appended, with a .bak copy first.
Does it work without a framework? Yes. The connection works, the whitelist stays on Discord and the store only delivers console commands.