# Exports, events and commands Everything the fivedash resource exposes to scripts and the console, with Lua examples: the log export, the fivedash:log event and the fivedash command. Source: https://fivedash.fivex.gg/docs/en/developers/exports-and-events This page lists everything the `fivedash` resource offers your city's scripts and the server console. The list is short on purpose: one export for logs, an equivalent event and a console command. The rest (whitelist, store) happens on its own, driven by the panel. It's for script developers. ## Before you start * The `fivedash` resource installed, connected and with the folder named `fivedash`. See [FiveM resource](https://fivedash.fivex.gg/docs/en/developers/fivem-resource). * For logs: the **Logs** module in your plan and a log created in the panel, with the **Key** your scripts will use (e.g. `deaths`). See [Create logs](https://fivedash.fivex.gg/docs/en/logs/create-logs). * Everything here is **server side only**. The resource has no client export and no network event. ## Summary | Name | Type | Side | What for | | --------------------------------- | ---------------------------- | -------------- | ----------------------------------------------- | | `exports.fivedash:log(key, data)` | Export | Server | Send a log to FiveDash | | `fivedash:log` | Local event (`TriggerEvent`) | Server | Same as the export, for those who prefer events | | `fivedash` | Console command | Server console | Status, detection, store and logs | | `fivedash::loaded` | Emitted local event | Server | Internal: character loaded (see below) | ## The `log` export ```lua local ok = exports.fivedash:log(key, data) ``` | Parameter | Type | What it is | | --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `key` | string | The log's **Key** in FiveDash (**Logs → the log → How to send**). It's lowercased. It must be 2 to 32 characters: lowercase letters, numbers, `-` and `_`, starting with a letter or number | | `data` | table or string | The log's content. A string becomes the `message` | **Returns:** `true` when the log went into the send queue; `false` when it was ignored. The export only checks the table and queues it: no network, no database. It's safe to call in a full city, but never inside per-frame loops. ### Fields of `data` | Field | Type | What it does | Limit | | --------- | ---------------- | ------------------------------------------------------------------------------------------- | -------------------------------- | | `title` | string | The log's title | 256 characters | | `message` | string | Free text, with as many lines as you want (`description` is accepted too) | 4,096 characters | | `player` | number or table | The player's `source`. FiveDash adds the character ID, name and identifiers on its own | | | `players` | table | Several players, each with a `label` | 10 players | | `fields` | table | Values in order: `{ { "Item", "water" }, { "Qty", 3 } }` | 25 fields; name 256, value 1,024 | | `color` | number or string | Stripe color: `"#ff4d4f"`, `"0xff4d4f"` or a number from `0` to `16777215` | | | `coords` | vector3 or table | Where it happened. Without it, the first player's position is used (`Coords` in `logs.lua`) | | | `image` | string | An `http(s)://` image link (a screenshot) | 2,048 characters | A log with no `title`, no `message`, no `fields` and no players is ignored (returns `false`). ### Players Each player (in `player` or inside `players`) can be: | Form | Example | When to use | | ------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------- | | Number (`source`) | `player = source` | The player is in the city | | Table with `source` | `{ source = target, label = "Victim" }` | In the city, with a label | | Table with `id` | `{ id = "1234", name = "John Smith", label = "Victim" }` | Out of the city (`id` is the character ID; `passport` and `passaporte` work too) | For a player in the city, the resource fills in: the character ID (the framework's character ID), the character's name, the `source` and the identifiers listed in `Identifiers` in `logs.lua` (default `license` and `discord`). Without a character picked yet, the FiveM name is used. `label` is up to 40 characters. ### Shapes of `fields` ```lua -- List of pairs, in order (recommended) fields = { { "Weapon", "WEAPON_PISTOL" }, { "Distance", 12.5 } } -- With name and value, and inline fields = { { name = "Weapon", value = "WEAPON_PISTOL", inline = true } } -- Pair with inline as the third value fields = { { "Weapon", "WEAPON_PISTOL", true } } -- key = value table (order not guaranteed) fields = { Weapon = "WEAPON_PISTOL", Distance = 12.5 } ``` Values can be text, numbers or booleans (booleans become **Yes** / **No**, in the city's language). Tables become JSON. ### Examples One player: ```lua -- server.lua RegisterNetEvent("my-script:bought", function(item, qty) local src = source exports.fivedash:log("npc-shop", { title = "Convenience store purchase", player = src, fields = { { "Item", item }, { "Qty", qty } }, }) end) ``` Two players, with color and coordinates: ```lua AddEventHandler("my-script:death", function(killer, victim, weapon) exports.fivedash:log("deaths", { title = "Death recorded", color = "#ff4d4f", players = { { source = killer, label = "Killer" }, { source = victim, label = "Victim" }, }, fields = { { "Weapon", weapon } }, coords = GetEntityCoords(GetPlayerPed(victim)), }) end) ``` Text only: ```lua exports.fivedash:log("admin", "Scheduled restart in 5 minutes") ``` With a screenshot: ```lua exports.fivedash:log("reports", { title = "Report with screenshot", player = source, message = "Player reported a map bug", image = "https://cdn.fivex.sh/example-city/screenshots/print-0001.webp", }) ``` ### Safe helper Create a function at the top of the file and use it everywhere. That way the script doesn't break if `fivedash` is stopped: ```lua local function fivedashLog(data) if GetResourceState("fivedash") ~= "started" then return end exports.fivedash:log("deaths", data) end fivedashLog({ title = "Death recorded", player = source }) ``` > On the log's page, **Copy AI prompt** copies a ready-made prompt (with the key, every option and these rules) to paste into an AI along with your script. ### From the client side The export doesn't exist on the client, and players can't send logs. If the action happens on the client, send it to a server event of your script and call the export there. Use the event's `source` to know who the player is: never trust an ID or name coming from the client. ```lua -- client.lua TriggerServerEvent("my-script:openedChest", chestId) -- server.lua RegisterNetEvent("my-script:openedChest", function(chestId) exports.fivedash:log("chests", { title = "Chest opened", player = source, fields = { { "Chest", chestId } }, }) end) ``` ### When a log is ignored | Situation | What happens | | -------------------------------------------------------------- | --------------------------------------------------------------------- | | `Enabled = false` in `logs.lua` | Returns `false` | | `config.lua` has no `Key` | Returns `false` | | Key in an invalid format | Returns `false` and warns in the console once: "Invalid log key in …" | | Key listed in `Disabled` | Returns `false` | | Resource not in `AllowedResources` (when the list isn't empty) | Returns `false` | | Empty log | Returns `false` | | Key that doesn't exist in the panel yet | Returns `true` and waits in the queue until the log is created | ## The `fivedash:log` event The same as the export, for scripts that prefer events. It's a **server-local event**: fire it with `TriggerEvent` from a server script. A client `TriggerServerEvent` doesn't reach it. ```lua TriggerEvent("fivedash:log", "deaths", { title = "Death recorded", player = source, fields = { { "Weapon", weapon } }, }) ``` Parameters and rules are the same as the export's. The event returns nothing. ## The `fivedash` command Only works in the server console (txAdmin or the FXServer terminal). In the game chat it's ignored. | Command | What it does | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `fivedash` or `fivedash status` | Version, framework, panel connection, server, language, syncs and commands, update waiting for a restart and waiting deliveries | | `fivedash detect` (or `detectar`) | Detects the framework again and prints the score and evidence | | `fivedash store` (or `loja`) | Store state: on, what it delivers, ID name, waiting, delivered and failed deliveries | | `fivedash store deliver` (or `loja entregar`) | Runs the deliveries of players already in the city now | | `fivedash logs` | Logs state: queue, sent, dropped, pace, last send and last error | | `fivedash logs test ` (or `teste`) | Queues a test log for the log with that key | Example of `fivedash`: ```bash [FiveDash] FiveDash 0.6.0 [FiveDash] · framework: QBCore [FiveDash] · dashboard: https://fivedash.fivex.gg (connected) [FiveDash] · server in FiveDash: "Example City" [FiveDash] · language: English (set in FiveDash) [FiveDash] · syncs: 1520, commands: 12 [FiveDash] · store: 2 deliveries waiting for players [FiveDash] · commands: fivedash status, fivedash detect, fivedash store, fivedash logs ``` Example of a log test: ```bash fivedash logs test deaths [FiveDash] Test log for "deaths" queued: it reaches FiveDash within 1 s. ``` ## Store command variables On products delivered by **command**, the resource replaces these variables before running the command in the console: | Variable | Becomes | | ----------- | -------------------------------------------------------------------------------------------------------------------------- | | `{id}` | The receiving character's ID (character ID, Citizen ID…). If the command uses `{id}` and there's no ID, the delivery fails | | `{discord}` | The buyer's Discord ID | | `{pedido}` | The order number | `{id}` and `{discord}` only carry letters, numbers, `-` and `_`. The blocked commands and `AllowedCommands` are in [FiveM resource](https://fivedash.fivex.gg/docs/en/developers/fivem-resource). ```bash givecoins {id} 500 ``` ## What the resource fires ### Internal character-loaded event On QBCore, Qbox, ESX, ox_core and vRP, the resource tracks which character each player is on and emits a server-local event when the character loads: | Framework | Event | Arguments | | --------- | ------------------------- | ------------------------------------ | | QBCore | `fivedash:qbcore:loaded` | `characterId` (Citizen ID), `source` | | Qbox | `fivedash:qbox:loaded` | `characterId` (Citizen ID), `source` | | ESX | `fivedash:esx:loaded` | `characterId` (`users.id`), `source` | | ox_core | `fivedash:ox-core:loaded` | `characterId` (State ID), `source` | | vRP | `fivedash:vrp:loaded` | `characterId` (account ID), `source` | On Creative, the store uses the base's own `CharacterChosen`, and this event doesn't exist. > This event is internal (it's what triggers store deliveries). It may change between versions without notice. For your scripts, prefer the framework's own events (`QBCore:Server:PlayerLoaded`, `esx:playerLoaded`…). ### On-screen notices When a purchase arrives (`Notify = true` in `loja.lua`) or is announced (`Announce = true`), the resource fires the framework's notice client event. If your city swaps the notification system, make sure this event keeps working: | Framework | Client event | | -------------------------- | ---------------------------------------------------------- | | Creative Network Enchanted | `Notify` (title, message, `"verde"` or `"default"`, 10000) | | vRP | `Notify` (`"sucesso"` or `"importante"`, message) | | QBCore | `QBCore:Notify` | | ESX | `esx:showNotification` | | Qbox and ox_core | `ox_lib:notify` | ### ACEs and groups The resource runs these console commands on its own: | Command | When | | ------------------------------------------------------------ | ------------------------------------------------------------------------ | | `add_ace identifier.license: allow` | Unlock on QBCore's and Qbox's whitelist | | `remove_ace identifier.license: allow` | Removal from QBCore's and Qbox's whitelist | | ` add/remove whitelist` | Unlock and removal on ESX | | `add_principal identifier.license: group.` | A store group that isn't a job (ESX and Qbox; `qbcore.` on QBCore) | | `remove_principal …` | When a timed group expires | Check groups in your scripts with `IsPlayerAceAllowed(source, "")` and grant the permissions in `server.cfg` (`add_ace group.vip vip allow`). ## What doesn't exist * There's no client export, network event (`RegisterNetEvent`) or callback. * There's no export for the whitelist or the store: the panel drives them. * There's no CDN export. To upload files, use the [CDN API](https://fivedash.fivex.gg/docs/en/developers/cdn-api). ## FAQ **The export returned true, but the log didn't show up.** Check that a log with that **Key** exists in the panel. Logs with an unknown key wait in the queue until the log is created. Run `fivedash logs` to see the queue and the last error. **Can I call the export in a loop?** Avoid it. One log per event. The resource already batches logs, but per-frame loops fill the queue (up to 20,000 logs, then the oldest are dropped). **Does it work with JavaScript or C# scripts?** Yes. FiveM exports work across languages: in JS, `exports.fivedash.log("deaths", { title: "…" })`. ## Next steps [Create logs](https://fivedash.fivex.gg/docs/en/logs/create-logs)Create the log and pick its key in the panel. [Logs API](https://fivedash.fivex.gg/docs/en/developers/logs-api)Send logs over HTTP, in Discord's webhook format. [FiveM resource](https://fivedash.fivex.gg/docs/en/developers/fivem-resource)Options in logs.lua and loja.lua. [Frameworks](https://fivedash.fivex.gg/docs/en/developers/frameworks)What each framework delivers and how it's detected.