# fivemad.com documentation

> Free tools, reference data and documentation for FiveM server owners and developers.
> This file holds every documentation page in full. The short map is at https://fivemad.com/llms.txt.
> Any single page is available on its own: add .md to its URL.


# AI and API

## Using fivemad with an AI assistant

URL: https://fivemad.com/docs/ai

Read our docs as Markdown, pull our JSON datasets, look up a joaat hash and call our calculators from ChatGPT, Claude, Cursor or your own script.

Everything on fivemad is public and free, including for a machine. You do not need a key, an account or a contract. This page is the whole story in one place: how an assistant reads our documentation, how it pulls our data, and how it calls the parts of our tools that are pure calculation.

If you are the assistant reading this: start at [llms.txt](/llms.txt).

## Read any docs page as Markdown

Add `.md` to any `/docs` URL and you get the page as plain Markdown with a `text/markdown` content type.

```txt
https://fivemad.com/docs/server-setup/server-cfg      the page
https://fivemad.com/docs/server-setup/server-cfg.md   the same page as Markdown
https://fivemad.com/docs.md                           the index of every page
```

The Markdown is the real source of the page. The first lines say where it came from, which section it belongs to and when it was last touched, so a model that only sees the file still knows what it is holding.

```bash
curl https://fivemad.com/docs/server-setup/server-cfg.md
```

```md
<!-- fivemad.com, Markdown source of https://fivemad.com/docs/server-setup/server-cfg -->
> Source: https://fivemad.com/docs/server-setup/server-cfg
> Section: Server setup
> Tags: server.cfg, convars, onesync, sv_enforceGameBuild, ensure, endpoints, ace, config
> Last updated: 2026-09-22
> Site map for assistants: https://fivemad.com/llms.txt

# server.cfg explained line by line

What every common server.cfg line does: endpoints, hostname, tags, license key, slots,
game build, OneSync, ensure order, convars, ACE permissions and splitting configs.

`server.cfg` is not a special format. It is a list of **server console commands** that
FXServer runs from top to bottom when it starts...
```

Every docs page also has an **Open** button next to the breadcrumbs. It gives you the Markdown view, a copy of the Markdown on your clipboard, and a one click hand-off to ChatGPT, Claude or Cursor with the page's `.md` URL already in the prompt.

## llms.txt and llms-full.txt

| File | What it holds |
| --- | --- |
| [/llms.txt](/llms.txt) | The short map: what fivemad is, every tool with one line, the whole docs tree, every dataset with its row count and size, and the API. |
| [/llms-full.txt](/llms-full.txt) | The documentation itself, every page in full, in one plain text file. |

Both are built from the same registry and the same files the site ships, so the counts in them are real. They are listed in [robots.txt](/robots.txt) too, and every docs page carries them as `<link rel="alternate">` in its head.

```bash
curl https://fivemad.com/llms.txt
```

```txt
# fivemad.com

> Free tools, reference data and documentation for FiveM server owners and developers.
> 47 browser tools, 104 documentation pages and 29 public JSON datasets built from the GTA V game files.
> Nothing here needs an account. The tools run in the browser; the data below is static JSON you can fetch directly.

## How to use this site as an assistant

- Add .md to any docs URL for the plain Markdown source: https://fivemad.com/docs/server-setup/server-cfg.md
- Whole documentation in one file: https://fivemad.com/llms-full.txt
- Dataset index with row counts and sizes: https://fivemad.com/data/index.json
...

## Datasets

- [Props with pictures](https://fivemad.com/data/props.json): Every GTA V prop model that has a picture,
  with a readable label, category, tags and its real size in metres.
  (30,033 rows, 2.6 MB; rows: [model, label, category, tags, [x,y,z] size in m, minBuild, atlasCell, has3d])
```

> [!TIP]
> If you are pasting context into a chat by hand, `llms.txt` plus the two or three `.md` pages it points at is almost always better than `llms-full.txt`. The full file is large.

## The datasets

The reference data behind the tools is static JSON under `/data`. It is the same file the tool itself fetches, so nothing is held back.

Start with the index, which is generated from the real files:

```bash
curl https://fivemad.com/data/index.json
```

```json
{
  "site": "https://fivemad.com",
  "generated": "2026-09-23",
  "docs": "https://fivemad.com/docs/ai",
  "count": 29,
  "totalBytes": 12857308,
  "datasets": [
    {
      "id": "props",
      "title": "Props with pictures",
      "url": "https://fivemad.com/data/props.json",
      "about": "Every GTA V prop model that has a picture, with a readable label, category, tags and its real size in metres.",
      "shape": "rows: [model, label, category, tags, [x,y,z] size in m, minBuild, atlasCell, has3d]",
      "rows": 30033,
      "bytes": 2713710,
      "size": "2.6 MB",
      "page": "https://fivemad.com/tools/objects-list",
      "pageName": "Objects / Props List"
    }
  ]
}
```

Each entry tells you the URL, what the file holds, how a row is laid out, how many rows there are and how big the download is. The rows are short arrays on purpose: these files are fetched by browsers, so the column names live in the index and in a `cols` field inside the file, not on every row.

Some of these files are several megabytes. If all you need is one lookup, use the search or hash endpoints below instead of downloading the whole thing.

## Search

One short JSON answer over the tool list, the documentation and the dataset index.

```bash
curl "https://fivemad.com/api/search?q=handling&limit=3"
```

```json
{
  "query": "handling",
  "type": "all",
  "total": 16,
  "returned": 3,
  "limit": "60 requests per minute per IP",
  "hint": "Add .md to any docs URL for the plain Markdown source.",
  "results": [
    {
      "type": "doc",
      "title": "Vehicle Handling Editor",
      "url": "https://fivemad.com/docs/tools/vehicle-handling-editor",
      "markdown": "https://fivemad.com/docs/tools/vehicle-handling-editor.md",
      "summary": "Tune CHandlingData with sliders, import an existing handling.meta, toggle flag bits, and export handling.meta, runtime Lua or a carcols.meta mod kit.",
      "extra": {
        "section": "Tools",
        "match": "The Vehicle Handling Editor lets you tune a vehicle's CHandlingData block with sliders and a one line explanation per field..."
      },
      "score": 117.5
    },
    {
      "type": "tool",
      "title": "Vehicle Handling Editor",
      "url": "https://fivemad.com/tools/vehicle-handling-editor",
      "summary": "Tune mass, drive force, grip and suspension from a UI, then export handling.meta or runtime Lua.",
      "extra": { "category": "Config & Code", "tags": ["Vehicles", "Download"] },
      "score": 110
    }
  ]
}
```

Parameters: `q` (required), `type` (`all`, `tools`, `docs`, `datasets`), `limit` (1 to 50, default 10). Every documentation hit carries its `.md` URL, so the next step is one more fetch. The `score` is only there to explain the order; do not read anything into the absolute number.

## Look up a joaat hash

Paste a hash and get the name back. The search runs over every name set the site ships: props and map objects, vehicles, peds, weapons and their components, animation dictionaries and clips, particle assets and effects, sounds and sound sets, ymap and IPL names, MLO interiors, scaleform movies, ped decorations, timecycle modifiers, animpostfx effects, player stats and cutscenes.

```bash
curl "https://fivemad.com/api/hash?q=0xB779A091"
```

```json
{
  "query": "0xB779A091",
  "searched": { "names": 113305, "sets": 22 },
  "note": "joaat is a 32 bit hash, so a value can belong to more than one name. Every match is listed; none is picked for you...",
  "limit": "60 requests per minute per IP",
  "count": 1,
  "results": [
    {
      "query": "0xB779A091",
      "readAs": "hash",
      "hash": { "unsigned": 3078201489, "signed": -1216765807, "hex": "0xB779A091" },
      "matchCount": 1,
      "matches": [
        {
          "name": "adder",
          "kind": "vehicle",
          "kindLabel": "Vehicle model",
          "page": "https://fivemad.com/tools/model-hash-browser?q=adder"
        }
      ]
    }
  ]
}
```

The other direction, with the name this time:

```bash
curl "https://fivemad.com/api/hash?q=adder"
```

```json
{
  "results": [
    {
      "query": "adder",
      "readAs": "name",
      "name": "adder",
      "lua": "`adder`",
      "hash": { "unsigned": 3078201489, "signed": -1216765807, "hex": "0xB779A091" },
      "matchCount": 1,
      "matches": [{ "name": "adder", "kind": "vehicle", "kindLabel": "Vehicle model" }]
    }
  ]
}
```

It works the other way round too: pass a name and you get the unsigned, signed and hex forms plus the Lua backtick literal, and the same match list says whether the game actually ships that name.

- `q` accepts an unsigned value, a signed int32, `0x` hex, bare 8 digit hex, or a name.
- Up to 25 values in one call, separated by commas or new lines.
- `kind` narrows the answer, for example `kind=vehicle,ped`. `searched.byKind` in the response lists every kind and how many names it holds.
- A match may carry a `parent`: one animation dictionary, particle asset or sound set that contains the name. Because the hash depends on the name alone, a name is stored once, so the same clip or effect often lives in other dictionaries too. Treat `parent` as an example, not as the whole answer.

> [!IMPORTANT]
> joaat is a 32 bit hash, so a value can belong to more than one name. Every match is returned as a list and none of them is picked for you. If `matchCount` is above 1, the answer is genuinely ambiguous and you have to decide from context.

Here is a real one. `0x37D80B0E` is both a prop model and a ymap of the same name, so both come back:

```bash
curl "https://fivemad.com/api/hash?q=0x37D80B0E"
```

```json
{
  "results": [
    {
      "query": "0x37D80B0E",
      "readAs": "hash",
      "matchCount": 2,
      "matches": [
        { "name": "prop_cheetah_covered", "kind": "prop", "kindLabel": "Prop / object model" },
        { "name": "prop_cheetah_covered", "kind": "ymap", "kindLabel": "ymap / IPL name" }
      ]
    }
  ]
}
```

A name we do not ship comes back with `matchCount: 0`. That means we have no record of it, not that it does not exist.

The page for the same thing is the [joaat Hash Calculator](/tools/hash-calculator), under the "Reverse lookup" tab.

## Call a tool

The parts of the toolkit that are a pure function of their input can be called directly, so an assistant does not have to work out a flag value in its head. The list is at [/api/tools](/api/tools).

| Endpoint | What it does |
| --- | --- |
| `/api/tools/joaat` | joaat hash of one or more strings |
| `/api/tools/driving-style` | driving style flags for `TaskVehicleDriveToCoord` and friends |
| `/api/tools/animation-flags` | the flag argument of `TaskPlayAnim` |
| `/api/tools/warning-buttons` | button flags for `SetWarningMessage` |
| `/api/tools/handling-flags` | `strHandlingFlags`, `strModelFlags` and `strDamageFlags` |

The index gives you a working example URL for each one, so an assistant can discover the whole thing from a single fetch:

```bash
curl https://fivemad.com/api/tools
```

```json
{
  "count": 5,
  "tools": [
    {
      "id": "driving-style",
      "name": "Driving style flags",
      "about": "eVehicleDrivingFlags for TaskVehicleDriveToCoord, TaskVehicleDriveWander and SetDriveTaskDrivingStyle: decode a value or build one from flag names.",
      "url": "https://fivemad.com/api/tools/driving-style",
      "page": "https://fivemad.com/tools/driving-style-calculator",
      "params": [
        { "name": "value", "about": "Decode this value: 786603, -1073741824, 0xC00AB, 0b1011 or 1|2|128." },
        { "name": "flags", "about": "Encode instead: flag names separated by commas (StopForVehicles, StopForPeds, ...)." },
        { "name": "preset", "about": "One of: Normal, Strict, Ignore lights, Avoid vehicles, Reckless, ..." }
      ],
      "example": "https://fivemad.com/api/tools/driving-style?value=786603"
    }
  ]
}
```

Decode a value:

```bash
curl "https://fivemad.com/api/tools/driving-style?value=786603"
```

```json
{
  "tool": "driving-style",
  "name": "Driving style flags",
  "page": "https://fivemad.com/tools/driving-style-calculator",
  "limit": "120 requests per minute per IP",
  "value": 786603,
  "signed": 786603,
  "hex": "0x000C00AB",
  "binary": "0000 0000 0000 1100 0000 0000 1010 1011",
  "active": [
    { "bit": 0, "value": 1, "name": "StopForVehicles", "label": "Stop for vehicles", "desc": "Brakes and waits behind vehicles in its way instead of driving into them.", "unknown": false },
    { "bit": 1, "value": 2, "name": "StopForPeds", "label": "Stop for peds", "desc": "Stops for pedestrians on the road.", "unknown": false },
    { "bit": 3, "value": 8, "name": "SteerAroundStationaryVehicles", "label": "Steer around stationary vehicles", "desc": "Steers around parked and empty vehicles.", "unknown": false },
    { "bit": 5, "value": 32, "name": "SteerAroundObjects", "label": "Steer around objects", "desc": "Steers around props and objects on the road.", "unknown": false },
    { "bit": 7, "value": 128, "name": "StopAtTrafficLights", "label": "Stop at traffic lights", "desc": "Obeys red lights and stop lines.", "unknown": false },
    { "bit": 18, "value": 262144, "name": "UseShortCutLinks", "label": "Use shortcut links", "desc": "Allows shortcut road links such as dirt tracks and alleys. Removes most route limits.", "unknown": false },
    { "bit": 19, "value": 524288, "name": "ChangeLanesAroundObstructions", "label": "Change lanes around obstructions", "desc": "Changes lanes to pass slower traffic and obstructions.", "unknown": false }
  ],
  "expression": "StopForVehicles | StopForPeds | SteerAroundStationaryVehicles | SteerAroundObjects | StopAtTrafficLights | UseShortCutLinks | ChangeLanesAroundObstructions",
  "natives": ["TaskVehicleDriveToCoord", "TaskVehicleDriveToCoordLongrange", "TaskVehicleDriveWander", "SetDriveTaskDrivingStyle"],
  "valuesUsedByRockstar": [0, 1, 4, 16, 131, 139, 7785, 7791, 262144, 262208, 262275, 525116, 786468]
}
```

Build one from names instead. The answer has the same shape, so you can round trip it:

```bash
curl "https://fivemad.com/api/tools/driving-style?flags=StopForVehicles,StopAtTrafficLights,SteerAroundPeds"
```

```json
{
  "value": 145,
  "signed": 145,
  "hex": "0x00000091",
  "binary": "0000 0000 0000 0000 0000 0000 1001 0001",
  "expression": "StopForVehicles | SteerAroundPeds | StopAtTrafficLights"
}
```

Hashing, in bulk:

```bash
curl "https://fivemad.com/api/tools/joaat?text=adder,WEAPON_PISTOL"
```

```json
{
  "tool": "joaat",
  "note": "The game lower-cases a string before hashing it, so ADDER and adder give the same value.",
  "results": [
    { "input": "adder", "unsigned": 3078201489, "signed": -1216765807, "hex": "0xB779A091", "lua": "`adder`" },
    { "input": "WEAPON_PISTOL", "unsigned": 453432689, "signed": 453432689, "hex": "0x1B06D571", "lua": "`weapon_pistol`" }
  ]
}
```

handling.meta writes its flag fields as bare hex, so that is how this endpoint reads a value, and it gives you the line back ready to paste:

```bash
curl "https://fivemad.com/api/tools/handling-flags?set=strHandlingFlags&value=440010"
```

```json
{
  "set": "strHandlingFlags",
  "label": "Handling flags",
  "value": 4456464,
  "hex": "440010",
  "metaValue": "<strHandlingFlags value=\"440010\" />",
  "binary": "0000 0000 0100 0100 0000 0000 0001 0000",
  "active": [
    { "bit": 4, "value": 16, "name": "HF_NO_HANDBRAKE", "desc": "Handbrake disabled." },
    { "bit": 18, "value": 262144, "name": "HF_REDUCED_DRIVE_OVER_DAMAGE", "desc": "Takes less damage driving over things." },
    { "bit": 22, "value": 4194304, "name": "HF_TYRES_RAISE_SIDE_IMPACT_THRESHOLD", "desc": "Tyres resist side impacts better." }
  ],
  "expression": "HF_NO_HANDBRAKE | HF_REDUCED_DRIVE_OVER_DAMAGE | HF_TYRES_RAISE_SIDE_IMPACT_THRESHOLD"
}
```

Call an endpoint with no parameters and it answers with its full flag list, its presets and what each bit means, which is enough for a model to pick the right flags on its own:

```bash
curl "https://fivemad.com/api/tools/animation-flags"
```

`POST` with a JSON body works the same as the query string:

```bash
curl -X POST https://fivemad.com/api/tools/animation-flags \
  -H "content-type: application/json" \
  -d '{"flags":"AF_LOOPING,AF_UPPERBODY"}'
```

These use the exact same code as the tool pages, so the two can never give different answers.

## Rate limits

Per IP, in a fixed one minute window:

| Endpoint | Limit |
| --- | --- |
| `/api/search` | 60 per minute |
| `/api/hash` | 60 per minute |
| `/api/tools` and `/api/tools/*` | 120 per minute |
| All of the above together | 240 per minute |

Over the limit you get `429` with a `retry-after` header in seconds and a JSON body that says which limit you hit:

```json
{
  "error": "rate_limited",
  "message": "Too many requests. This endpoint allows 60 requests per minute per IP (240 across the whole API). Try again in 41s.",
  "docs": "https://fivemad.com/docs/ai"
}
```

The static files (`/data/*.json`, the `.md` pages, `llms.txt`) are served straight off disk and are not rate limited. Please cache them rather than refetching: they change when we rebuild, not per request.

The older endpoints keep their own limits: `/api/server` allows 30 lookups per minute per IP and `/api/blacklist` allows 20.

## CORS, caching and errors

- The `/api/*` endpoints on this page answer with `access-control-allow-origin: *` and handle a preflight, so a browser based agent can call them from any page.
- The static files (`/data/*.json`, `/data/index.json`, the `.md` pages, `llms.txt`) are served by the front end web server, not by the app, so whether they carry that header depends on the deployment. From a server side script, curl or an assistant's own fetcher this makes no difference. If you are calling them from a browser and get a CORS error, use `/api/search` or `/api/hash` instead, or proxy the file yourself.
- Errors are JSON with an `error` code, a `message` written for a human, and a link back to this page. Status codes are the ordinary ones: `400` bad input, `404` unknown tool, `429` rate limited, `503` when an index is not loaded yet.
- `/api/*` answers are cached for 60 seconds. The static files carry a longer cache.

## What an assistant can and cannot do here

It can:

- read any documentation page as Markdown, and the whole set at once;
- list and download every dataset, with the row shape given up front;
- resolve a joaat hash to a name, or a name to a hash, across the whole game;
- compute the flag values the natives want, and get the flag meanings back with them;
- link a person straight to the page that shows the same thing.

It cannot:

- run the tools that need a file, a browser or the game files. The texture editor, the clothing designer, the ymap and ytyp builders, the profiler and the 3D viewers all work on data you drop into the page, in your own browser, and there is no upload endpoint for them.
- write anything. Everything here is read only.
- look up a name we do not ship. Our data comes from the game files and from public FiveM sources; a model, sound or animation that a custom resource adds is not in it.
- be treated as a live game API. Nothing here talks to a running server, except `/api/server`, which reports what a FiveM server publishes about itself.

## A worked example

"What driving style should I use for an ambulance that runs red lights but still avoids traffic?"

```bash
# 1. see what the flags mean
curl "https://fivemad.com/api/tools/driving-style"

# 2. build the value
curl "https://fivemad.com/api/tools/driving-style?flags=SwerveAroundAllVehicles,SteerAroundStationaryVehicles,SteerAroundPeds,SteerAroundObjects,AllowGoingWrongWay"

# 3. check the vehicle model exists and get its hash
curl "https://fivemad.com/api/hash?q=ambulance"
```

The answer to step 2 carries the value, its signed and hex forms and the native names it belongs to, which is everything needed to write the `TaskVehicleDriveToCoord` call.

_Last updated: 2026-09-23_

---


# Video tutorials

## FiveM video tutorial archive

URL: https://fivemad.com/docs/videos

A hand-picked training set of FiveM YouTube tutorials, grouped into courses from first server to Lua, NUI, streaming assets, CodeWalker and Blender with Sollumz.

Some things are easier to learn by watching someone do them. This archive collects FiveM tutorials from YouTube and puts them in order, so you get a course instead of a search results page. Every video was checked to exist and picked because it's clear, accurate enough and still useful today.

## How it's organised

The archive has ten courses. Each has a level and its lessons in a sensible order:

| Course | Level | For |
| --- | --- | --- |
| Run your first server | Beginner | Getting a server online on Windows, Linux or a VPS, license key, database, ports, updates, vMenu |
| txAdmin in depth | Beginner | The in-game menu, admins, the Discord bot, whitelisting |
| Frameworks: QBCore, Qbox and ESX | Beginner | Choosing and installing a framework, jobs, items, ox_inventory |
| Lua scripting for FiveM: the basics | Beginner | Editor setup, first resource, commands, natives, events, callbacks, threads |
| Scripting in depth | Intermediate | State bags, routing buckets, databases, exports, full job systems, JavaScript and C# |
| NUI and user interfaces | Intermediate | HTML UIs, focus and callbacks, React, loading screens |
| Streaming assets: vehicles, clothing and MLOs | Intermediate | Car packs and their meta files, textures, clothing packs, MLO installs |
| CodeWalker and map editing | Intermediate | YMAPs, adding and removing props, merging maps, MLO collisions |
| 3D modelling with Blender and Sollumz | Advanced | Props, collisions, lights, vehicles, clothing and MLO interiors |
| Performance, security and workflow | Intermediate | resmon, optimisation, stopping cheaters, git |

## How to use it

- **Pair videos with the written guides.** Each course matches a section of these docs: watch the video, then use the guide as the reference. For example the Lua course goes with [Your first resource](/docs/development/first-resource) and [Client, server and events](/docs/development/client-server-events).
- **Follow the order inside a course**, but skip what you already know.
- **Code along.** Keep a local dev server running (see [Windows setup](/docs/server-setup/windows)) and type the code yourself instead of just watching.
- **Check the date.** Every lesson shows when it was published. FiveM changes: older videos may show old txAdmin screens, `GetPlayerPed(-1)` instead of `PlayerPedId()`, or framework code from earlier versions. The ideas still hold, and the written guides show the current way.

> [!NOTE]
> The videos belong to their creators and are embedded from YouTube. The descriptions are ours. Many creators also sell resources or hosting; being listed here isn't an endorsement of anything but the video.

## About Vespura and the official channels

Tom Grobbe (Vespura), the author of vMenu, documents his work in writing at [docs.vespura.com](https://docs.vespura.com/) rather than on YouTube, so his projects appear here through other creators' install videos and in our [recommended resources](/docs/resources/recommended#vmenu) page. Cfx.re's own documentation is written too, at [docs.fivem.net](https://docs.fivem.net/docs/). The official [txAdmin channel](https://www.youtube.com/@txAdmin) has a few short videos, included in the txAdmin course.

## Missing something?

If a video goes private or a better one comes out, we update the archive. Suggestions are welcome through the fivemad Discord.

_Last updated: 2026-09-22_

---


# Getting started

## Getting started with FiveM servers and development

URL: https://fivemad.com/docs/getting-started

What FiveM, FXServer, txAdmin and Cfx.re are, how the pieces fit together, and the order to read these docs in to run a server or write scripts.

These docs take you from "I want a FiveM server" to running one, managing it with txAdmin, installing resources and frameworks, and writing your own scripts. Everything here is checked against the official Cfx.re documentation and the source repositories on GitHub. When something depends on a version, the page says so.

If you only want to get a server online today, jump to [Setting up a server on Windows](/docs/server-setup/windows) or [on Linux](/docs/server-setup/linux). If you want to write code, start with [Your first resource](/docs/development/first-resource). Come back to this page when a word stops making sense.

## The pieces and who makes them

FiveM is a modification framework for Grand Theft Auto V that lets people run their own multiplayer servers with custom code, maps, vehicles and game modes. A few names show up everywhere:

| Name | What it is |
| --- | --- |
| **Cfx.re** | The team and platform behind FiveM (GTA V) and RedM (Red Dead Redemption 2). Cfx.re is owned by Rockstar Games. The forum is [forum.cfx.re](https://forum.cfx.re), the docs are [docs.fivem.net](https://docs.fivem.net/docs/). |
| **FiveM client** | What players install. It launches their own copy of GTA V and connects to servers. |
| **FXServer** | The server program you run. Also called the "Cfx platform server". On Windows it is `FXServer.exe`, on Linux you start it through `run.sh`. |
| **Server artifacts** | The FXServer builds you download. Each build has a number, for example `2xxxx`. See [Updating artifacts safely](/docs/server-setup/updating-artifacts) and our [Artifacts page](/artifacts). |
| **txAdmin** | The web panel and in-game admin menu that ships inside FXServer. It deploys servers from recipes, restarts them, bans players and more. |
| **Cfx.re Portal** | [portal.cfx.re](https://portal.cfx.re), where you create the free server license key that every server needs. |
| **Resources** | Folders of scripts and assets that FXServer loads. Everything a server does beyond vanilla GTA is a resource. |
| **Frameworks** | Big sets of resources that add players, jobs, money and inventories, for example QBCore, Qbox and ESX Legacy. See [Frameworks](/docs/frameworks). |

> [!NOTE]
> In July 2026 Cfx.re opened early access for **FiveM for GTA V Enhanced**, which runs on the newer Enhanced edition of the game with a separate server build called **Cfx Server**. The classic FiveM, now called **Legacy**, keeps running and is still what almost every server and resource targets. These docs cover Legacy FXServer unless a page says otherwise. See [FiveM Legacy and Enhanced](/docs/server-setup#fivem-legacy-and-fivem-for-gta-v-enhanced) for what changes.

## How it fits together

When you start a server, this is what happens:

1. You run FXServer. With no arguments it starts **txAdmin**, which opens a web panel on port `40120`.
2. txAdmin (or you, by hand) starts FXServer with a `server.cfg`. That file sets the server name, the license key, player slots, endpoints and which resources to start.
3. FXServer reads the `resources` folder, loads every resource you `ensure`, and runs their **server scripts**.
4. A player connects on port `30120`. Their client downloads the **client scripts**, NUI pages and streamed assets (models, textures, maps) of your resources, then joins.
5. Client scripts and server scripts talk to each other with **events**, and to the game through **natives**.

```text title="A typical server folder after a txAdmin deploy"
FXServer/
├─ server/            the artifact: FXServer.exe (Windows) or run.sh + alpine/ (Linux)
└─ txData/
   ├─ admins.json     txAdmin accounts
   └─ MyServer.base/  your server data folder (any name you pick in the deployer)
      ├─ server.cfg
      └─ resources/
         ├─ [cfx-default]/   mapmanager, spawnmanager, chat...
         └─ [local]/         your own resources
```

## A learning path through these docs

Follow the sections in this order. Each page links to the next one.

### 1. Understand what you need

- [Glossary](/docs/getting-started/glossary): every term you will meet, in one place.
- [Requirements](/docs/getting-started/requirements): hardware, Windows or Linux, and the legal basics (license, Rockstar content, monetisation).

### 2. Get a server online

- [Server setup overview](/docs/server-setup), then [Windows](/docs/server-setup/windows) or [Linux](/docs/server-setup/linux).
- [server.cfg explained](/docs/server-setup/server-cfg) line by line. You can also build one with the [server.cfg Generator](/tools/server-cfg-generator).
- [Ports and networking](/docs/server-setup/ports-and-networking) and [Database setup](/docs/server-setup/database) if you plan to run a framework.
- [Common errors and fixes](/docs/server-setup/common-errors) and [Security basics](/docs/server-setup/security).

### 3. Run it day to day with txAdmin

- [txAdmin overview](/docs/txadmin), [first setup and the deployer](/docs/txadmin/first-setup), [recipes](/docs/txadmin/recipes), [everyday admin](/docs/txadmin/everyday-admin) and the [Discord bot](/docs/txadmin/discord-bot).

### 4. Add content

- [Installing resources](/docs/resources), [recommended open source resources](/docs/resources/recommended), [maps, MLOs and clothing](/docs/resources/maps-mlos-clothing) and [vehicle packs](/docs/resources/vehicle-packs).
- Pick a framework, or none: [Frameworks compared](/docs/frameworks).

### 5. Write your own scripts

- [Development overview](/docs/development) (tools and setup), then [Your first resource](/docs/development/first-resource).
- [Client, server and events](/docs/development/client-server-events), [natives](/docs/development/natives), [state bags and OneSync](/docs/development/state-bags-onesync), [NUI](/docs/development/nui).
- [Threads and performance](/docs/development/threads-performance), [exports and dependencies](/docs/development/exports-dependencies), [debugging](/docs/development/debugging).
- [Streaming custom assets](/docs/development/streaming-assets) and [publishing a resource](/docs/development/publishing).

### 6. Watch instead of read

The [video tutorial archive](/docs/videos) groups hand-picked YouTube tutorials into courses: running your first server, txAdmin, frameworks, Lua scripting, NUI, streaming assets, CodeWalker and Blender with Sollumz.

## Where to get help

- **Official docs**: [docs.fivem.net](https://docs.fivem.net/docs/) for server setup, the scripting manual and the [natives reference](https://docs.fivem.net/natives/).
- **Forum**: [forum.cfx.re](https://forum.cfx.re) has Server Discussion, Development and Releases categories. Search before you post, most errors have been seen before.
- **Framework communities**: QBCore, Qbox, ESX and Overextended each run their own Discord and docs, linked from the [frameworks pages](/docs/frameworks).
- **txAdmin**: the [txAdmin Discord](https://discord.gg/txAdmin) and the docs folder in the [txAdmin repository](https://github.com/citizenfx/txAdmin/tree/master/docs).

> [!TIP]
> When you ask for help, paste the exact error from the server console or the F8 client console, your artifact build number and your `server.cfg` (with the license key and database password removed). That answers half the questions people will ask you.

_Last updated: 2026-09-22_

---

## FiveM glossary

URL: https://fivemad.com/docs/getting-started/glossary

Plain definitions of the FiveM terms you will meet: resources, artifacts, OneSync, natives, state bags, NUI, ymap, ytyp, ydr, yft, ytd, streaming, convars, ACE.

FiveM has its own vocabulary, and GTA V adds a second one for its file formats. This page explains each term in a sentence or two and points to the page that goes deeper. Terms are grouped by topic, not alphabetically, so related ideas sit together.

## Platform and server

**Cfx.re**: The company and platform behind FiveM and RedM, owned by Rockstar Games. "Cfx" shows up in the forum (`forum.cfx.re`), the portal (`portal.cfx.re`) and join links (`cfx.re/join/abc123`).

**FXServer**: The dedicated server program. You download it as an **artifact** and run `FXServer.exe` on Windows or `run.sh` on Linux.

**Artifact**: One numbered build of FXServer, published at `runtime.fivem.net/artifacts`. There is a *recommended* build and a *latest* build. Some builds are known to be broken, so check our [Artifacts page](/artifacts) before you update. More in [Updating artifacts safely](/docs/server-setup/updating-artifacts).

**Legacy and Enhanced**: Since July 2026 there are two FiveM platforms. **Legacy** is the classic FiveM on the original PC version of GTA V and uses FXServer. **FiveM for GTA V Enhanced** runs on the Enhanced edition and uses a separate server build called **Cfx Server**. They are separate: a Legacy client cannot join an Enhanced server.

**txAdmin**: The web panel and in-game menu built into FXServer. It deploys servers from **recipes**, restarts on crash, schedules restarts, bans and warns players and runs a Discord bot. See [txAdmin](/docs/txadmin).

**Recipe**: A YAML file that tells the txAdmin deployer how to build a server: which repositories to download, which files to move, which SQL to run. See [Recipes explained](/docs/txadmin/recipes).

**License key**: The free key from [portal.cfx.re](https://portal.cfx.re) that every server must set with `sv_licenseKey`. Keys look like `cfxk_...`.

**server.cfg**: The config file FXServer executes on start. It is a list of console commands and convars. See [server.cfg explained](/docs/server-setup/server-cfg).

**Convar**: A console variable, like `sv_hostname` or `sv_maxclients`. You set it with `set`, `sets` (also shows in the server list info) or `setr` (also replicated to clients so client scripts can read it).

**Endpoint**: The IP and port FXServer listens on, set with `endpoint_add_tcp` and `endpoint_add_udp`. The default is `0.0.0.0:30120`.

**Game build**: The GTA V update your server asks clients to run, set with `sv_enforceGameBuild` (for example `3751`). Newer builds unlock newer DLC vehicles, clothes and maps.

**Pure mode**: `sv_pureLevel` blocks modified client game files. Level 1 still allows audio files and known graphics mods, level 2 blocks all modified files.

**OneSync**: FiveM's server side sync system. With `onesync on` the server knows about every entity and player and decides who gets what, which allows more than 32 players and server side entity control. Without a Cfx.re subscription the slot limit is 48. Up to 2048 slots are possible with OneSync and the right tier.

**Routing bucket**: A separate "dimension" on a OneSync server. Players and entities in different buckets cannot see each other. Used for instanced interiors, character selection and races.

**Entity lockdown**: `sv_entityLockdown` stops clients from creating networked entities themselves, which blocks a common cheat. Modes are `inactive`, `relaxed` and `strict`.

## Resources and scripting

**Resource**: A folder with an `fxmanifest.lua` file. It can contain Lua, JavaScript or C# scripts, a web UI, streamed assets and data files. You start it with `ensure name` where `name` is the folder name.

**fxmanifest.lua**: The resource manifest. It declares `fx_version`, `game`, which scripts run on the client or server, which files to send to clients, `data_file` entries and dependencies. Generate one with the [fxmanifest Generator](/tools/fxmanifest-generator).

**Category folder**: A folder in brackets, like `[local]` or `[qb]`. It only groups resources, it is not a resource itself. `ensure [qb]` starts every resource inside it.

**Client script / server script / shared script**: Client scripts run on each player's game. Server scripts run once, in FXServer. Shared scripts run on both. See [Client, server and events](/docs/development/client-server-events).

**Event**: A named message. `TriggerEvent` fires one on the same side, `TriggerServerEvent` sends one from a client to the server, `TriggerClientEvent` sends one from the server to one or all clients. Network events must be registered with `RegisterNetEvent`.

**Callback**: A request that expects an answer, for example "server, how much money does this player have?". FiveM has no built in callback between client and server, so libraries like `ox_lib` (`lib.callback`) and the frameworks provide one on top of events.

**Native**: A function of the GTA V engine or of FiveM itself, like `GetEntityCoords` or `SetPedIntoVehicle`. There are thousands, listed at [docs.fivem.net/natives](https://docs.fivem.net/natives/). See [Natives](/docs/development/natives).

**Hash / joaat**: GTA identifies models, weapons and many other things by a 32 bit hash of their name, computed with Jenkins one-at-a-time (joaat). `GetHashKey('adder')` or `` `adder` `` in FiveM Lua gives you the number. Try the [joaat Hash Calculator](/tools/hash-calculator).

**Export**: A function one resource makes callable from other resources, like `exports.ox_inventory:AddItem(...)`. See [Exports and dependencies](/docs/development/exports-dependencies).

**State bag**: A key/value store attached to the server (`GlobalState`), a player (`Player(src).state`) or an entity (`Entity(ent).state`) that FiveM syncs for you. See [State bags and OneSync](/docs/development/state-bags-onesync).

**NUI**: "New UI", FiveM's embedded Chromium browser. It lets you build HUDs, menus and phones in HTML, CSS and JavaScript (React, Vue, Svelte and so on). See [NUI basics](/docs/development/nui).

**DUI**: Direct-rendered UI. A web page drawn onto a texture in the world, like a TV screen or a billboard.

**KVP**: Key value pairs, a small built in storage (`SetResourceKvp`, `GetResourceKvpString`) on the client or server. Good for settings, not for large data.

**Tick / thread**: A Lua loop created with `CreateThread` that runs every frame or every `Wait(ms)`. Code that runs every frame costs performance. See [Threads and performance](/docs/development/threads-performance).

**resmon**: The resource monitor. Type `resmon` in the F8 console to see how much CPU time and memory each client resource uses.

**Profiler**: The built in FiveM profiler (`profiler record`, `profiler saveJSON`) that records exactly which resource and function uses time. Read its output with the [Profiler Analyzer](/tools/profiler-analyzer).

**Framework**: A shared base for roleplay style servers: player data, characters, jobs, money, items. QBCore, Qbox, ESX Legacy, ox_core and ND_Core are the common ones. See [Frameworks](/docs/frameworks).

**Asset escrow**: Cfx.re's system that encrypts paid resources sold on Tebex so they only run on the buyer's license key. See [Publishing a resource](/docs/development/publishing).

## Permissions

**ACE**: Access Control Entry. A rule like `add_ace group.admin command allow` that allows or denies an **object** (for example `command.ban`) for a **principal**.

**Principal**: Who a rule applies to: a group (`group.admin`), an identifier (`identifier.fivem:123456`, `identifier.license:abc...`, `identifier.discord:...`) or a resource (`resource.myresource`). `add_principal child parent` makes one principal inherit another.

**Identifier**: A player ID that FXServer receives on connect: `license:` (Rockstar license), `fivem:` (Cfx.re account), `discord:`, `steam:` (needs a Steam Web API key), `xbl:`, `live:` and `ip:`.

## GTA V file formats

**RPF**: Rockstar's archive format. Singleplayer mods ship as `dlc.rpf`. FiveM does not load RPFs from resources, you extract their contents into a `stream` folder and meta files instead.

**Streaming**: Loading assets into the game as they are needed. In FiveM, any supported file in a resource's `stream` folder is sent to clients and registered with the game automatically.

**YDR**: A single drawable model (props, simple objects).

**YDD**: A drawable dictionary, several drawables in one file. Used for clothing and ped parts.

**YFT**: A fragment model, a model that can break or has moving parts. Vehicles are `.yft` files (plus a `_hi.yft` high detail version).

**YTD**: A texture dictionary. Holds the textures for a model. Oversized YTDs are the most common cause of texture loss on busy servers. Shrink them with the [YTD Optimizer](/tools/ytd-optimizer).

**YBN**: Static collision (bounds). Without it players fall through your map.

**YMAP**: A map placement file. It lists which objects (entities) are placed where, with rotation and LOD distance. Build one with the [YMAP Builder](/tools/ymap-builder) or in CodeWalker.

**YTYP**: An archetype definition file. It tells the game about new model names, their bounding boxes and LOD distances, and defines MLO interiors. Create one with the [YTYP Creator](/tools/ytyp-creator).

**MLO**: "Map Loaded Object", an interior with rooms and portals, defined in a `.ytyp` and placed by a `.ymap`. Custom shops, police stations and houses are usually MLOs.

**YMT**: A binary metadata file. For clothing, the ped variation `.ymt` lists how many drawables and textures each component has. Generate one with the [YMT Creator](/tools/ymt-creator).

**YNV / YND**: Navmesh and path nodes. They tell peds and traffic where they can walk and drive.

**.meta files**: XML data files the game reads, like `vehicles.meta`, `handling.meta`, `carcols.meta`, `carvariations.meta` and `weapons.meta`. You register them in the manifest with `data_file`.

**AWC / dat54.rel**: Audio: `.awc` holds the sound data, `dat54.rel` (and friends) define how the game plays it. The [Native Audio Builder](/tools/native-audio-builder) turns WAV, MP3 or OGG files into this format.

**CodeWalker**: The free community tool for browsing the GTA V world and editing YMAPs, YTYPs and many other formats. Get it from [github.com/dexyfex/CodeWalker](https://github.com/dexyfex/CodeWalker).

**Sollumz**: The free Blender add-on for importing and exporting GTA V models (YDR, YDD, YFT, YBN) as CodeWalker XML. Get it from [github.com/Sollumz/Sollumz](https://github.com/Sollumz/Sollumz).

**LOD**: Level of detail. Models have simpler versions for far away views, and the game switches between them by distance.

_Last updated: 2026-09-22_

---

## Requirements: hardware, OS and the rules

URL: https://fivemad.com/docs/getting-started/requirements

What you need to run a FiveM server: realistic hardware sizing, Windows or Linux, network, and the legal basics of the Cfx.re license, Rockstar content and Tebex.

Before you rent a machine or promise a community a launch date, check three things: the hardware you need for the kind of server you want, the operating system you are comfortable with, and the rules you agree to when you run a FiveM server.

## What you need no matter what

- **A legal copy of GTA V** on the PC you play from. The server itself does not need GTA V installed.
- **A Cfx.re account** and a free **server license key** from [portal.cfx.re](https://portal.cfx.re). One key per server.
- **A machine that stays online**: your own PC for testing, or a VPS or dedicated server for a public server.
- **Open ports**: `30120` TCP and UDP for players, and `40120` TCP for the txAdmin web panel (keep that one private if you can). See [Ports and networking](/docs/server-setup/ports-and-networking).
- **MariaDB** if you plan to run a framework like QBCore, Qbox or ESX. A plain server with vMenu does not need a database. See [Database setup](/docs/server-setup/database).

## Hardware sizing

Cfx.re does not publish official hardware requirements, and the real load depends far more on your resources than on your player count. A server with 40 well written scripts behaves very differently from one with 300 leaked ones. Use the table below as a starting point, then measure with txAdmin's performance chart and the [profiler](/docs/development/threads-performance).

| Server type | CPU | RAM | Storage | Notes |
| --- | --- | --- | --- | --- |
| Local test server on your PC | Any modern 4 core | 4 GB free | 10 GB | Fine for development. Run the game and the server on the same machine. |
| Small public server, up to ~48 players, light scripts | 2 to 4 fast cores | 4 to 8 GB | 30 to 60 GB SSD | vMenu or a light framework, a few car packs. |
| Roleplay server, 48 to 128 players, full framework | 4+ cores with high single core speed | 8 to 16 GB | 60 to 120 GB NVMe | MariaDB on the same machine is common at this size. |
| Large server, 128+ players, heavy streaming | 6 to 8+ high clock cores | 16 to 32 GB | NVMe, plus a CDN or separate file server for assets | Needs a paid Cfx.re tier for the slots, and careful script work. |

A few things matter more than raw numbers:

- **Single core speed.** The main server thread runs on one core. A high clock CPU beats a many core, low clock one.
- **Upload bandwidth.** Every joining player downloads all your streamed assets. A 2 GB car pack times 50 players joining after a restart is 100 GB of upload. Keep packs lean, shrink textures with the [YTD Optimizer](/tools/ytd-optimizer), and consider a file server or CDN for big servers.
- **Disk speed.** MariaDB and txAdmin logs like fast disks. Avoid spinning disks.
- **Clean IP.** Some hosting IP ranges are blocked on the Cfx.re platform. Check a VPS IP with the [Cfx Blacklist Checker](/tools/cfx-blacklist-checker) before you pay for a year.

> [!IMPORTANT]
> The free slot limit is **48 players**. Going above 48 needs a Cfx.re Element Club tier (Argentum or higher), bought on the Cfx.re Portal. Setting `sv_maxclients 64` without it does not work.

## Windows or Linux

Both are fully supported by FXServer and txAdmin.

| | Windows | Linux |
| --- | --- | --- |
| Setup | Download `server.7z`, extract, double click `FXServer.exe`. | Download `fx.tar.xz`, extract, run `bash run.sh`. Needs basic shell skills. |
| Cost | Windows Server licenses make VPS plans pricier. | Usually cheaper for the same hardware. |
| Tools | HeidiSQL, CodeWalker and Windows only tools run on the same box. | Everything is done over SSH. Run the game tools on your own PC. |
| Running as a service | Scheduled task or a service wrapper. | `systemd`, `screen` or `tmux`. |
| C# resources | Supported. | Supported. |

If you have never used a Linux shell, start on Windows (even your own PC) and move to Linux later. Your resources and `server.cfg` work the same on both, just watch out for **case sensitive file names** on Linux: `ensure MyResource` will not find a folder called `myresource`.

> [!TIP]
> Develop on a local Windows server, deploy to a Linux VPS. Keep the whole server folder in git so moving between them is a `git pull`. See [Security basics](/docs/server-setup/security) for what never to commit.

## Game server providers vs your own VPS

Game server providers (GSPs) give you a panel with FXServer and txAdmin preinstalled. That is the fastest way to get online, and many of them can host MariaDB for you. A VPS or dedicated server gives you full control and usually more hardware for the money, but you handle updates, backups and security yourself. These docs work for both: txAdmin looks the same everywhere.

## The rules you agree to

Running a FiveM server means agreeing to the **Cfx.re Platform License Agreement** (the "terms", at [fivem.net/terms](https://fivem.net/terms)). It has been updated several times, including a new Creator Platform License Agreement that took effect on 12 January 2026, so read the current version yourself. This section is a plain summary, not legal advice.

### What the platform allows

- Running a server with your own game mode, scripts, maps and vehicles.
- Making and sharing resources, free or paid.
- Accepting money from players, but only through **Tebex**, Cfx.re's authorised commerce partner, and only for things the terms allow.

### What gets servers and creators in trouble

Commonly cited points from the current agreement and Cfx.re's guidance:

- **Selling Rockstar's content.** You cannot sell access to GTA V assets, vehicles, clothing or maps that Rockstar made, or charge for things that are just the base game.
- **Loot boxes and gambling.** Chance based purchases and real money gambling mechanics are not allowed.
- **Selling in-game currency** or anything that can be converted back into real money.
- **Using other people's IP.** Real world brands, logos, copyrighted cars and characters. "Everyone else does it" is not a defence when a takedown arrives.
- **Leaked resources.** Running or sharing leaked paid scripts is a licence violation, can get your server delisted, and leaked code is a common place to hide backdoors.
- **Hosting other people's servers commercially** without authorisation. Only authorised game server providers may do that.

### Tebex and asset escrow

- **Tebex** is the store you connect on the Cfx.re Portal. Players buy packages, and Tebex can run commands on your server to deliver them.
- **Asset escrow** is how paid resources are protected. When a creator sells a resource on Tebex with escrow, the files are encrypted and only run for the buyer's Cfx.re account. As a buyer you download them from the assets section of the Cfx.re Portal, logged in with the account that bought them. Escrowed resources usually leave a `config.lua` and a few "open" files readable so you can configure them.
- If you sell your own work, see [Publishing a resource](/docs/development/publishing).

> [!CAUTION]
> If a "free" copy of a paid script shows up on a random Discord, it is leaked. Beyond the licence issue, leaked resources are one of the most common ways servers get backdoored (remote code that gives someone else admin, or drains your Tebex). Don't run them.

## Checklist before you start

- [ ] GTA V installed and FiveM working on your PC.
- [ ] Cfx.re account created, license key generated on the Portal.
- [ ] Machine chosen (local PC, VPS or GSP) and its IP checked with the [Cfx Blacklist Checker](/tools/cfx-blacklist-checker).
- [ ] Ports `30120` TCP/UDP reachable, `40120` reachable at least from your own IP.
- [ ] MariaDB installed if you want a framework.
- [ ] A text editor (VS Code) and git.

Next: [Server setup overview](/docs/server-setup).

_Last updated: 2026-09-22_

---


# Server setup

## Server setup overview

URL: https://fivemad.com/docs/server-setup

The ways to set up a FiveM server (txAdmin, vanilla, hosting provider), what you download, the folder layout, and the difference between Legacy and Enhanced.

Setting up a FiveM server comes down to four steps: get a license key, download a server build (an **artifact**), run it, and give it a `server.cfg` with resources to start. txAdmin, which ships inside every build, does most of this for you.

## Pick a setup method

The official docs list four ways. They all end up with the same FXServer running the same resources.

| Method | Best for | Guide |
| --- | --- | --- |
| **txAdmin on Windows** | First server, local development, Windows VPS | [Windows setup](/docs/server-setup/windows) |
| **txAdmin on Linux** | VPS and dedicated servers, cheaper hosting | [Linux setup](/docs/server-setup/linux) |
| **Vanilla (no txAdmin)** | Minimal dev servers, containers, people who want full control | Covered at the end of both guides |
| **Game server provider** | People who don't want to manage a machine | Your provider's panel, then the [txAdmin](/docs/txadmin) pages |

We recommend txAdmin for almost everyone. It is maintained by Cfx.re, restarts the server when it crashes, schedules restarts, and its deployer can install QBCore, Qbox or ESX from a recipe in a few minutes.

## Before you start

1. **Create a license key.** Log in at [portal.cfx.re](https://portal.cfx.re), open the server registration keys page (the dashboard has a "Create a Key" quick link), click **Generate Key**, give it a display name and copy the key. It starts with `cfxk_`. Store it somewhere safe, you will paste it into txAdmin or `server.cfg`.
2. **Pick an artifact.** Download the **recommended** build from the official [server download page](https://docs.fivem.net/docs/server-download/) or `runtime.fivem.net/artifacts`. Our [Artifacts page](/artifacts) shows the recommended build and flags builds known to be broken.
3. **Decide where the server lives.** Your PC is fine for testing. For a public server read [Requirements](/docs/getting-started/requirements) first.
4. **Install MariaDB** if you will run a framework. See [Database setup](/docs/server-setup/database).

## What you download

| Platform | File | What is inside |
| --- | --- | --- |
| Windows | `server.7z` | `FXServer.exe`, `citizen/` (scripting runtimes, txAdmin, system resources) and DLLs |
| Linux | `fx.tar.xz` | `run.sh` and an `alpine/` folder with the server and its own libraries |

The artifact is the program. Your **server data** (the `server.cfg` and the `resources` folder) lives somewhere else. Keeping them apart is what makes updating easy: you swap the artifact folder and your data stays untouched.

```text title="Recommended layout"
C:\FXServer\
├─ server\        artifact, replace this folder when you update
└─ txData\        created by txAdmin on first start
   ├─ admins.json
   ├─ default\    txAdmin's own data (config, player database, logs)
   └─ QBCore_A1B2C3.base\   your server data folder: server.cfg + resources\
                            (the deployer suggests a name like this, you can pick any)
```

On Linux the same idea applies, usually under `/home/fivem/` or `/opt/fivem/`.

## How txAdmin and FXServer start

- Run FXServer **without** `+exec server.cfg` and it starts **txAdmin** on port `40120`. txAdmin then starts FXServer for you with your config. This is the normal way.
- Run FXServer **with** `+exec server.cfg` from inside your server data folder and it starts directly, with no txAdmin. This is the "vanilla" way.

Both guides cover both ways.

## FiveM Legacy and FiveM for GTA V Enhanced

In March 2026 Cfx.re announced FiveM for the Enhanced edition of GTA V, and early access for server owners opened on **21 July 2026**. What you need to know as a server owner:

- It is a **separate platform**. The client is separate, and the server is a separate program called **Cfx Server** with its own download on the [server download page](https://docs.fivem.net/docs/server-download/) (files are named `cfx-server.exe` on Windows). Legacy and Enhanced players cannot join each other's servers, so moving is a decision for your whole community.
- Legacy is **not going away**. Upgrading is optional and Legacy support continues.
- Cfx.re's [What's changed](https://docs.fivem.net/docs/developers/legacy-vs-enhanced/) page lists the breaking changes. The big ones: Mono is replaced by .NET 10 for C# resources, pure mode is always on, OneSync is always the full mode (no "legacy" or P2P mode), only the latest game build is supported, KVP files must be migrated, asset escrow was not yet available at launch, and dev tools need `sv_devMode true`.
- Existing streamed assets may need converting with Cfx.re's **Alchemist** tool.
- txAdmin has a separate "FiveM Basic Server (Enhanced)" recipe.

The rest of these docs describe **Legacy FXServer**, which is what almost all resources, frameworks and tutorials target today. Where Enhanced differs in a way that bites, the page says so.

[FiveM Enhanced: Everything That Changed For Server Owners (TraseDev)](https://www.youtube.com/watch?v=WOgYKmAqptg) (YouTube video)

## The pages in this section

1. [Windows setup](/docs/server-setup/windows): step by step with txAdmin, plus vanilla.
2. [Linux setup](/docs/server-setup/linux): Ubuntu or Debian, systemd service, firewall.
3. [server.cfg explained](/docs/server-setup/server-cfg): every common line and what it does.
4. [Updating artifacts safely](/docs/server-setup/updating-artifacts): how to update without breaking things.
5. [Ports and networking](/docs/server-setup/ports-and-networking): port forwarding, server list, proxies.
6. [Database setup](/docs/server-setup/database): MariaDB, HeidiSQL and oxmysql.
7. [Common errors and fixes](/docs/server-setup/common-errors): the errors everyone hits, and the fix.
8. [Security basics](/docs/server-setup/security): ACE, txAdmin accounts, the database, secrets.

> [!TIP]
> Want a ready config instead of writing one? The [server.cfg Generator](/tools/server-cfg-generator) builds a full `server.cfg` with hostname, slots, OneSync, endpoints, tags, resources and ACE permissions.

_Last updated: 2026-09-22_

---

## Set up a FiveM server on Windows

URL: https://fivemad.com/docs/server-setup/windows

Step by step: download the FXServer artifact, extract it, run txAdmin, link your Cfx.re account, deploy a recipe with your license key, and connect. Plus the vanilla way.

This guide sets up a FiveM server on Windows 10, 11 or Windows Server with txAdmin. It works the same on your own PC (for development) and on a Windows VPS. Plan about 15 minutes.

[How to Make a FiveM Server in 2026! (HighwayTrooper)](https://www.youtube.com/watch?v=NjVwsBinE10) (YouTube video)

## What you need

- A Cfx.re account and a **license key** from [portal.cfx.re](https://portal.cfx.re) (see [Server setup overview](/docs/server-setup#before-you-start)).
- [7-Zip](https://www.7-zip.org/) or WinRAR to open `.7z` files.
- **Git for Windows** is optional but useful later.
- **MariaDB** only if you want a framework (QBCore, Qbox, ESX). Install it first, see [Database setup](/docs/server-setup/database).

## 1. Create the folders

Make a folder with a short path and no spaces, for example:

```text
C:\FXServer\server
```

Short paths avoid problems with long resource paths and some tools. Don't put the server in `Program Files`, `Downloads` or a OneDrive synced folder.

## 2. Download the artifact

1. Open the official [server download page](https://docs.fivem.net/docs/server-download/) (or `https://runtime.fivem.net/artifacts/fivem/build_server_windows/master/`).
2. Pick **FiveM / RedM**, **Windows**, **Recommended** and download `server.7z`.
3. Check the build number against our [Artifacts page](/artifacts), which flags builds with known problems.

> [!NOTE]
> The Enhanced platform (Cfx Server) is a different download on the same page. Pick the FiveM / RedM (Legacy) build unless you know you want Enhanced. See [Legacy and Enhanced](/docs/server-setup#fivem-legacy-and-fivem-for-gta-v-enhanced).

## 3. Extract it

Open `server.7z` with 7-Zip and extract everything into `C:\FXServer\server`. You should now have `C:\FXServer\server\FXServer.exe` and a `citizen` folder next to it.

> [!TIP]
> Windows Defender scanning every file makes FXServer start slowly. The official FAQ suggests excluding the folder: open PowerShell as administrator and run `Add-MpPreference -ExclusionPath 'C:\FXServer\'`.

## 4. Start txAdmin

Double click `FXServer.exe`. A console window opens and, because you did not pass `+exec server.cfg`, FXServer starts **txAdmin**. It creates `C:\FXServer\txData` and opens `http://localhost:40120` in your browser. The console also prints a 4 digit **PIN**.

If the browser does not open, go to `http://localhost:40120` yourself. On a VPS, use `http://YOUR_VPS_IP:40120` from your own PC (and open TCP 40120 in the Windows firewall, ideally only for your IP).

## 5. Link your account

1. Check that the PIN is filled in and click **Link Account**.
2. Log in with your Cfx.re (forum) account and click **Yes, Allow**.
3. Create a **backup password**. You will use it if Cfx.re login is ever down, so save it in a password manager.

This makes you the **master admin** of this txAdmin.

## 6. Run the setup and deployer

1. Enter a **server name** and click **Next**.
2. Choose **Popular Recipes**.
3. Pick a recipe:
   - **FiveM Basic Server (Legacy)**, sometimes shown as CFX Default: a clean, framework free server. Best for learning and for vMenu servers.
   - **QBCore**, **Qbox** or **ESX Legacy**: full roleplay frameworks. These need MariaDB running. See [Popular recipes](/docs/txadmin/popular-recipes).
4. Confirm the **data location** (the default `txData\<name>.base` is fine) and click **Save**.
5. The **Recipe Deployer** shows the recipe YAML. Click **Next**.
6. Paste your **license key**. For framework recipes, fill in the **database** host (`localhost`), port (`3306`), user (`root`) and password. Leave the database name empty and txAdmin generates one.
7. Click **Run Recipe**. txAdmin downloads the resources and, for frameworks, imports the SQL. This takes a minute or two.
8. Review the generated `server.cfg` and click **Save & Run Server**.

The live console in txAdmin now shows the server starting. When you see resources starting and no red errors, it is up.

> [!IMPORTANT]
> QBCore and some other recipes install NPM packages with yarn on first start. Let that finish before you restart. The QBCore docs say this explicitly.

## 7. Connect

1. Start FiveM.
2. Press <kbd>F8</kbd> to open the client console.
3. Type `connect localhost:30120` (same PC) or `connect YOUR_PUBLIC_IP:30120` and press <kbd>Enter</kbd>.

You can also use the direct connect box in the FiveM main menu with the same address. To let friends connect, see [Ports and networking](/docs/server-setup/ports-and-networking).

## 8. Make it start on its own

txAdmin restarts FXServer on crashes, but not the whole machine. On a VPS, start FXServer when Windows boots:

1. Create `C:\FXServer\start.bat`:

```bat title="C:\FXServer\start.bat"
@echo off
cd /d C:\FXServer\server
FXServer.exe
```

2. Open **Task Scheduler**, create a task that runs `start.bat` **At startup**, "Run whether user is logged on or not", with the account that owns the folder.
3. In txAdmin, **Settings > FXServer**, turn on starting the server automatically when txAdmin starts.

## Folder layout after setup

```text
C:\FXServer\
├─ server\                 FXServer.exe + citizen\  (replace to update)
├─ start.bat
└─ txData\
   ├─ admins.json          txAdmin accounts
   ├─ default\             txAdmin config, logs, player database
   └─ MyServer.base\
      ├─ server.cfg
      └─ resources\
```

Your own resources go in `resources\[local]\` and get an `ensure` line in `server.cfg`. See [Installing resources](/docs/resources).

## The vanilla way (no txAdmin)

Useful for a throwaway dev server or when you want to see exactly what runs. From the official vanilla guide:

```bat
cd /d C:\FXServer
git clone https://github.com/citizenfx/cfx-server-data.git server-data
```

Create `C:\FXServer\server-data\server.cfg`:

```cfg title="server-data/server.cfg"
endpoint_add_tcp "0.0.0.0:30120"
endpoint_add_udp "0.0.0.0:30120"

ensure mapmanager
ensure chat
ensure spawnmanager
ensure sessionmanager
ensure basic-gamemode
ensure hardcap

sv_hostname "My dev server"
sv_maxclients 8
sv_licenseKey "cfxk_your_key_here"
sv_enforceGameBuild 3751
set onesync on
```

Then start it from inside the data folder:

```bat
cd /d C:\FXServer\server-data
C:\FXServer\server\FXServer.exe +exec server.cfg
```

> [!WARNING]
> Always start FXServer from inside the server data folder (or tell txAdmin where it is). If you start it from somewhere else, it cannot find `resources` and you get "no resources found" or "couldn't find resource" errors.

## Next steps

- Read [server.cfg explained](/docs/server-setup/server-cfg) so you know what every line does.
- Set up [txAdmin admins, bans and scheduled restarts](/docs/txadmin/everyday-admin).
- Add [vMenu or other resources](/docs/resources/recommended).
- Write [your first resource](/docs/development/first-resource).

_Last updated: 2026-09-22_

---

## Set up a FiveM server on Linux

URL: https://fivemad.com/docs/server-setup/linux

Run FXServer and txAdmin on Ubuntu or Debian: dependencies, a dedicated user, the Linux artifact, a systemd service or tmux, the ufw firewall and MariaDB.

This guide sets up FXServer with txAdmin on a fresh **Ubuntu 22.04 / 24.04** or **Debian 12** VPS. Other distributions work too, since the Linux artifact ships its own libraries in an `alpine` folder, but the package commands below are for Debian based systems. You need SSH access with a user that can run `sudo`.

[Linux-Ubuntu FiveM Server Install Guide (Enix Hosting)](https://www.youtube.com/watch?v=kz1TozHDa5Q) (YouTube video)

## 1. Update the system and install tools

```bash
sudo apt update && sudo apt upgrade -y
sudo apt install -y xz-utils git curl wget tmux ufw
```

`xz-utils` is required to extract the artifact. `git` is for cloning resources, `tmux` for running the server in a detachable session, `ufw` for the firewall.

## 2. Create a user for the server

Never run a game server as `root`. Create a dedicated user and switch to it:

```bash
sudo adduser --disabled-password --gecos "" fivem
sudo -iu fivem
mkdir -p ~/server
cd ~/server
```

Everything below runs as `fivem` unless it starts with `sudo`.

## 3. Download the Linux artifact

1. Open `https://runtime.fivem.net/artifacts/fivem/build_proot_linux/master/` in your browser.
2. Pick the **recommended** build (check it on our [Artifacts page](/artifacts)) and copy the link to its `fx.tar.xz`.
3. Download and extract it on the server:

```bash
cd ~/server
wget https://runtime.fivem.net/artifacts/fivem/build_proot_linux/master/XXXXX-<hash>/fx.tar.xz
tar xf fx.tar.xz
rm fx.tar.xz
ls
# alpine  run.sh
```

Replace the URL with the one you copied. The build folder name changes with every release, so don't reuse an old link from a tutorial.

## 4. Open the firewall

Allow SSH first so you don't lock yourself out, then the game ports:

```bash
sudo ufw allow OpenSSH
sudo ufw allow 30120/tcp
sudo ufw allow 30120/udp
# txAdmin web panel: better to allow only your own IP
sudo ufw allow from YOUR_HOME_IP to any port 40120 proto tcp
sudo ufw enable
sudo ufw status
```

If your home IP changes often, you can open 40120 to everyone (`sudo ufw allow 40120/tcp`), but then use a strong password and 2FA on every txAdmin account. See [Security basics](/docs/server-setup/security). Many VPS providers also have a firewall in their web panel: open the same ports there.

## 5. First start with txAdmin

```bash
cd ~/server
bash run.sh
```

FXServer starts txAdmin and prints something like:

```text
[txAdmin] Use the PIN below to register:
[txAdmin]  1234
[txAdmin] http://YOUR_VPS_IP:40120/
```

Open that address in your browser on your own PC and follow the same steps as on Windows: **Link Account** with your Cfx.re login, create a backup password, pick a recipe, paste your license key, run the recipe, then **Save & Run Server**. The full walkthrough is in [First setup and the deployer](/docs/txadmin/first-setup).

On Linux, txAdmin creates `txData` next to `run.sh` by default (`~/server/txData`). You can change it with the `TXHOST_DATA_PATH` environment variable.

Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to stop it once setup is done. Next we make it run in the background.

## 6. Keep it running

### Option A: tmux (simple)

```bash
tmux new -s fivem
cd ~/server && bash run.sh
```

Detach with <kbd>Ctrl</kbd>+<kbd>B</kbd> then <kbd>D</kbd>. Reattach later with `tmux attach -t fivem`. The server keeps running after you log out, but not after a reboot. `screen` works the same way (`screen -S fivem`, detach with <kbd>Ctrl</kbd>+<kbd>A</kbd> then <kbd>D</kbd>, reattach with `screen -r fivem`).

### Option B: systemd service (starts on boot)

Create the unit file as root:

```ini title="/etc/systemd/system/fivem.service"
[Unit]
Description=FiveM server (txAdmin)
After=network-online.target mariadb.service
Wants=network-online.target

[Service]
Type=simple
User=fivem
Group=fivem
WorkingDirectory=/home/fivem/server
ExecStart=/bin/bash /home/fivem/server/run.sh
Restart=on-failure
RestartSec=10
# Optional txAdmin settings, see the txAdmin env-config docs
# Environment=TXHOST_TXA_PORT=40120

[Install]
WantedBy=multi-user.target
```

Enable and start it:

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now fivem
sudo systemctl status fivem
journalctl -u fivem -f      # follow the console output
```

txAdmin still restarts FXServer itself when it crashes. systemd restarts txAdmin if the whole process dies, and starts everything on boot. In txAdmin **Settings > FXServer**, enable starting the server when txAdmin starts, so a reboot brings the game server back without you logging in.

> [!NOTE]
> With systemd you do not have an interactive console. Use txAdmin's **Live Console** page to type server commands.

## 7. MariaDB (for frameworks)

```bash
sudo apt install -y mariadb-server
sudo mariadb-secure-installation
```

Then open the MariaDB shell with `sudo mariadb` and create a database user for FiveM instead of using `root`:

```sql
CREATE USER 'fivem'@'localhost' IDENTIFIED BY 'a-long-random-password';
GRANT ALL PRIVILEGES ON *.* TO 'fivem'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```

`GRANT ALL ON *.*` lets the txAdmin deployer create the database for you. After deploying you can tighten it to the one database (`GRANT ALL ON yourdb.* ...`). Keep MariaDB bound to `127.0.0.1` (the default on Debian and Ubuntu) and never open port 3306 in the firewall. More in [Database setup](/docs/server-setup/database).

## Linux gotchas

- **File names are case sensitive.** `ensure qb-Core` will not find `qb-core`. Stream files referenced in metas must match their exact case too.
- **Line endings.** Scripts edited on Windows work fine, but shell scripts (`.sh`) with Windows line endings fail with `bad interpreter`. Convert with `sed -i 's/\r$//' script.sh`.
- **Permissions.** If you upload files as `root` (for example with SFTP as root), the `fivem` user cannot read them. Fix with `sudo chown -R fivem:fivem /home/fivem/server`.
- **Paths with spaces or brackets.** Quote them in the shell: `cd "resources/[local]"`.

## The vanilla way (no txAdmin)

From the official guide:

```bash
git clone https://github.com/citizenfx/cfx-server-data.git ~/server-data
cd ~/server-data
nano server.cfg   # same content as the Windows vanilla example
bash ~/server/run.sh +exec server.cfg
```

You must start it from inside the data folder, with `+exec server.cfg`. See the [Windows guide](/docs/server-setup/windows#the-vanilla-way-no-txadmin) for a minimal `server.cfg`.

## Updating later

Stop the server, move the old `alpine` folder and `run.sh` aside, extract the new `fx.tar.xz` in the same place, start again. Your `txData` is untouched. The full routine, including rollback, is in [Updating artifacts safely](/docs/server-setup/updating-artifacts).

_Last updated: 2026-09-22_

---

## server.cfg explained line by line

URL: https://fivemad.com/docs/server-setup/server-cfg

What every common server.cfg line does: endpoints, hostname, tags, license key, slots, game build, OneSync, ensure order, convars, ACE permissions and splitting configs.

`server.cfg` is not a special format. It is a list of **server console commands** that FXServer runs from top to bottom when it starts, exactly as if you typed them into the console. That explains most of its behaviour: order matters, a typo is an "unknown command", and anything you can type in the console you can put in the file.

> [!TIP]
> Don't want to write it by hand? The [server.cfg Generator](/tools/server-cfg-generator) builds a complete file with hostname, slots, OneSync, endpoints, tags, resources and ACE permissions.

## A complete example

This is a sensible config for a small public server without a framework. The sections below explain each part.

```cfg title="server.cfg"
## Network
endpoint_add_tcp "0.0.0.0:30120"
endpoint_add_udp "0.0.0.0:30120"

## Server list info
sv_hostname "^2My Server ^7| Custom cars | Discord in desc"
sets sv_projectName "My Server"
sets sv_projectDesc "A small freeroam server with custom cars and friendly admins."
sets tags "freeroam, drift, cars"
sets locale "en-US"
load_server_icon myLogo.png
sets banner_detail "https://example.com/banner_detail.png"
sets banner_connecting "https://example.com/banner_connecting.png"

## Core settings
sv_licenseKey "cfxk_xxxxxxxxxxxxxxxxxxxx_xxxxxx"
sv_maxclients 32
sv_enforceGameBuild 3751
set onesync on
sv_endpointPrivacy true
sv_scriptHookAllowed 0
set steam_webApiKey "none"
set resources_useSystemChat true

## Resources (order matters)
ensure mapmanager
ensure chat
ensure spawnmanager
ensure basic-gamemode
ensure hardcap

ensure [local]

## Permissions
add_ace group.admin command allow
add_ace group.admin command.quit deny
add_principal identifier.fivem:123456 group.admin
```

## Network: endpoints

```cfg
endpoint_add_tcp "0.0.0.0:30120"
endpoint_add_udp "0.0.0.0:30120"
```

These bind the server to port `30120` on every network interface, TCP for HTTP (connection info, downloads) and UDP for game traffic. Both lines are needed. Change `30120` to run a second server on the same machine (for example `30121`).

When txAdmin deploys a server, it writes these lines for you (the `{{serverEndpoints}}` placeholder in recipes), and the `TXHOST_FXS_PORT` variable can force a port. See [Ports and networking](/docs/server-setup/ports-and-networking).

## Server list info

| Line | What it does |
| --- | --- |
| `sv_hostname "..."` | The name in the server browser. Supports colour codes like `^1` red, `^2` green, `^7` white. Preview them with [Draw Text Colors](/tools/text-colors). |
| `sets sv_projectName "..."` | Your community's name. Shown in the server browser details. Required for proper listing. |
| `sets sv_projectDesc "..."` | One sentence describing the server. Also required for proper listing. |
| `sets tags "a, b, c"` | Comma separated tags for server browser search. |
| `sets locale "en-US"` | The server's main language. The default recipes use `root-AQ`, which means "not set", so change it. |
| `load_server_icon file.png` | Server icon, a **96x96 PNG** in the server data folder. |
| `sets banner_detail` / `sets banner_connecting` | Image URLs for the server detail page and the connecting screen. |

`set` stores a convar, `sets` also publishes it in the server info (so the server browser can show it), and `setr` replicates it to clients so client scripts can read it with `GetConvar`. Use `setr` for things like `voice_useNativeAudio` that client code needs.

## Core settings

### `sv_licenseKey`

Your key from [portal.cfx.re](https://portal.cfx.re). Without a valid key the server will not start. Never paste it in screenshots or public repos. If it leaks, regenerate it on the Portal.

### `sv_maxclients`

Maximum players, 1 to 2048. Up to **48** is free. Anything above 48 needs a Cfx.re Element Club tier (Argentum or higher) on the account that owns the key.

### `sv_enforceGameBuild`

Forces clients to run a specific GTA V update, which unlocks that update's vehicles, clothing, weapons and map changes. It can only be set at startup. Valid builds for FiveM include:

| Build | DLC |
| --- | --- |
| 2699 | The Criminal Enterprises |
| 2802 | Los Santos Drug Wars |
| 2944 | San Andreas Mercenaries |
| 3095 | The Chop Shop |
| 3258 | Bottom Dollar Bounties |
| 3407 | Agents of Sabotage |
| 3570 | Money Fronts |
| 3751 | A Safehouse in the Hills |
| 3889 | The Kortz Center Heist |

Every build includes everything before it. The txAdmin default recipes currently set `3751`. Pick the build your resources support: some older scripts and MLOs break on the newest build, and players have to download the matching game data the first time they join. You can check a build's content in the [Model & Hash Browser](/tools/model-hash-browser) (vehicles, peds and weapons).

> [!NOTE]
> FiveM for GTA V Enhanced only supports the latest game build, so this setting works differently there.

### `onesync`

```cfg
set onesync on
```

Turns on OneSync, the server side sync. Values are `on`, `legacy` (compatibility mode, not recommended) and `off`. Every current framework needs `on`, and you need it for more than 32 players, routing buckets, server side entity creation and state bags on entities. Use `set onesync on` in the cfg (or `+set onesync on` on the command line). txAdmin also exposes it in its settings.

### Privacy and client mods

| Line | Meaning |
| --- | --- |
| `sv_endpointPrivacy true` | Hides player IP addresses in the public player list output. Turn it on. |
| `sv_scriptHookAllowed 0` | Blocks clients with ScriptHookV (singleplayer mod menus). Default is off, keep it off. |
| `sv_pureLevel 1` | Blocks modified game files except audio and known graphics mods. `2` blocks all modified files. Leave it out to allow anything. |
| `sv_entityLockdown strict` | Clients cannot create networked entities, only the server can. Great against cheaters, but many older scripts spawn things client side and will break. Test first. |

### Steam and chat

- `set steam_webApiKey "none"` disables Steam identifiers. If your scripts need `steam:` identifiers, put a key from [steamcommunity.com/dev/apikey](https://steamcommunity.com/dev/apikey).
- `set resources_useSystemChat true` makes `ensure chat` use the chat resource built into the artifact instead of an old copy in your resources folder. The default txAdmin recipe sets this.

## Resources: `ensure`, `start` and order

```cfg
ensure mapmanager
ensure chat
ensure spawnmanager
ensure [local]
```

- `ensure name` starts a resource, or restarts it if it is already running. It is the one you want in `server.cfg`.
- `start name` starts it only if it is stopped. `stop name` stops it. `restart name` restarts a running one.
- `ensure [folder]` starts every resource inside a bracketed category folder.
- `name` is the **folder name**, not what the manifest says.

**Order matters.** Resources start in the order of the lines. Libraries and databases first, then the framework, then everything that depends on it:

```cfg
ensure oxmysql
ensure ox_lib
ensure qbx_core        # or qb-core, es_extended
ensure ox_target
ensure ox_inventory
ensure [qbx]
ensure [standalone]
ensure [local]         # your own stuff last
```

If a resource lists `dependencies` in its manifest, FXServer starts those first anyway, but explicit order saves you confusing errors. More in [Installing resources](/docs/resources).

## Splitting the config with `exec`

Big servers split their config. `exec` runs another file:

```cfg
exec permissions.cfg
exec resources.cfg
exec @vMenu/config/permissions.cfg
```

Paths are relative to the server data folder, and `@resource/path` points into a resource. The Qbox recipe, for example, splits settings into `permissions.cfg`, `ox.cfg`, `voice.cfg` and `misc.cfg`.

A common trick is a `secrets.cfg` that holds the license key and database password and is **not** in git:

```cfg title="secrets.cfg"
sv_licenseKey "cfxk_..."
set mysql_connection_string "mysql://fivem:password@localhost/fivem?charset=utf8mb4"
```

```cfg title="server.cfg"
exec secrets.cfg
```

## Database connection

Frameworks use `oxmysql`, which reads one convar:

```cfg
set mysql_connection_string "mysql://user:password@localhost:3306/database?charset=utf8mb4"
```

The key value form `"user=root;password=12345;host=localhost;port=3306;database=fivem"` also works. Avoid special characters like `@ : / ? # & =` in the password. See [Database setup](/docs/server-setup/database).

## Permissions (ACE)

```cfg
add_ace group.admin command allow         # admins can run any command
add_ace group.admin command.quit deny     # except quit
add_principal identifier.fivem:123456 group.admin
add_principal identifier.discord:111111111111111111 group.admin
```

- `add_ace <principal> <object> <allow|deny>` creates a rule.
- `add_principal <child> <parent>` puts a player (or group) into a group.
- Identifiers: `identifier.fivem:` (Cfx.re account ID), `identifier.license:`, `identifier.discord:`, `identifier.steam:`.

The txAdmin recipes add `{{addPrincipalsMaster}}`, which the deployer replaces with your own identifiers, so the master admin gets `group.admin` automatically. More in [Security basics](/docs/server-setup/security).

## Listing, private servers and proxies

| Line | Use |
| --- | --- |
| `sv_master1 ""` | Makes the server private: it will not appear in the server list. Leave it commented out (`#sv_master1 ""`) for a public server. |
| `sv_lan true` | LAN only server. |
| `sv_listingIpOverride "1.2.3.4"` | Overrides the IP sent to the server list, for NAT setups. |
| `sv_forceIndirectListing true` | Don't advertise the server with its real IP. |
| `sv_listingHostOverride "play.example.com"` | Overrides the host name sent to the list, for proxy setups. |
| `sv_proxyIPRanges "a.b.c.d/24"` | IP ranges of your own proxies, so the real player IP is used. |

These are advanced. See [Ports and networking](/docs/server-setup/ports-and-networking) before touching them.

## Things that don't belong in server.cfg

- `rcon_password`: RCON is off when unset, and txAdmin's live console replaces it. Leave it unset.
- Old lines copied from ancient tutorials, like `start essentialmode`, or a `sv_master1 ""` left over from a private test server.
- Anything with your password if the file is shared or in git: move it to `secrets.cfg`.

## After editing

Changes to `server.cfg` apply on the next server restart. In txAdmin you can edit the file under **CFG Editor** and restart from the dashboard. To pick up a new resource without a restart, type `refresh` then `ensure name` in the live console.

_Last updated: 2026-09-22_

---

## Updating FXServer artifacts safely

URL: https://fivemad.com/docs/server-setup/updating-artifacts

How to pick a server artifact, avoid broken builds, update on Windows and Linux without losing data, test first, and roll back when something goes wrong.

An **artifact** is one build of FXServer. Cfx.re publishes new builds all the time, and some of them break things. Updating is easy, updating *safely* takes five extra minutes and saves you a broken Saturday night.

[How to update FiveM Server Artifacts / TXAdmin (HighwayTrooper)](https://www.youtube.com/watch?v=UZXnK8IjT20) (YouTube video)

## Which build to use

| Branch | What it means | Use it for |
| --- | --- | --- |
| **Recommended** | The build Cfx.re currently recommends for production. | Your live server. |
| **Latest** | The newest build that passed CI. May contain fresh bugs. | Testing new features, dev servers. |
| **Optional / other** | Older or newer numbered builds in the list. | Rolling back, or when a resource requires a minimum build. |

Download from the official [server download page](https://docs.fivem.net/docs/server-download/) or directly:

- Windows: `https://runtime.fivem.net/artifacts/fivem/build_server_windows/master/`
- Linux: `https://runtime.fivem.net/artifacts/fivem/build_proot_linux/master/`

Before you update, open our [Artifacts page](/artifacts). It shows the current recommended build, the full list of builds, and flags the ones the community has reported as **broken** (crashes, broken OneSync, broken txAdmin and so on). It is based on the JG Scripts artifacts database.

> [!IMPORTANT]
> Old artifacts stop working. Cfx.re blocks very old builds from the server list and eventually from starting at all, and new game builds need new artifacts. "Never update" is not an option, but "update carefully" is.

## Why updates break things

- A resource uses a native or behaviour that changed.
- A build has a regression (it happens, that's why the broken list exists).
- The new build bumps the bundled **txAdmin** version and something in its config changed.
- Resources that require a minimum build (`dependency '/server:XXXX'` in their manifest) or newer runtimes (for example `node_version '22'`) only work on newer builds, and the other way around.

## The safe routine

### 1. Read before you download

- Check the build on [/artifacts](/artifacts).
- Skim the Announcements category on [forum.cfx.re](https://forum.cfx.re) and the txAdmin Discord for anything about the build.

### 2. Back up

- Your **server data folder** (`server.cfg`, `resources`) is not touched by an update, but back it up anyway, or better, keep it in git.
- **txData** (txAdmin accounts, bans, warns, player database, settings). Copy the whole folder.
- Your **database**. Dump it with HeidiSQL (Tools > Export database as SQL) or on Linux:

```bash
mysqldump -u fivem -p --single-transaction yourdb > backup-$(date +%F).sql
```

### 3. Test on a copy (for big servers)

Run the new artifact against a copy of your server data on another port with `TXHOST_FXS_PORT` and a separate `TXHOST_DATA_PATH`, join it, and click through the core features: character select, inventory, a job, a vehicle shop, the phone. Five minutes of testing finds most breakage.

### 4. Swap the artifact

**Windows**

1. Stop the server in txAdmin and close the FXServer window.
2. Rename `C:\FXServer\server` to `C:\FXServer\server-old`.
3. Extract the new `server.7z` to a fresh `C:\FXServer\server`.
4. Start `FXServer.exe` (or your `start.bat` / scheduled task) again.

**Linux**

```bash
sudo systemctl stop fivem        # or stop it in tmux
cd /home/fivem
mv server server-old
mkdir server && cd server
wget https://runtime.fivem.net/artifacts/fivem/build_proot_linux/master/XXXXX-<hash>/fx.tar.xz
tar xf fx.tar.xz && rm fx.tar.xz
# if your txData lived inside the old folder, move it back:
mv ../server-old/txData ./ 2>/dev/null
sudo systemctl start fivem
```

> [!WARNING]
> On Linux the default `txData` location is **next to `run.sh`**, so it sits inside the artifact folder. Move it back after swapping (as above), or set `TXHOST_DATA_PATH` to a folder outside the artifact so this never bites you.

Never extract a new artifact **over** the old one. Leftover files from the previous build cause strange errors.

### 5. Check it

- The txAdmin dashboard shows the new FXServer version.
- The live console has no new red errors during startup.
- Join and test the same things as in step 3.
- Look at txAdmin's performance chart after an hour with players.

### 6. Roll back if needed

Stop the server, delete the new artifact folder, rename `server-old` back to `server`, start. That's why you kept it. Once the new build has been fine for a few days, delete `server-old`.

## Updating txAdmin

txAdmin is part of the artifact. There is nothing separate to download: when you update FXServer, you update txAdmin. See [Updating txAdmin and FXServer](/docs/txadmin/updating).

## Game build updates

When Rockstar ships a GTA V update, FiveM adds the new build to `sv_enforceGameBuild`. You usually need a recent artifact to use it. Update the artifact first, then change `sv_enforceGameBuild` in [server.cfg](/docs/server-setup/server-cfg), then restart. Players download the new game data on their next join.

## Quick checklist

- [ ] Build checked on [/artifacts](/artifacts), not on the broken list.
- [ ] txData, server data and database backed up.
- [ ] Old artifact folder renamed, not overwritten.
- [ ] txData location checked (Linux).
- [ ] Server starts cleanly, core features tested.
- [ ] Old folder kept for a few days.

_Last updated: 2026-09-22_

---

## Ports and networking

URL: https://fivemad.com/docs/server-setup/ports-and-networking

Which ports FiveM and txAdmin use, how to port forward at home, why a server is missing from the list, multiple servers on one IP, proxies and the listing convars.

Most "my friends can't join" and "my server isn't in the list" problems are network problems, not FiveM problems. This page covers the ports, home port forwarding, the server list and the more advanced proxy options.

[How To Port Forward A FiveM Server! (HTNetwork)](https://www.youtube.com/watch?v=Y0jLMc_zEDw) (YouTube video)

## The ports

| Port | Protocol | Used by | Who needs to reach it |
| --- | --- | --- | --- |
| `30120` | **TCP and UDP** | FXServer: TCP for HTTP (info, file downloads, connection handshake), UDP for game traffic | Every player |
| `40120` | TCP | txAdmin web panel | Only you and your admins |
| `3306` | TCP | MariaDB / MySQL | Only the server itself. Never open it to the internet. |

Both TCP **and** UDP must be open on `30120`. Opening only TCP gives the classic symptom: the server shows up and players can see the player count, but joining hangs or times out.

You can change the game port with the `endpoint_add_tcp` / `endpoint_add_udp` lines in [server.cfg](/docs/server-setup/server-cfg), and the txAdmin port with the `TXHOST_TXA_PORT` environment variable. txAdmin refuses to use `30120` for its panel, and the game port cannot be `40120`, to avoid mixing them up.

## Hosting from home: port forwarding

If the server runs on a PC at home, your router must forward the port to that PC.

1. Give the server PC a fixed local IP (a DHCP reservation in the router, or a static IP in Windows), for example `192.168.1.50`.
2. In the router's admin page, find **Port Forwarding** (sometimes "Virtual Server" or "NAT").
3. Add a rule: external port `30120`, internal port `30120`, protocol **TCP and UDP** (or two rules), target `192.168.1.50`.
4. Allow FXServer in **Windows Defender Firewall** (Windows asks the first time you run it, allow both private and public if you're unsure, or add inbound rules for port 30120 TCP and UDP).
5. Test from outside: ask a friend to `connect YOUR_PUBLIC_IP:30120` in the F8 console, or use a port checker like canyouseeme.org while the server runs.

> [!WARNING]
> Some ISPs use **CGNAT**: your router doesn't have a real public IP, so port forwarding can't work. If the WAN IP in your router differs from what "what is my IP" sites show, you are probably behind CGNAT. Ask your ISP for a public IP, or rent a VPS.

Don't forward `40120` at home unless you really need remote access, and if you do, use strong passwords and 2FA.

## Why isn't my server in the list?

Straight from the official server FAQ, plus experience:

1. **Ports.** Bad port forwarding or firewall rules are the usual cause. Test with direct connect first: `connect IP:30120` in F8. If that fails, it's the network.
2. **Private mode.** Make sure `sv_master1 ""` is commented out (`#sv_master1 ""`) or not present.
3. **Project info.** Set `sets sv_projectName` and `sets sv_projectDesc`.
4. **Time.** It can take **up to 8 minutes** after start for a server to appear.
5. **Blacklisted IP.** Some hosting ranges are blocked from the platform. Check with the [Cfx Blacklist Checker](/tools/cfx-blacklist-checker).
6. **Outdated artifact.** Very old builds are refused. Update, see [Updating artifacts safely](/docs/server-setup/updating-artifacts).

To see what the world sees, enter your IP:port or join code in the [Server Status Checker](/tools/server-status-checker). It shows players, build, resources and map as reported by your server.

## Join links

Every listed server gets a `cfx.re/join/xxxxxx` code tied to its license key. You can share it instead of an IP, and it keeps working if the IP changes. Find it in the server browser details, in txAdmin, or in the Discord status embed (`{{serverJoinUrl}}`). To show your live status on a website or Discord, use a [Server Status Badge](/tools/server-uptime-badge).

## Running more than one server on one machine

Give each server its own:

- **game port**: `endpoint_add_tcp "0.0.0.0:30121"` and `endpoint_add_udp "0.0.0.0:30121"`,
- **license key** (one key per server),
- **txData** (`TXHOST_DATA_PATH`) and **txAdmin port** (`TXHOST_TXA_PORT=40121`),
- **database**.

txAdmin's docs strongly recommend separate txData folders per server, otherwise `admins.json` conflicts.

```bat title="start-dev.bat (Windows example from the txAdmin docs pattern)"
@echo off
set TXHOST_DATA_PATH=C:\FXServer\txData-dev
set TXHOST_TXA_PORT=40121
set TXHOST_FXS_PORT=30121
set TXHOST_MAX_SLOTS=8
C:\FXServer\server\FXServer.exe
```

## OneSync and networking

OneSync (`set onesync on`) is the server side sync model: the server tracks all entities and decides which client sees what, culling entities to a radius (424 units by default) around each player. It lowers bandwidth per client compared to the old peer to peer model, allows up to 2048 slots with the right tier, and enables routing buckets and entity state bags. Every modern framework expects it. See [State bags and OneSync](/docs/development/state-bags-onesync) for what it means for scripts.

## Proxies, DDoS protection and Cloudflare

Large servers often put a proxy or DDoS filter in front of FXServer so the real IP stays hidden. This is advanced and easy to get wrong. The relevant convars (from the official server commands reference):

| Convar | What it does |
| --- | --- |
| `sv_forceIndirectListing true` | Prevents the server from being advertised with its real IP. |
| `sv_listingIpOverride "1.2.3.4"` | Overrides the IP sent to the server list (useful behind NAT or a proxy). |
| `sv_listingHostOverride "play.example.com"` | Overrides the host name sent to the list (useful behind a proxy). |
| `sv_proxyIPRanges "1.2.3.0/24 5.6.7.0/24"` | Space separated CIDR ranges of your own proxies, so FXServer trusts forwarded client IPs from them. |
| `sv_requestParanoia 0-3` | Extra checks against proxy based HTTP floods. |
| `sv_endpointPrivacy true` | Hides player IPs in public output. |

Some things to know before you try:

- **Cloudflare's normal (orange cloud) proxy only handles HTTP(S) traffic**, not the UDP game traffic, so you can't just point a proxied DNS record at FXServer. Setups that proxy FiveM traffic use a proxy that supports both TCP and UDP (Cloudflare Spectrum on paid plans, or a dedicated game DDoS provider), or a separate file server/CDN for downloads.
- If you set up a proxy without `sv_proxyIPRanges`, every player appears to come from the proxy's IP, which breaks IP bans and some anticheats.
- Test with a small group first. A broken proxy config makes the server invisible or unjoinable.

For the **txAdmin panel**, the txAdmin team's advice is not to expose it with SSL inside txAdmin but to put a reverse proxy (nginx, Caddy) or a Cloudflare Tunnel in front of it if you want HTTPS.

## Quick diagnosis

| Symptom | Likely cause |
| --- | --- |
| Nobody can connect, not even with direct connect | Port closed, wrong IP, firewall, CGNAT |
| Server in list, joining times out at "handshaking" or "connecting" | UDP 30120 blocked |
| Works on LAN (`192.168.x.x`), not from outside | Router port forward or ISP |
| Direct connect works, not in list | `sv_master1`, missing project name/desc, wait 8 minutes, blacklisted IP |
| Everyone shows the same IP in txAdmin | Proxy without `sv_proxyIPRanges` |

_Last updated: 2026-09-22_

---

## Database setup: MariaDB, HeidiSQL and oxmysql

URL: https://fivemad.com/docs/server-setup/database

Install MariaDB on Windows or Linux, manage it with HeidiSQL, connect FiveM with oxmysql and mysql_connection_string, import SQL files and back up your data.

Frameworks like QBCore, Qbox and ESX store characters, money, vehicles and inventories in a SQL database. FiveM talks to it through a resource, almost always **oxmysql**. A plain vMenu server does not need any of this.

[How to Setup a Database for Your FiveM Server (TraseDev)](https://www.youtube.com/watch?v=lIlFkSaNACU) (YouTube video)

## Use MariaDB, not XAMPP

- **MariaDB** is what the frameworks target. The oxmysql docs say MariaDB is "highly recommended for compatibility and improved performance" over MySQL 8 (which has reserved keyword and default value differences that break some scripts).
- **Qbox** requires at least MariaDB 10.9 and recommends a current LTS release. The **ESX** docs say to use MariaDB only.
- **XAMPP** bundles an old MariaDB with a web server you don't need. Both the ESX and Qbox docs tell you not to use it. If you're on XAMPP now, dump your database and move it to a real MariaDB install.

## Install on Windows

1. Download the MSI from [mariadb.org/download](https://mariadb.org/download/) (pick the current LTS).
2. Run it. Set a **root password** and keep "Install as service" checked. Leave "Enable access from remote machines for root" **unchecked**.
3. The Windows installer includes **HeidiSQL**, a free GUI for the database. Keep it selected.
4. Default port is `3306`. Keep it unless something else uses it.

## Install on Linux

```bash
sudo apt install -y mariadb-server
sudo mariadb-secure-installation
```

Then create a dedicated user in the MariaDB shell (`sudo mariadb`):

```sql
CREATE USER 'fivem'@'localhost' IDENTIFIED BY 'a-long-random-password';
GRANT ALL PRIVILEGES ON *.* TO 'fivem'@'localhost';
FLUSH PRIVILEGES;
```

The broad grant lets the txAdmin deployer create a database. After deploying, you can restrict it to one database: `GRANT ALL PRIVILEGES ON qbox_4f2a.* TO 'fivem'@'localhost';` and revoke the rest. Manage it from your PC with HeidiSQL over an **SSH tunnel** (HeidiSQL supports "MariaDB or MySQL (SSH tunnel)") instead of opening port 3306.

## HeidiSQL basics

1. Open HeidiSQL, click **New**, network type **MariaDB or MySQL (TCP/IP)**, host `127.0.0.1`, user `root` (or `fivem`), your password, port `3306`. Save and **Open**.
2. **Create a database**: right click the connection > **Create new > Database**. Collation `utf8mb4_unicode_ci` or `utf8mb4_general_ci`.
3. **Import a `.sql` file** (a resource's install SQL): select the database, then **File > Run SQL file...** and pick the file.
4. **Browse data**: click a table, then the **Data** tab. Handy for checking a player's money or job while testing.
5. **Back up**: right click the database > **Export database as SQL**, tick "Create" for tables and "Insert" for data.

## Let txAdmin create it

When you deploy a framework recipe in txAdmin, the deployer asks for host, port, user and password and **creates the database for you** if you leave the name empty (it generates a random name like `QBCore_A1B2C3`). It also imports the framework's SQL and writes the connection string into `server.cfg` through the `{{dbConnectionString}}` placeholder. That's the easiest path.

## Connect with oxmysql

oxmysql reads one convar. Put it in `server.cfg` (or better, in a `secrets.cfg` you `exec`) **before** `ensure oxmysql`:

```cfg title="server.cfg"
set mysql_connection_string "mysql://fivem:password@localhost:3306/qbox_4f2a?charset=utf8mb4"

ensure oxmysql
```

Both formats from the oxmysql docs work:

```cfg
# URI
set mysql_connection_string "mysql://root:12345@localhost:3306/fivem"
# key=value
set mysql_connection_string "user=root;password=12345;host=localhost;port=3306;database=fivem"
```

> [!WARNING]
> Don't use these characters in the database password: `; , / ? : @ & = + $ #`. They break the connection string parsing. Use a long password made of letters and numbers instead.

Useful oxmysql convars:

```cfg
set mysql_slow_query_warning 150      # warn about queries slower than 150 ms
set mysql_debug false                 # true, or a list like ["ox_inventory"] to log queries
```

## Using the database in your own resource

Add oxmysql's library to your manifest:

```lua title="fxmanifest.lua"
server_scripts {
    '@oxmysql/lib/MySQL.lua',
    'server/main.lua',
}
dependency 'oxmysql'
```

Then query from server scripts. Always use placeholders (`?`) for values, never string concatenation:

```lua title="server/main.lua"
-- one row
local row = MySQL.single.await('SELECT money FROM my_accounts WHERE identifier = ?', { identifier })

-- one value
local count = MySQL.scalar.await('SELECT COUNT(*) FROM my_accounts')

-- many rows
local rows = MySQL.query.await('SELECT * FROM my_accounts WHERE money > ?', { 1000 })

-- insert, returns the new id
local id = MySQL.insert.await('INSERT INTO my_accounts (identifier, money) VALUES (?, ?)', { identifier, 500 })

-- update, returns affected rows
local changed = MySQL.update.await('UPDATE my_accounts SET money = money + ? WHERE identifier = ?', { 250, identifier })
```

> [!CAUTION]
> Never build SQL from strings a client sent you: `'... WHERE name = "' .. name .. '"'` is an SQL injection waiting to happen. Placeholders escape values for you.

Database code only runs on the **server**. Clients must never talk to the database directly. They ask the server with an event or callback, and the server checks and queries. See [Client, server and events](/docs/development/client-server-events).

## Backups

Set these up before you have players, not after the first disaster.

**Windows**: a scheduled task that runs `mariadb-dump` (or `mysqldump`, both ship with MariaDB) every night:

```bat title="backup-db.bat"
@echo off
set STAMP=%DATE:~-4%-%DATE:~3,2%-%DATE:~0,2%
"C:\Program Files\MariaDB 11.4\bin\mariadb-dump.exe" -u root -pYOURPASSWORD --single-transaction qbox_4f2a > C:\Backups\db-%STAMP%.sql
```

Adjust the MariaDB folder and date format to your system.

**Linux**: a cron job for the `fivem` user:

```bash
crontab -e
# every night at 04:30, keep 14 days
30 4 * * * mariadb-dump --single-transaction qbox_4f2a | gzip > /home/fivem/backups/db-$(date +\%F).sql.gz && find /home/fivem/backups -name 'db-*.sql.gz' -mtime +14 -delete
```

Put credentials in `~/.my.cnf` (mode 600) so they don't appear in the crontab:

```ini title="~/.my.cnf"
[client]
user=fivem
password=a-long-random-password
```

Copy backups **off the machine** too (another server, object storage). A backup on the same disk doesn't help when the disk dies.

## Common database errors

| Error / symptom | Fix |
| --- | --- |
| `ECONNREFUSED 127.0.0.1:3306` | MariaDB isn't running, or it's on another port. Start the service. |
| `ER_ACCESS_DENIED_ERROR` | Wrong user or password in `mysql_connection_string`, or the user has no rights on that database. |
| `ER_BAD_DB_ERROR: Unknown database` | The database name in the string doesn't exist. Create it or fix the name. |
| `ER_NO_SUCH_TABLE` | You didn't import the resource's `.sql` file. |
| Emojis or special names turn into `????` | Use `utf8mb4` for the database and add `?charset=utf8mb4` to the URI. |
| Framework loads, but nothing saves | oxmysql started after the framework. Put `ensure oxmysql` first. |

Next: [Common errors and fixes](/docs/server-setup/common-errors).

_Last updated: 2026-09-22_

---

## Common server errors and fixes

URL: https://fivemad.com/docs/server-setup/common-errors

Fixes for the errors every FiveM server owner hits: license key, resources that won't load, server not in list, game build and pure mode, oversized assets, escrow and SQL.

Start every diagnosis in the same place: the **server console** (txAdmin > Live Console) for server errors, and the **F8 console** in the game for client errors. Scroll up to the **first** red line. Later errors are often just a result of the first one.

The messages below are paraphrased where their exact wording changes between builds. Search the console for the key words.

## License key problems

**Symptoms:** the server stops right after starting and mentions the license key, "invalid", "failed to verify" or a missing `sv_licenseKey`.

- Check the key is on its own line: `sv_licenseKey "cfxk_..."` with no extra spaces or quotes inside.
- Make sure it is not commented out and that no later `exec`'d file overrides it with an old key.
- Each server needs its **own** key. Two servers with one key fight each other.
- If you pasted the key into a public place, it may have been abused. **Regenerate** it on [portal.cfx.re](https://portal.cfx.re) and update your config.
- On a VPS, a system clock that is far off can break verification. The txAdmin team has a short video on syncing the Windows VPS clock, linked in the [video archive](/docs/videos).

## "Couldn't find resource" / "Couldn't start resource"

**Symptoms:** `Couldn't find resource myresource.` or a failed start for a resource you just added.

1. **Folder name.** `ensure` uses the folder name. `ensure my-car` does not find `My-Car` on Linux (case sensitive) and does not find `my-car-main` (GitHub zip downloads add `-main` or `-master`, rename the folder).
2. **Nested folder.** Unzipping often gives `resources/[local]/mycar/mycar/fxmanifest.lua`. The manifest must be directly inside the folder you ensure.
3. **No manifest.** The folder needs `fxmanifest.lua` (or the ancient `__resource.lua`). Generate a correct one with the [fxmanifest Generator](/tools/fxmanifest-generator).
4. **Wrong working directory.** Starting FXServer from the wrong folder (vanilla setups) means it can't see `resources` at all. Start it from your server data folder.
5. **Not refreshed.** Added the folder while the server runs? Type `refresh`, then `ensure name`.

## Manifest and script errors

**Symptoms:** `Couldn't load resource x` followed by a Lua error in `fxmanifest.lua`, or `SCRIPT ERROR: @resource/file.lua:12: ...`.

- A syntax error in the manifest (missing quote or comma in a `{ }` list) stops the whole resource. The error names the line.
- `SCRIPT ERROR` lines show `@resource/path:line`. Open that file at that line. Common ones:
  - `attempt to index a nil value (global 'QBCore')`: the framework object was never fetched, or the framework started after this resource. Fix `ensure` order.
  - `attempt to call a nil value (field 'xyz')`: calling an export or function that doesn't exist (wrong resource name, wrong version).
  - `No such export xyz in resource abc`: the resource isn't started, has another name, or doesn't export that function in your version.
- `Could not find dependency x for resource y`: install and `ensure` the dependency first.

More on reading errors in [Debugging](/docs/development/debugging).

## Server not in the server list

1. Test direct connect: `connect IP:30120` in F8. If it fails, it's ports or firewall, see [Ports and networking](/docs/server-setup/ports-and-networking).
2. Remove or comment out `sv_master1 ""`.
3. Set `sets sv_projectName` and `sets sv_projectDesc`.
4. Wait up to 8 minutes after start.
5. Check the IP isn't blocked with the [Cfx Blacklist Checker](/tools/cfx-blacklist-checker).
6. Check what your server reports with the [Server Status Checker](/tools/server-status-checker).

## Players get stuck while connecting

| Where it hangs | Usual cause |
| --- | --- |
| "Handshaking with server" | UDP 30120 blocked, or the server is under heavy load at start. |
| "Downloading assets" for ages | Huge streamed packs. Shrink textures with the [YTD Optimizer](/tools/ytd-optimizer), remove unused packs, consider a file server. |
| Loading screen never ends | A loadscreen with `loadscreen_manual_shutdown 'yes'` that never calls `ShutdownLoadingScreenNui()`, or a framework spawn script erroring. Check F8. |
| Kicked with a timeout after joining | A client script erroring in a loop, or a resource sending huge events. Check F8 and the server console. |

## Game build mismatch

**Symptoms:** players are told they need to download game data or a different build, or DLC vehicles and clothes don't appear.

- `sv_enforceGameBuild` must be set at startup, in `server.cfg`, and requires a restart to change.
- A build number that your artifact doesn't know yet does nothing. Update the artifact first.
- DLC content (vehicles, clothes) from a newer build than the one you enforce won't spawn. Check the build in [server.cfg explained](/docs/server-setup/server-cfg#sv_enforcegamebuild).
- Some old MLOs and clothing packs break on newer builds because Rockstar changed the base files. Look for an updated version from the author.

## Pure mode kicks

**Symptoms:** players are refused because of modified game files.

`sv_pureLevel 1` allows audio mods and known graphics mods, `sv_pureLevel 2` blocks everything modified. If legitimate players with graphics mods can't join, lower it to 1 or remove it. On FiveM for GTA V Enhanced, pure mode is always on and can't be disabled.

## Oversized assets and texture loss

**Symptoms:** a console warning that an asset "uses XX MiB of physical memory" and that oversized assets can lead to streaming issues. In game: blurry or missing textures, the city not loading when you drive fast, invisible cars.

- Usually a `.ytd` with 4K textures in a car or clothing pack.
- Resize textures to 2048 or 1024, use DXT compression, generate mipmaps. The [YTD Optimizer](/tools/ytd-optimizer) does this for many files at once.
- Check a whole vehicle resource for broken references with the [Vehicle Pack Validator](/tools/vehicle-pack-validator).
- Remove packs nobody uses. Every streamed MB costs every player memory.

## Escrow errors

**Symptoms:** "Failed to verify protected resource" or an escrowed resource refusing to start.

- The resource was bought on a **different Cfx.re account** than the one that owns the server's license key. Escrowed assets are tied to the buying account.
- Re-download it from the Cfx.re Portal. Files changed or re-zipped by hand (for example opened and saved in an editor) fail verification. Only edit the files the creator left open (usually `config.lua`).
- Too old an artifact: escrow needs a reasonably recent build.
- Some escrowed resources need a minimum game build or OneSync.

## Database errors

See the table at the end of [Database setup](/docs/server-setup/database#common-database-errors). The top three: MariaDB not running, wrong password in `mysql_connection_string`, forgot to import the resource's `.sql`.

## Port already in use

**Symptoms:** FXServer can't bind to `0.0.0.0:30120`, or txAdmin can't use 40120.

Another FXServer (or an old one that didn't close) is running. Close it (Task Manager on Windows, `pkill -f FXServer` or `systemctl stop` on Linux) or use different ports for the second server.

## txAdmin says the server is not responding

- A resource is blocking the main thread (an infinite loop without `Wait`, a slow synchronous query). txAdmin's **hang detection** restarts it. Find the culprit with the profiler: see [Threads and performance](/docs/development/threads-performance) and the [Profiler Analyzer](/tools/profiler-analyzer).
- Server hitches in the console (`server thread hitch warning: timer interval of X milliseconds`) mean the same thing on a smaller scale.

## Still stuck?

Post on [forum.cfx.re](https://forum.cfx.re) (Server Discussion) or the relevant framework Discord with:

- the first red error, copied as text,
- your artifact build and game build,
- what you changed last,
- your `server.cfg` without the license key and passwords.

_Last updated: 2026-09-22_

---

## Security basics for FiveM servers

URL: https://fivemad.com/docs/server-setup/security

Lock down a FiveM server: ACE permissions, txAdmin accounts and 2FA, a private database, secrets out of git, safe events, leaked resources, entity lockdown and backups.

Most FiveM servers that get "hacked" are not hacked at all. Someone found an unprotected event that gives money, a leaked resource with a backdoor, an exposed database, or an admin password reused from a leaked site. This page covers the basics that stop most of it.

## 1. Accounts and the txAdmin panel

- **Log in with Cfx.re** and turn on two factor authentication on your Cfx.re account (forum account settings). Every admin should do the same.
- **Give each admin their own txAdmin account** (Admin Manager). Never share the master account.
- **Least privilege.** txAdmin has fine grained permissions: `console.write`, `control.server`, `players.ban`, `server.cfg.editor`, `manage.admins` and more. A moderator needs `players.warn`, `players.kick`, `players.ban` and maybe `players.spectate`, not the console. See [Everyday admin](/docs/txadmin/everyday-admin#admins-and-permissions).
- **Remove admins who leave**, the same day.
- **Keep port 40120 private** if you can: allow it only from your IP in the firewall. If it must be public, strong passwords and 2FA are not optional. For HTTPS, put a reverse proxy (nginx, Caddy) or a Cloudflare Tunnel in front, as the txAdmin team recommends.
- The txAdmin **backup password** is a real password. Make it long and unique.

## 2. ACE permissions in server.cfg

FiveM's built in permission system is ACE. Keep it tight:

```cfg title="server.cfg"
# a group that can use every command except quit
add_ace group.admin command allow
add_ace group.admin command.quit deny

# a smaller group for moderators
add_ace group.mod command.kick allow
add_ace group.mod myresource.moderate allow   # a custom permission your scripts check

# people
add_principal identifier.fivem:123456 group.admin
add_principal identifier.discord:111111111111111111 group.mod
```

- Prefer `identifier.fivem:` (the Cfx.re account ID, visible in txAdmin) or `identifier.license:` over `identifier.ip:`, which changes and can be shared.
- `add_ace resource.myresource command.stop allow` lets a resource run a command. Only give resources what they need. Some resources ask for `add_ace resource.x command allow` (everything): think twice.
- In your own code, protect commands with `RegisterCommand(name, fn, true)` (restricted: requires the `command.name` ACE) or check `IsPlayerAceAllowed(source, 'myresource.admin')`.

## 3. Never trust the client

This is the most important rule for anyone who writes or installs scripts. Anything a client sends can be faked by a cheater with an executor. They can trigger **any** server event you registered, with any arguments.

Bad:

```lua title="server.lua (DON'T)"
RegisterNetEvent('shop:giveMoney', function(amount)
    local player = GetPlayer(source)
    player.addMoney(amount) -- a cheater sends 999999999
end)
```

Better:

```lua title="server.lua"
local PRICE = { bread = 5, water = 3 }

RegisterNetEvent('shop:buy', function(item)
    local src = source
    local price = PRICE[item]
    if not price then return end                       -- unknown item, ignore
    local player = GetPlayer(src)
    if not player or not isNearShop(src) then return end -- check position server side
    if player.getMoney() < price then return end
    player.removeMoney(price)
    player.addItem(item, 1)
end)
```

- Decide prices, rewards and amounts on the **server**.
- Validate every argument: type, range, whether the player can do this right now (distance, job, cooldown).
- Use `source` (copied into a local at the top of the handler), never a player ID sent as an argument, to know who is asking.
- Rate limit events that could be spammed.

More in [Client, server and events](/docs/development/client-server-events#security-never-trust-the-client).

## 4. The database

- MariaDB listens on `127.0.0.1` only. **Never** open port 3306 to the internet.
- Use a dedicated database user with a strong password, not `root` with an empty one.
- Manage it remotely through an SSH tunnel.
- Use parameterised queries (`?` placeholders) everywhere. See [Database setup](/docs/server-setup/database#using-the-database-in-your-own-resource).
- Back it up every night, and keep copies off the server.

## 5. Secrets out of git and screenshots

Keep your license key, database password, Discord bot tokens, Tebex secret and webhook URLs in a separate `secrets.cfg` that you `exec` from `server.cfg`, and add it to `.gitignore`:

```gitignore title=".gitignore"
secrets.cfg
txData/
cache/
*.log
```

If a key leaks: regenerate the license key on the Portal, change the database password, reset the bot token. Webhook URLs are secrets too: anyone with the URL can post to your channel.

## 6. What you install

- **No leaked resources.** Besides breaking the platform license, leaked paid scripts are a favourite place to hide backdoors: obfuscated code that downloads and runs remote Lua, gives admin to a stranger, or empties your Tebex.
- **Read what you install**, at least quickly. Red flags in Lua: `load(` or `assert(load(` with downloaded or encoded strings, `PerformHttpRequest` to unknown domains combined with `load`, long lines of escaped bytes (`\x..`), or files that are unreadable on purpose in a supposedly open resource.
- Prefer well known open source resources from GitHub (see [Recommended resources](/docs/resources/recommended)) and paid ones from reputable creators who use Cfx.re escrow.
- Keep them updated: security fixes land in `ox_inventory`, frameworks and txAdmin regularly.

## 7. Server settings that help

```cfg title="server.cfg"
sv_scriptHookAllowed 0         # block singleplayer mod menus
sv_endpointPrivacy true        # hide player IPs in public output
sv_entityLockdown strict       # only the server may create networked entities
# rcon_password is left unset, so RCON is disabled
```

- **Entity lockdown** stops a big class of cheats (spawning objects and peds). It also breaks scripts that create networked entities on the client, so test it on a dev copy. `relaxed` is a middle ground.
- **`sv_filterRequestControl`** can block clients from taking control of entities they don't own, another common cheat vector. Read its modes in the [server commands reference](https://docs.fivem.net/docs/server-manual/server-commands/) before using it.
- **State bags**: set `sv_stateBagStrictMode true` if your resources only set state from the server, so clients can't write to state bags.

## 8. Anticheat, realistically

No anticheat is perfect, and a paid one does not fix unsafe events. In order of value:

1. Safe server side code (section 3).
2. Entity lockdown and the settings above.
3. Good logging: txAdmin's action log and server log, plus logs of money and item changes in your framework.
4. Active moderators with txAdmin.
5. Then, if you still need it, a reputable anticheat.

[FiveM Scripting: How to Stop Cheaters (Twisle)](https://www.youtube.com/watch?v=FRVuFB0peU0) (YouTube video)

## 9. The machine itself

- Keep the OS updated. On Linux, enable unattended security upgrades.
- SSH with keys, not passwords. Disable root login over SSH.
- Run FXServer as its own user, not root or Administrator.
- Firewall: only 30120 TCP/UDP public, 40120 restricted, SSH restricted if possible.
- Backups of `txData`, the server folder and the database, stored elsewhere.

## Quick checklist

- [ ] Every admin has their own txAdmin account with only the permissions they need.
- [ ] 2FA on every Cfx.re account with admin access.
- [ ] 40120 restricted, 3306 closed.
- [ ] Secrets in `secrets.cfg`, not in git.
- [ ] No leaked or unreadable resources.
- [ ] Server events validate everything and use `source`.
- [ ] `sv_scriptHookAllowed 0`, `sv_endpointPrivacy true`, entity lockdown tested.
- [ ] Nightly backups copied off the machine.

_Last updated: 2026-09-22_

---


# txAdmin

## txAdmin overview

URL: https://fivemad.com/docs/txadmin

What txAdmin is and does: the recipe deployer, web panel, in-game menu, bans and warns, whitelist, scheduled restarts, Discord bot, live console and monitoring.

txAdmin is the web panel and in-game admin menu for FiveM and RedM servers. It was created by tabarra in 2019, has been part of FXServer since early 2020, and is now maintained under the Cfx.re GitHub organisation ([citizenfx/txAdmin](https://github.com/citizenfx/txAdmin), MIT licensed). The project says it runs on over 29,000 servers at any given time.

You don't install it. **Run FXServer without `+exec server.cfg` and txAdmin starts**, creates a `txData` folder, and serves its panel on port `40120`.

## What it does

### Deploy servers

The **recipe deployer** builds a complete server from a YAML recipe: downloads resources from GitHub, creates and imports the database, writes `server.cfg`. The setup page lists "Popular Recipes" (a basic FiveM server, ESX Legacy, Qbox, QBCore and a few game modes) and accepts any recipe URL. See [Recipes explained](/docs/txadmin/recipes) and [Popular recipes](/docs/txadmin/popular-recipes).

### Run and watch the server

- Start, stop and restart FXServer, and start or stop single resources.
- **Auto restart** on crash or hang.
- **Scheduled restarts** at fixed times, with in-game warnings 30, 15, 10, 5, 4, 3, 2 and 1 minutes before.
- **Live Console** with a log file, command history and search.
- **Performance chart** of server thread times against player count, plus CPU and memory use.
- **Server activity log**: joins, leaves, kills, chat, explosions and custom commands.
- A **CFG editor** for `server.cfg`.

### Manage players

- Real time player list, player search and player info (play time, identifiers, notes).
- **Warns** (players must acknowledge them in game), **kicks** and **bans**, temporary or permanent, including hardware ID bans.
- **Whitelist** modes: approved license, Discord server member, Discord role, or admin only.
- A self contained player database, no MySQL needed.

### In-game menu

Type `/tx` (or `/txadmin`) in game to open it. It has NoClip, god mode, super jump, teleport (waypoint, coords, back), vehicle spawn, fix, delete and boost, heal, announcements, world area reset, player IDs, and player actions: go to, bring, spectate, freeze, warn, ban, DM and a few troll options. Access requires a txAdmin account linked to your Cfx.re or Discord identifier.

### Discord bot

An optional bot posts a **persistent status embed** that updates every minute, and has commands to whitelist players and show player info. See [Discord bot](/docs/txadmin/discord-bot).

### Access control

Login with Cfx.re or password, per admin **permissions**, and an **action log** of what every admin did.

## Pages in this section

1. [First setup and the deployer](/docs/txadmin/first-setup): from first start to a running server.
2. [Recipes explained](/docs/txadmin/recipes): the YAML format, every task action, variables.
3. [Writing your own recipe](/docs/txadmin/writing-recipes): a complete example that installs a small framework stack.
4. [Popular recipes](/docs/txadmin/popular-recipes): what the Basic Server, QBCore, Qbox and ESX Legacy recipes install.
5. [Everyday admin](/docs/txadmin/everyday-admin): players, bans, warns, whitelist, restarts, backups, console, logs, admins.
6. [Discord bot](/docs/txadmin/discord-bot): setup, status embed, whitelist.
7. [Updating txAdmin and FXServer](/docs/txadmin/updating).

## Settings that live outside the panel

Since txAdmin v8, host level settings are **environment variables** named `TXHOST_*`, set before FXServer starts (in your `.bat`, `run.sh`, systemd unit or Docker env file). The ones you are most likely to need:

| Variable | Default | Use |
| --- | --- | --- |
| `TXHOST_DATA_PATH` | Windows: folder next to the artifact folder. Linux: next to `run.sh`. | Where `txData` lives. Use one per server. |
| `TXHOST_TXA_PORT` | `40120` | txAdmin web port. Cannot be 30120. |
| `TXHOST_FXS_PORT` | not set | Forces the game port by rewriting `endpoint_add_*`. Cannot be 40120. |
| `TXHOST_INTERFACE` | `0.0.0.0` | Interface txAdmin (and FXServer) bind to. |
| `TXHOST_MAX_SLOTS` | not set | Caps `sv_maxclients`. |
| `TXHOST_DEFAULT_CFXKEY` / `TXHOST_DEFAULT_DB*` | not set | Prefills the deployer, handy when you redeploy dev servers often. |

The old convars `txAdminPort`, `txAdminInterface` and `txDataPath` are deprecated. Full list in the [env-config docs](https://github.com/citizenfx/txAdmin/blob/master/docs/env-config.md).

## For script developers

txAdmin broadcasts server events you can listen to, named `txAdmin:events:<name>`, for example:

- `txAdmin:events:scheduledRestart` (with `secondsRemaining`), useful to save players before a restart,
- `txAdmin:events:serverShuttingDown`,
- `txAdmin:events:playerBanned`, `playerKicked`, `playerWarned`, `playerDirectMessage`,
- `txAdmin:events:playerHealed`, which frameworks use to revive a downed player when an admin heals them,
- `txAdmin:events:announcement`.

```lua title="server/main.lua"
AddEventHandler('txAdmin:events:scheduledRestart', function(data)
    if data.secondsRemaining == 60 then
        print('Restart in one minute, saving everything')
        -- save your resource's data here
    end
end)
```

The full list is in [events.md](https://github.com/citizenfx/txAdmin/blob/master/docs/events.md).

_Last updated: 2026-09-22_

---

## txAdmin first setup and the deployer

URL: https://fivemad.com/docs/txadmin/first-setup

Walk through txAdmin's first start: the PIN, linking your Cfx.re account, choosing a recipe or existing server, the deployer steps, license key, database and first launch.

This page goes through txAdmin's first run screen by screen. It is the same on Windows and Linux. If you haven't downloaded an artifact yet, start with [Windows setup](/docs/server-setup/windows) or [Linux setup](/docs/server-setup/linux).

[How to Create a FiveM Server with txAdmin (Alfa)](https://www.youtube.com/watch?v=FCIM7FlTA1g) (YouTube video)

## Before you click anything

Have these ready:

- Your **license key** from [portal.cfx.re](https://portal.cfx.re) (starts with `cfxk_`).
- For a framework recipe: MariaDB running, and its **host, port, user and password**. See [Database setup](/docs/server-setup/database).
- Optional: your **Discord user ID** if you want txAdmin to know it right away.

## Step 1: start FXServer and open the panel

Run `FXServer.exe` (Windows) or `bash run.sh` (Linux) with no arguments. The console prints the panel address and a **PIN**:

```text
[txAdmin] Use the PIN below to register:
[txAdmin]  5820
[txAdmin] http://localhost:40120/
```

Open the address. On a VPS use the server's public IP. The PIN proves you have access to the console, so nobody else who finds the page first can claim your server.

## Step 2: link your account

1. The PIN field should be filled already. Click **Link Account**.
2. Log in with your **Cfx.re** account (the forum account) and approve txAdmin.
3. Set a **backup password**. You'll use it only if Cfx.re login is down.

You are now the **master account**. It can't be removed by other admins and has every permission.

## Step 3: name the server

Type the name you want txAdmin to use (in the panel, Discord embed and logs). You can change it later in **Settings > General**. This is not `sv_hostname`, which lives in `server.cfg`.

## Step 4: choose how to set up

You get these options:

| Option | Pick it when |
| --- | --- |
| **Popular Recipes** (some versions say "Popular Template") | You want a fresh server from one of the listed recipes. Most people. |
| **Existing Server Data** | You already have a folder with `server.cfg` and `resources` (moving a server, or a vanilla setup). |
| **Remote URL Template** | You have the URL of a recipe YAML that isn't in the list. |
| **Custom Template** | You want to paste or edit a recipe yourself. |

### Existing server data

Point txAdmin to the folder that contains `server.cfg` and `resources`, then to the cfg file. txAdmin checks both and starts it. Nothing is downloaded.

## Step 5: pick a recipe

The Popular Recipes list comes from the [txAdmin-recipes index](https://github.com/citizenfx/txAdmin-recipes). At the time of writing it includes:

- **FiveM Basic Server** (Legacy and an Enhanced variant): the default Cfx resources, no framework.
- **ESX Legacy**, **Qbox**, **QBCore**: roleplay frameworks. Need MariaDB.
- **vMenu** (via a recipe patch), **StreetKings** (racing), **WarfareTacticsV** (RTS) and RedM's **VORP Core**.

See [Popular recipes](/docs/txadmin/popular-recipes) for what each one installs.

## Step 6: choose the data location

txAdmin suggests a folder inside `txData` named after the recipe with a random suffix, like `txData/QBCore_4F2A1C.base`. You can change it. The folder must be empty or not exist yet. Click **Save**.

> [!NOTE]
> The ESX docs point out that txAdmin will not create missing parent directories for you. If you pick a path outside `txData`, create the parent folder first.

## Step 7: the Recipe Deployer

This screen shows the recipe YAML. Read it once: it tells you exactly what will be downloaded. Click **Next**.

Now fill in the inputs:

- **License key**: paste your `cfxk_` key.
- **Database** (framework recipes only): host `localhost`, port `3306`, user, password. Leave **database name** empty to let txAdmin create one with a random name. The **delete database if it exists** option exists for redeploys, careful with it.
- Some recipes ask for extra values, like a Steam Web API key (recipes with `$steamRequired`).

Click **Run Recipe**. The deployer runs each task in order and shows a log. A failure stops it and shows which task failed. Common failures:

| Failure | Fix |
| --- | --- |
| GitHub `403` / `429` on a `download_github` task | GitHub rate limited your IP. Wait a few minutes and retry. It happens more on shared hosting IPs. |
| `connect_database` fails | MariaDB not running, wrong password, or the user can't create databases. |
| `query_database` fails | Usually MySQL instead of MariaDB, or a very old MariaDB. Use a current MariaDB. |
| Timeout on a big download | Retry. Recipes can raise `timeoutSeconds` on slow tasks. |

## Step 8: review server.cfg and start

txAdmin shows the generated `server.cfg`. The recipe placeholders are already filled in: your key, `endpoint_add_*` lines, `sv_maxclients` (48 by default), and `add_principal` lines that make **your** identifiers admin. Change `sv_hostname`, `sets tags`, `sets locale` if you like, then click **Save & Run Server**.

The panel switches to the **Live Console**. First boot takes longer:

- The artifact caches files.
- Some recipes (QBCore in particular) build resources with **yarn** on first start. Let it finish.
- Framework resources run database migrations.

When the console settles and shows resources started without red errors, connect with <kbd>F8</kbd> > `connect localhost:30120` (or your IP).

## Step 9: first things to set

1. **Settings > FXServer**: turn on starting the server automatically when txAdmin boots.
2. **Settings > Restarter**: add scheduled restart times (for example `06:00` and `18:00`). See [Everyday admin](/docs/txadmin/everyday-admin#scheduled-restarts).
3. **Admin Manager**: add your staff with only the permissions they need.
4. **Settings > Discord Bot** if you want the status embed. See [Discord bot](/docs/txadmin/discord-bot).
5. In game, type `/tx` to check the menu works for you.

## Starting over

To redeploy from scratch: stop the server, delete (or move) the server data folder, and use txAdmin's **Master Actions** page (master account only), which has an option to reset the FXServer settings and bring you back to the setup page. Keep `txData/default` if you want to keep your bans and player database.

> [!TIP]
> If you redeploy dev servers often, set `TXHOST_DEFAULT_CFXKEY` and the `TXHOST_DEFAULT_DB*` variables so the deployer inputs are prefilled.

_Last updated: 2026-09-22_

---

## txAdmin recipes explained

URL: https://fivemad.com/docs/txadmin/recipes

The anatomy of a txAdmin recipe: metadata, $engine and $onesync, context variables, every task action (download_github, unzip, move_path, query_database...) with examples.

A **recipe** is a YAML file that tells txAdmin's deployer how to build a server: what to download, where to put it, which SQL to run and how to fill in `server.cfg`. Every server in the "Popular Recipes" list is just a recipe file on GitHub, and you can deploy any recipe by URL.

This page is the reference, based on txAdmin's [recipe.md](https://github.com/citizenfx/txAdmin/blob/master/docs/recipe.md). To see what the listed recipes install, read [Popular recipes](/docs/txadmin/popular-recipes). To write one yourself, see [Writing your own recipe](/docs/txadmin/writing-recipes).

## A real recipe

This is the official **FiveM Basic Server** recipe from [citizenfx/txAdmin-recipes](https://github.com/citizenfx/txAdmin-recipes/tree/main/default-fivem), exactly as published:

```yaml title="default-fivem/recipe.yaml"
$engine: 3
$onesync: on
name: FiveM Basic Server
description: Recipe for the base resources required to run a minimal FiveM server.

tasks: 
  # Download default resources
  - action: download_github
    src: https://github.com/citizenfx/cfx-server-data
    ref: master
    subpath: resources
    dest: ./resources

  # Remove the old chat resource
  - action: remove_path
    path: ./resources/[gameplay]/chat

  # Download default server.cfg for FiveM
  - action: download_file
    url: https://raw.githubusercontent.com/citizenfx/txAdmin-recipes/refs/heads/main/default-fivem/server.cfg
    path: ./server.cfg
```

Three tasks: copy the `resources` folder of `cfx-server-data`, delete its old chat resource (the artifact has a built in one, enabled with `set resources_useSystemChat true`), and download a `server.cfg` template. The template uses placeholders that the deployer fills in:

```cfg title="default-fivem/server.cfg (excerpt)"
sv_hostname "{{serverName}} built with {{recipeName}}!"
sets sv_projectName "[{{recipeName}}] {{serverName}}"
sets sv_projectDesc "{{recipeDescription}}"

sv_enforceGameBuild 3751 #mp2025_02 - A Safehouse in the Hills
sv_licenseKey "{{svLicense}}"
sv_maxclients {{maxClients}}
{{serverEndpoints}}

add_ace group.admin command allow
add_ace group.admin command.quit deny
{{addPrincipalsMaster}}
```

## How the deployer runs a recipe

1. It reads the metadata and checks engine version and requirements.
2. It asks the user for inputs (license key, database, extra variables).
3. It runs the **tasks** one by one, in order. **Any failure stops the whole process.**
4. Every path is **jailed** to the target folder: a recipe can't write outside it (so it can't touch your `admins.json`).
5. At the end it checks that the target folder has a `server.cfg` and a `resources` folder, and replaces `{{svLicense}}` in `server.cfg`.

## Metadata

| Key | Required | Meaning |
| --- | --- | --- |
| `name` | recommended | Short name, under 24 characters. |
| `version` | recommended | Your recipe's version. |
| `author` | recommended | Short author name, under 24 characters. |
| `description` | recommended | Under 256 characters. YAML multiline strings work. |
| `$engine` | optional | Recipe engine version the recipe targets. Current recipes use `3`. |
| `$minFxVersion` | optional | Minimum FXServer build required. |
| `$onesync` | optional | OneSync value to set after deploy: `off`, `legacy` or `on`. |
| `$steamRequired` | optional | `true` if the `steam_webApiKey` variable must be provided. |

## Context variables

The deployer keeps a shared **context** of variables. You use them as `{{varName}}` in `replace_string` tasks and in files processed with `all_vars`.

| Variable | Filled from |
| --- | --- |
| `deploymentID` | Short recipe name plus a hex timestamp, like `PlumeESX_BBC957`. |
| `serverName` | The name entered on the setup page. |
| `recipeName`, `recipeAuthor`, `recipeVersion`, `recipeDescription` | Recipe metadata. |
| `dbHost`, `dbPort`, `dbUsername`, `dbPassword`, `dbName`, `dbDelete`, `dbConnectionString` | The database inputs. |
| `svLicense` | The license key input. Replaced in `server.cfg` automatically at the end. |
| `serverEndpoints` | The `endpoint_add_tcp/udp` lines (default `0.0.0.0:30120`, or from `TXHOST_INTERFACE` / `TXHOST_FXS_PORT`). |
| `maxClients` | 48 by default, or `TXHOST_MAX_SLOTS`. |
| `addPrincipalsMaster` | `add_principal` lines for the master admin's identifiers (used in `server.cfg` templates). |

Define your own under `variables:`:

```yaml
variables:
  frameworkLocale: en
  dbName: null   # null means "let txAdmin create a database"
```

## Task actions

Every task is a list item with an `action` and its options. Every task accepts `timeoutSeconds` to raise its default timeout. Indentation matters in YAML: use spaces, not tabs.

### `download_github`

Downloads a GitHub repository, optionally at a ref and only a subpath.

| Option | Meaning |
| --- | --- |
| `src` | Repo URL or `owner/repo`. |
| `ref` | Optional branch, tag or commit. Without it, txAdmin asks the GitHub API for the default branch. |
| `subpath` | Optional folder inside the repo to copy. |
| `dest` | Destination folder. Created if missing. |

```yaml
- action: download_github
  src: https://github.com/citizenfx/cfx-server-data
  ref: 6eaa3525a6858a83546dc9c4ce621e59eae7085c
  subpath: resources
  dest: ./resources

- action: download_github
  src: esx-framework/es_extended
  dest: ./resources/[esx]/es_extended
```

> [!NOTE]
> Without `ref`, each download makes an extra GitHub API call. With more than ~30 downloads, users hit rate limits (401/403 errors). Set `ref` on every task in big recipes, ideally to a **commit hash** (tags can move).

### `download_file`

```yaml
- action: download_file
  url: https://github.com/overextended/ox_lib/releases/latest/download/ox_lib.zip
  path: ./tmp/ox_lib.zip
```

`path` must be a file name, not a folder.

### `unzip`

```yaml
- action: unzip
  src: ./tmp/ox_lib.zip
  dest: ./resources/[ox]
```

ZIP only, no `.tar` files.

### `move_path`, `copy_path`, `remove_path`, `ensure_dir`

```yaml
- action: move_path
  src: ./tmp/cfx-server-data-master/resources
  dest: ./resources
  overwrite: true        # replace dest if it exists

- action: copy_path
  src: ./tmp/configs/
  dest: ./resources/[local]/myconfig
  # copies the CONTENTS of a src folder; overwrite defaults to true
  # errorOnExist: true makes it fail instead of silently skipping when overwrite is false

- action: remove_path
  path: ./tmp            # does nothing if the path doesn't exist

- action: ensure_dir
  path: ./resources/[local]
```

None of these accept the root path `./` as source or target.

### `write_file`

```yaml
- action: write_file
  file: ./server.cfg
  append: true
  data: |
    ensure my_resource
    ensure another_one

- action: write_file
  file: ./resources/[local]/myres/config.json
  data: |
    { "enabled": true }
```

Without `append`, the file is overwritten and missing folders are created.

### `replace_string`

Search and replace in one file or a list of files.

| `mode` | Behaviour |
| --- | --- |
| `template` (default) | Replaces `search` with `replace`, and `replace` can contain `{{vars}}`. |
| `all_vars` | Replaces every `{{var}}` in the file(s). `search` and `replace` are ignored. |
| `literal` | Plain search and replace, no variables. |

```yaml
- action: replace_string
  file: ./server.cfg
  search: 'FXServer, but unconfigured'
  replace: '{{serverName}} built with {{recipeName}} by {{recipeAuthor}}!'

- action: replace_string
  mode: all_vars
  file:
    - ./server.cfg
    - ./resources/[local]/myres/config.json
```

### `connect_database` and `query_database`

`connect_database` has no options. It uses the database inputs, and **creates the database** if `dbName` is null. It must run before any `query_database`.

```yaml
- action: connect_database

- action: query_database
  file: ./tmp/qbcore/qbcore.sql

- action: query_database
  query: |
    CREATE TABLE IF NOT EXISTS `my_table` (
      `id` INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
      `name` VARCHAR(64) NOT NULL
    );
```

Use `file` **or** `query`, never both.

### `load_vars`

Loads extra context variables from a JSON file (for example one shipped in a repo you downloaded):

```yaml
- action: load_vars
  src: ./tmp/recipe-vars.json
```

### `waste_time`

The txAdmin-recipes guidelines ask big recipes to pause with a `waste_time` task of 10 seconds every 25 `download_github` actions (50 if you set `ref`), so GitHub doesn't rate limit users. It isn't in the main recipe reference, but the official QBCore and Qbox recipes use it like this:

```yaml
- action: waste_time # prevent github throttling
  seconds: 10
```

## How big recipes are organised

Open the [QBCore](https://github.com/qbcore-framework/txAdminRecipe), [Qbox](https://github.com/Qbox-project/txAdminRecipe) or [ESX](https://github.com/esx-framework/ESX-recipes) recipe and you'll see the same pattern:

1. **Database first** (`connect_database`, then `query_database` with the framework SQL). It's the step most likely to fail, so failing early saves time.
2. **Download the recipe repo** itself into `./tmp`, which holds `server.cfg`, extra `.cfg` files, a logo and the SQL.
3. **Move** those files into place (`move_path` from `./tmp/...` to `./server.cfg`).
4. **Default Cfx resources** from `cfx-server-data` into `./resources/[cfx-default]`.
5. **Libraries** as release zips (`download_file` + `unzip`): oxmysql, ox_lib, ox_target, ox_inventory...
6. **Framework resources** with `download_github` into category folders like `[qb]` or `[qbx]`.
7. `remove_path` on `./tmp`.
8. `replace_string` with `all_vars` on `server.cfg` so `{{dbConnectionString}}` and friends are filled in.

## Where recipes come from

- The "Popular Recipes" list comes from the index files (`indexv4.json`, `indexv5.json`...) in the [txAdmin-recipes](https://github.com/citizenfx/txAdmin-recipes) repository. [Popular recipes](/docs/txadmin/popular-recipes) walks through every recipe in it.
- Any public raw URL to a `.yaml` works with **Remote URL Template**.
- You can paste YAML directly with **Custom Template**.

> [!WARNING]
> A recipe runs downloads and SQL on your machine. Only deploy recipes from sources you trust, and read the YAML on the deployer screen before clicking Next.

_Last updated: 2026-09-22_

---

## Writing your own txAdmin recipe

URL: https://fivemad.com/docs/txadmin/writing-recipes

Build a txAdmin recipe step by step: an example that installs oxmysql, ox_lib, ox_target, pma-voice and a starter resource, creates a table and writes server.cfg.

A recipe is the best way to make your server reproducible. Your dev server, your test server and a fresh live server can all come from the same file, and new developers on your team get a working setup in two minutes. This page builds a complete example recipe and explains each decision. The task reference is in [Recipes explained](/docs/txadmin/recipes).

> [!IMPORTANT]
> The recipe below is an **example** written for these docs. The resource URLs are real (they are the same ones the official Qbox and ESX recipes use), but pin versions you have tested before you rely on it.

## What we'll build

A lean, framework free base for a custom game mode:

- the default Cfx resources (mapmanager, spawnmanager, basic-gamemode...),
- **oxmysql** (database), **ox_lib** (UI and utilities), **ox_target** (third eye interactions),
- **pma-voice** (proximity voice) and **bob74_ipl** (loads GTA's online interiors),
- one starter resource of our own, created by the recipe,
- a database with one table,
- a `server.cfg` with everything wired up.

## Plan the folder layout

```text
resources/
├─ [cfx-default]/    from citizenfx/cfx-server-data
├─ [ox]/             oxmysql, ox_lib, ox_target
├─ [standalone]/     pma-voice, bob74_ipl
└─ [local]/          my_starter (our own)
server.cfg
```

## The recipe

```yaml title="my-base.yaml"
$engine: 3
$onesync: on
name: My Base
version: 1.0.0
author: YourName
description: |
  A lean base with oxmysql, ox_lib, ox_target, pma-voice and a starter resource.
  No framework. Example recipe from the fivemad docs.

variables:
  dbName: null   # let txAdmin create the database with a random name

tasks:
  # 1. Database first: the most likely step to fail
  - action: connect_database

  - action: query_database
    query: |
      CREATE TABLE IF NOT EXISTS `player_stats` (
        `license` VARCHAR(60) NOT NULL PRIMARY KEY,
        `playtime` INT UNSIGNED NOT NULL DEFAULT 0,
        `last_seen` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
      ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

  # 2. Default Cfx resources, minus the old chat (the artifact has a built in one)
  - action: download_github
    src: https://github.com/citizenfx/cfx-server-data
    ref: master
    subpath: resources
    dest: ./resources/[cfx-default]

  - action: remove_path
    path: ./resources/[cfx-default]/[gameplay]/chat

  # 3. Overextended libraries from their release zips
  - action: download_file
    url: https://github.com/overextended/oxmysql/releases/latest/download/oxmysql.zip
    path: ./tmp/oxmysql.zip
  - action: unzip
    src: ./tmp/oxmysql.zip
    dest: ./resources/[ox]

  - action: download_file
    url: https://github.com/overextended/ox_lib/releases/latest/download/ox_lib.zip
    path: ./tmp/ox_lib.zip
  - action: unzip
    src: ./tmp/ox_lib.zip
    dest: ./resources/[ox]

  - action: download_file
    url: https://github.com/overextended/ox_target/releases/latest/download/ox_target.zip
    path: ./tmp/ox_target.zip
  - action: unzip
    src: ./tmp/ox_target.zip
    dest: ./resources/[ox]

  # 4. Standalone resources straight from GitHub
  - action: download_github
    src: https://github.com/AvarianKnight/pma-voice
    dest: ./resources/[standalone]/pma-voice

  - action: download_github
    src: https://github.com/Bob74/bob74_ipl
    dest: ./resources/[standalone]/bob74_ipl

  # 5. Our own starter resource, written by the recipe
  - action: write_file
    file: ./resources/[local]/my_starter/fxmanifest.lua
    data: |
      fx_version 'cerulean'
      game 'gta5'

      name 'my_starter'
      description 'Starter resource created by the My Base recipe'
      version '1.0.0'

      shared_script '@ox_lib/init.lua'
      server_scripts {
          '@oxmysql/lib/MySQL.lua',
          'server.lua',
      }
      client_script 'client.lua'

      dependencies { 'oxmysql', 'ox_lib' }

  - action: write_file
    file: ./resources/[local]/my_starter/server.lua
    data: |
      AddEventHandler('playerJoining', function()
          local src = source
          local license = GetPlayerIdentifierByType(src, 'license')
          if not license then return end
          MySQL.insert('INSERT INTO player_stats (license) VALUES (?) ON DUPLICATE KEY UPDATE last_seen = NOW()', { license })
      end)

  - action: write_file
    file: ./resources/[local]/my_starter/client.lua
    data: |
      RegisterCommand('hello', function()
          lib.notify({ title = 'My Base', description = 'Hello from my_starter!', type = 'success' })
      end, false)

  # 6. server.cfg with placeholders
  - action: write_file
    file: ./server.cfg
    data: |
      ## Generated by the My Base recipe
      {{serverEndpoints}}

      sv_hostname "{{serverName}} | My Base"
      sets sv_projectName "{{serverName}}"
      sets sv_projectDesc "{{recipeDescription}}"
      sets tags "custom, base"
      sets locale "en-US"

      sv_licenseKey "{{svLicense}}"
      sv_maxclients {{maxClients}}
      sv_enforceGameBuild 3751
      set steam_webApiKey "none"
      set resources_useSystemChat true
      sv_endpointPrivacy true

      set mysql_connection_string "{{dbConnectionString}}"

      setr voice_useNativeAudio true
      setr voice_useSendingRangeOnly true

      ensure mapmanager
      ensure chat
      ensure spawnmanager
      ensure basic-gamemode
      ensure hardcap

      ensure oxmysql
      ensure ox_lib
      ensure ox_target
      ensure pma-voice
      ensure bob74_ipl

      ensure [local]

      add_ace group.admin command allow
      add_ace group.admin command.quit deny
      {{addPrincipalsMaster}}

  # 7. Fill in every {{placeholder}} in server.cfg
  - action: replace_string
    mode: all_vars
    file: ./server.cfg

  # 8. Clean up
  - action: remove_path
    path: ./tmp
```

## Why it's built this way

- **Database first.** The official guidelines say to put database tasks at the start, because they fail most often (wrong password, no MariaDB). Better to fail in the first second than after two minutes of downloads.
- **`dbName: null`.** The guidelines require recipes to accept txAdmin's random database name instead of forcing one like `es_extended`. We never hard code a name: the connection string comes from `{{dbConnectionString}}`.
- **Release zips for Overextended.** Their GitHub repos hold source code with a web UI that must be built. The release zip contains the built resource. Always use the release for ox_lib, ox_inventory, ox_target.
- **Placeholders in server.cfg.** The guidelines require `{{maxClients}}`, `{{addPrincipalsMaster}}`, `{{serverEndpoints}}` and `{{svLicense}}`. `{{svLicense}}` is replaced automatically at the end, the others by our `replace_string` with `all_vars`.
- **The chat resource** is removed from `cfx-server-data` because `set resources_useSystemChat true` uses the artifact's built in chat, as the official default recipe does.
- **`$onesync: on`** tells txAdmin to set OneSync on. ox_lib, ox_target and pma-voice all assume it.

## Pin your versions

`releases/latest/download/...` and `download_github` without `ref` always fetch the newest version. That's convenient, but a breaking update will break your next deploy. For a recipe you share or use for production:

```yaml
- action: download_github
  src: https://github.com/AvarianKnight/pma-voice
  ref: 0123456789abcdef0123456789abcdef01234567   # a commit you tested
  dest: ./resources/[standalone]/pma-voice

- action: download_file
  url: https://github.com/overextended/ox_lib/releases/download/v3.30.0/ox_lib.zip   # a tagged release you tested
  path: ./tmp/ox_lib.zip
```

The version numbers above are placeholders: look up the current release on each project's Releases page. The guidelines prefer commit hashes over tags, because tags can be moved.

## Test it

1. Push the YAML to a public GitHub repo (or a gist) and copy the **raw** URL.
2. Start a throwaway txAdmin: a separate `TXHOST_DATA_PATH` and `TXHOST_TXA_PORT` so you don't touch your main one.
3. Choose **Remote URL Template**, paste the URL, deploy.
4. Check: the server starts with no red errors, `/hello` shows a notification in game, `player_stats` gets a row when you join.

Or paste the YAML into **Custom Template** to test without hosting it.

## Guidelines if you want your recipe listed

The [txAdmin-recipes README](https://github.com/citizenfx/txAdmin-recipes) lists the rules for recipes in the Popular list. The main ones:

- Start from the CFX Default recipe structure.
- It must "just work": no editing files before the first start.
- Only open source or sharable resources. No leaked content.
- OneSync compatible, `$onesync: on` if supported.
- Admins in the `admin` ACE group must be recognised as admins by your framework.
- NUI that opens on <kbd>Tab</kbd> must check `IsNuiFocused()` so it doesn't steal focus from the txAdmin menu.
- txAdmin menu actions (noclip, god mode, teleport) must not trigger your anticheat, and txAdmin's Heal should revive downed players (listen to `txAdmin:events:playerHealed`).
- Good onboarding: a loading screen that explains the framework, plenty of comments in `server.cfg`.
- Use the same game build as the CFX Default recipes.

_Last updated: 2026-09-22_

---

## Popular txAdmin recipes

URL: https://fivemad.com/docs/txadmin/popular-recipes

Every recipe in the official txAdmin-recipes index: what CFX Default, QBCore, Qbox, ESX Legacy, vMenu and the others install, what they need, and how to deploy them.

The "Popular Recipes" list on txAdmin's setup page is not built into txAdmin. It is downloaded from the official **[citizenfx/txAdmin-recipes](https://github.com/citizenfx/txAdmin-recipes)** repository, which holds the index of listed recipes and the files for the "Basic Server" recipes. The framework recipes themselves live in each framework's own repository.

This page goes through every recipe in that index. For each one: what it installs, what it needs, the recipe URL, the notable tasks it runs and what to do after deploying. Everything below was read from the recipe files on GitHub in September 2026. Recipes change as projects update, so always read the YAML on the deployer screen before you click Next.

## Comparison

| Recipe | Game | Database | Game build set in its `server.cfg` | OneSync | What you get |
| --- | --- | --- | --- | --- | --- |
| **FiveM Basic Server (CFX Default)** | FiveM Legacy | No | `3751` | on | Default Cfx resources, no framework |
| **FiveM Basic Server (Enhanced)** | FiveM Enhanced | No | none (Enhanced uses the latest build) | always on | Minimal Enhanced server |
| **ESX Legacy** | FiveM | Yes (MariaDB) | `3258` | on | ESX core, ESX addons, ox_lib, oxmysql, pma-voice, a phone |
| **Qbox** | FiveM | Yes (MariaDB 10.9+) | `3258` | on | qbx_core and about 50 qbx resources on the ox stack, npwd phone |
| **QBCore** | FiveM | Yes (MariaDB) | `3095` | on | qb-core and about 60 qb resources |
| **vMenu** | FiveM | No | its own `sv_enforceGameBuild` line | on | Default Cfx resources plus vMenu |
| **StreetKings** | FiveM | Yes | see its `server.cfg` | on | Street racing game mode |
| **WarfareTacticsV** | FiveM | Yes | see its `server.cfg` | on | Real-time strategy game mode |
| **RedM Basic Server (CFX Default)** | RedM | No | n/a | on | Default Cfx resources for RedM |
| **VORP Core** | RedM | Yes | n/a | see recipe | RedM roleplay framework |

All of these set `$onesync: on` in their YAML (except where noted), and all framework recipes connect to the database **before** downloading anything else, as the repository's guidelines recommend.

## Which list you see

The repository keeps several index files, one per txAdmin generation: `indexv1.json` to `indexv5.json`. Your txAdmin version decides which one it reads.

- **`indexv4.json`** lists: FiveM Basic Server (CFX Default), ESX Legacy, Qbox, QBCore, vMenu, StreetKings, WarfareTacticsV, RedM Basic Server (CFX Default) and VORP Core.
- **`indexv5.json`**, the newest, starts with **FiveM Basic Server (Enhanced)** and lists ESX Legacy, Qbox, QBCore, StreetKings and WarfareTacticsV.

The repository README also lists the Legacy basic server, vMenu (with a recipe patch), VORP, and two deprecated entries (ZAP-Hosting ESX Pack and PlumeESX Legacy) that you should not use for new servers.

## How to deploy any of them

1. Start FXServer without `+exec` so txAdmin runs, link your Cfx.re account (see [First setup](/docs/txadmin/first-setup)).
2. On the setup page choose **Popular Recipes** and click the recipe. For a recipe that isn't listed (or to pin a specific file), choose **Remote URL Template** and paste the raw YAML URL from the sections below.
3. Pick the data folder (txAdmin suggests `txData/<Recipe>_<id>.base`).
4. Read the YAML, click **Next**, paste your license key, and for framework recipes fill in the MariaDB host, port, user and password. Leave the database name empty so txAdmin creates one.
5. **Run Recipe**, review `server.cfg`, **Save & Run Server**.

The task types used below (`download_github`, `query_database` and so on) are explained in [Recipes explained](/docs/txadmin/recipes).

## FiveM Basic Server (CFX Default)

- **Recipe URL**: `https://raw.githubusercontent.com/citizenfx/txAdmin-recipes/refs/heads/main/default-fivem/recipe.yaml`
- **Source**: [txAdmin-recipes/default-fivem](https://github.com/citizenfx/txAdmin-recipes/tree/main/default-fivem)
- **Needs**: a license key. No database.

**What it does.** Three tasks: copy the `resources` folder of [cfx-server-data](https://github.com/citizenfx/cfx-server-data), delete the old `chat` resource from it (the artifact's built in chat is used instead, via `set resources_useSystemChat true`), and download a minimal `server.cfg`.

```yaml title="default-fivem/recipe.yaml (excerpt, citizenfx/txAdmin-recipes)"
  - action: download_github
    src: https://github.com/citizenfx/cfx-server-data
    ref: master
    subpath: resources
    dest: ./resources

  - action: remove_path
    path: ./resources/[gameplay]/chat
```

**The server.cfg** starts `mapmanager`, `chat`, `spawnmanager`, `basic-gamemode` and `hardcap`, sets `sv_enforceGameBuild 3751` (A Safehouse in the Hills), `steam_webApiKey "none"`, and gives `group.admin` every command except `quit`. The file itself says it is "NOT supposed to be enough for most servers".

**After installing.** Change `sets locale "root-AQ"` to your language (for example `en-US`), set a real `sv_hostname`, and start adding resources: [Installing resources](/docs/resources), [vMenu](/docs/resources/recommended#vmenu), or your own code from [Your first resource](/docs/development/first-resource).

**Good for**: learning, development servers, freeroam, anything that isn't roleplay.

## FiveM Basic Server (Enhanced)

- **Recipe URL**: `https://raw.githubusercontent.com/citizenfx/txAdmin-recipes/refs/heads/main/default-fivem-enhanced/recipe.yaml`
- **Source**: [txAdmin-recipes/default-fivem-enhanced](https://github.com/citizenfx/txAdmin-recipes/tree/main/default-fivem-enhanced)
- **Needs**: the **Cfx Server** (Enhanced) artifact and a license key.

**What it does.** Downloads `cfx-server-data` into `./tmp`, then moves only what it needs into `resources`: `basic-gamemode`, `mapmanager`, `spawnmanager` and two example maps (`fivem-map-hipster`, `fivem-map-skater`), and deletes `./tmp`. There is no `$onesync` line (OneSync is always on in Enhanced) and no game build line (Enhanced only supports the latest build). Its `server.cfg` starts `mapmanager`, `spawnmanager` and `basic-gamemode` and uses the tags `enhanced, default, deployer`.

**Good for**: trying FiveM for GTA V Enhanced. Read [Legacy and Enhanced](/docs/server-setup#fivem-legacy-and-fivem-for-gta-v-enhanced) first.

## ESX Legacy

- **Recipe URL**: `https://raw.githubusercontent.com/esx-framework/ESX-recipes/legacy/recipe.yaml`
- **Source**: [esx-framework/ESX-recipes](https://github.com/esx-framework/ESX-recipes) (branch `legacy`)
- **Needs**: MariaDB (the ESX docs say MariaDB only, not XAMPP), a license key.

**What it installs.**

- Default Cfx resources into `[cfx-default]` (minus the old chat).
- ESX core: the `[core]` folder of [esx-framework/esx_core](https://github.com/esx-framework/esx_core), including `es_extended`.
- ESX addons: the `[esx_addons]` folder of ESX-Legacy-Addons (jobs, shops, society and more).
- `[standalone]`: bob74_ipl, pma-voice, oxmysql, ox_lib, and sd-phone with sd-phone-props.

**Notable tasks.** It downloads the core repo, then imports its SQL from inside it. The addons download gets a long timeout because the repository is big:

```yaml title="recipe.yaml (excerpt, esx-framework/ESX-recipes)"
  - action: connect_database

  - action: download_github
    src: https://github.com/esx-framework/esx-core
    ref: main
    dest: ./tmp/core

  - action: query_database
    file: ./tmp/core/[SQL]/legacy.sql

  - action: download_github
    src: https://github.com/esx-framework/ESX-Legacy-Addons/
    ref: main
    dest: ./tmp/addons
    timeoutSeconds: 900
```

**The server.cfg** sets `sv_enforceGameBuild 3258`, the connection string from `{{dbConnectionString}}`, pma-voice settings (`voice_useNativeAudio true`, `voice_useSendingRangeOnly true`), and some security convars (`sv_filterRequestControl 2`, networked sounds, script entity states and phone explosions disabled). It lets `es_extended` run `add_ace`, `add_principal`, `remove_principal` and `stop`, which ESX uses to sync its admin groups. Start order: `chat`, `oxmysql`, `esx_lib`, `es_extended`, `[core]`, `[standalone]`, `[esx_addons]`.

**After installing.** Set `setr esx:locale` if you want a language other than the one picked in txAdmin (the line is commented out by default). See the [ESX quick start](/docs/frameworks/esx) for jobs, items and admin.

## Qbox

- **Recipe URL**: `https://raw.githubusercontent.com/Qbox-project/txAdminRecipe/refs/heads/main/qbox.yaml`
- **Source**: [Qbox-project/txAdminRecipe](https://github.com/Qbox-project/txAdminRecipe)
- **Needs**: MariaDB 10.9 or newer (Qbox's docs say MySQL and XAMPP are not supported), a license key.

**What it installs.**

- Config files: `server.cfg`, `permissions.cfg`, `ox.cfg`, `voice.cfg`, `misc.cfg` and a logo.
- `[ox]`: ox_lib, ox_target, oxmysql, ox_doorlock, ox_inventory (with Qbox's `items.lua` and the item images from qbx_invimages) and ox_fuel.
- `[standalone]`: bob74_ipl, safecracker, screencapture, mhacking, scully_emotemenu, ultra-voltlab, Renewed-Banking, illenium-appearance, MugShotBase64, Renewed-Weathersync, xt-prison, vehiclehandler, a loading screen and mana_audio.
- `[voice]`: pma-voice and mm_radio.
- `[qbx]`: qbx_core and around 50 `qbx_*` resources (garages, vehicle shop and sales, police, ambulance and medical, mechanic, properties, vehicle keys, spawn, HUD, radial menu, management, city hall, customs, density, jobs and robberies).
- `[npwd]` and `[npwd-apps]`: the npwd phone (pinned to release 3.16.0) with Qbox garage and mail apps.
- `[assets]`: a Pillbox hospital map.

**Notable tasks.** It imports a base `qbox.sql`, then each resource's own SQL right after downloading it, and pauses between batches of GitHub downloads so users don't get rate limited:

```yaml title="qbox.yaml (excerpt, Qbox-project/txAdminRecipe)"
  - action: query_database
    file: ./resources/[qbx]/qbx_drugs/qbx_drugs.sql

  - action: waste_time # prevent github throttling
    seconds: 10
```

It also moves the item images into `ox_inventory/web/images` with `overwrite: true` and copies the Qbox npwd config over npwd's default one.

**The server.cfg** uses `set sv_enforceGameBuild 3258` and has many `qbx:` convars, including `qbx:enableBridge "true"` (the qb-core compatibility bridge), `qbx:enableQueue`, `qbx:max_jobs_per_player`, `qbx:enableVehiclePersistence` and a chat MOTD. Start order: `ox_lib`, `qbx_core`, `ox_target`, `[ox]`, `[qbx]`, `[standalone]`, `[voice]`, `[assets]`, then npwd. Permissions come from `{{addPrincipalsMaster}}` and `exec permissions.cfg`.

**After installing.** Change the locale lines (`sets locale`, `setr qb_locale`, `setr illenium-appearance:locale`), set `qbx:discordLink`, and fill in `SCREENSHOT_BASIC_TOKEN` / `NPWD_AUDIO_TOKEN` only if you want npwd's camera and audio features. See the [Qbox quick start](/docs/frameworks/qbox).

## QBCore

- **Recipe URL**: `https://raw.githubusercontent.com/qbcore-framework/txAdminRecipe/main/qbcore.yaml`
- **Source**: [qbcore-framework/txAdminRecipe](https://github.com/qbcore-framework/txAdminRecipe) (version 2.2.4 at the time of writing)
- **Needs**: MariaDB (the QBCore install guide pairs it with HeidiSQL), a license key.

**What it installs.**

- Default Cfx resources into `[cfx-default]` (minus the old chat).
- `[standalone]`: oxmysql (pinned to v2.14.1), menuv (v1.4.1), bob74_ipl, safecracker, screencapture, progressbar, interact-sound, connectqueue, PolyZone.
- `[voice]`: pma-voice and qb-radio.
- `[defaultmaps]`: hospital, dealer and prison maps.
- `[qb]`: qb-core and around 60 `qb-*` resources: multicharacter, target, inventory, phone, garages, vehicle shop and sales, police, ambulance, mechanic, houses, apartments, banking, clothing, doorlock, fuel, HUD, menu, input, loading screen, admin menu, management, weather sync, many jobs and robberies.

**Notable tasks.** The database goes first with one SQL file from the recipe repository, and the recipe pauses 10 seconds between batches of downloads (`waste_time`, eight times in total) to avoid GitHub throttling.

```yaml title="qbcore.yaml (excerpt, qbcore-framework/txAdminRecipe)"
  - action: connect_database
  - action: query_database
    file: ./tmp/qbcore/qbcore.sql

  - action: download_file
    path: ./tmp/files/oxmysql.zip
    url: https://github.com/overextended/oxmysql/releases/download/v2.14.1/oxmysql.zip
```

**The server.cfg** sets `sv_enforceGameBuild 3095` (The Chop Shop), pma-voice settings (`voice_useNativeAudio true`, default cycle key `GRAVE`), `setr qb_locale "en"` and `setr UseTarget false`. It defines a permission chain: `qbcore.god` inherits `group.admin` and `qbcore.admin`, and `qbcore.admin` inherits `qbcore.mod`. It also lets `resource.qb-core` run commands.

**After installing.** Let the first start finish: QBCore's docs warn to let **yarn install** run all the way through on the initial startup. Then give yourself QBCore admin by adding your identifier to the god group, for example `add_principal identifier.fivem:123456 qbcore.god`. Switch `UseTarget` to `true` if you want qb-target interactions instead of key prompts. See the [QBCore quick start](/docs/frameworks/qbcore).

## vMenu

- **Recipe URL** (as listed in `indexv4.json`): `https://raw.githubusercontent.com/tabarra/vMenu-recipe/refs/heads/main/recipe.yaml`. The README links the recipe patch at [feelfreetofee/vMenu-recipe](https://github.com/feelfreetofee/vMenu-recipe).
- **Needs**: a license key. No database.

**What it does.** Copies `cfx-server-data`, removes the old chat and the `[builders]` folder, downloads its `server.cfg`, then downloads a pinned vMenu release (v3.8.61 in the patch at the time of writing) and unzips it into `resources/[local]/vMenu`.

**The server.cfg** runs `exec @vMenu/config/permissions.cfg` **before** `ensure vMenu`, which is exactly the order the vMenu docs require.

**After installing.** Edit `resources/[local]/vMenu/config/permissions.cfg` to decide who can use which menu options. Newer vMenu releases may exist: see [vMenu](/docs/resources/recommended#vmenu) for updating it by hand.

## StreetKings

- **Recipe URL**: `https://raw.githubusercontent.com/streetkings-fivem/txAdminRecipe/refs/heads/main/streetkings.yaml`
- **Needs**: MariaDB, a license key.

A freeroam street racing game mode by 919DESIGN and Envi-Scripts: solo or up to 20 player races, XP for character and vehicle across five classes, daily races and a short story campaign. The recipe imports `streetkings.sql`, downloads bob74_ipl, pma-voice, the `streetkings` resource with its audio and blips assets, and ox_lib and oxmysql. Note that at the time of writing it downloads ox_lib and oxmysql from the **CommunityOx** GitHub organisation, whose copies of those repositories are now archived; the maintained versions are under [overextended](https://github.com/overextended).

## WarfareTacticsV (Real-Time Strategy)

- **Recipe URL**: `https://raw.githubusercontent.com/FiveM-RTS-WarfareTactics/txAdminRecipe/refs/heads/main/recipe.yaml`
- **Needs**: MariaDB, a license key.

A standalone RTS game mode by EnyoScripts (version 2.1.1 at the time of writing): platoon combat, 5 maps, 24 unit types, CPU opponents and matchmaking. The recipe pins `cfx-server-data` to a specific commit and only moves the pieces it needs (sessionmanager, baseevents, hardcap, the yarn and webpack builders, spawnmanager), then downloads its `[rts]` resources with 900 second timeouts because they are large.

## RedM Basic Server and VORP Core

For Red Dead Redemption 2 servers on RedM:

- **RedM Basic Server (CFX Default)**: `https://raw.githubusercontent.com/citizenfx/txAdmin-recipes/refs/heads/main/default-redm/recipe.yaml`, the same three tasks as the FiveM basic recipe with a RedM `server.cfg`.
- **VORP Core**: `https://raw.githubusercontent.com/VORPCORE/VORP_txAdmin/main/vorp_recipe.yaml`, the most used RedM roleplay framework. Needs MariaDB.

These docs focus on FiveM, but txAdmin works the same way for RedM.

## Common issues with recipe deploys

| Problem | Cause and fix |
| --- | --- |
| GitHub `401`, `403` or `429` during download | GitHub rate limits by IP, worse on shared hosting. Wait 10 to 15 minutes and retry. Big recipes pause with `waste_time` to reduce this. |
| `connect_database` fails | MariaDB not running, wrong password, or the user can't create databases. See [Database setup](/docs/server-setup/database). |
| `query_database` fails on a framework SQL | MySQL 8 or an old MariaDB (XAMPP). Qbox and ESX require MariaDB. |
| A task times out | Slow connection or a large repository. Retry. Recipe authors can raise `timeoutSeconds`. |
| Server starts but resources error on first boot | Resources that build with yarn (QBCore) need the first start to finish. Wait, then restart once. |
| Everything is in English | Change the locale convars in `server.cfg` (`sets locale`, `setr qb_locale`, `setr esx:locale`). |
| Target path error | txAdmin will not create missing parent folders outside `txData`. Create the parent first. |
| You deployed the wrong recipe | Stop the server, delete the data folder and the generated database, and deploy again. |

## Writing or listing your own

Anyone can deploy a recipe from a URL. To have one included in the Popular list, it must follow the [txAdmin-recipes guidelines](https://github.com/citizenfx/txAdmin-recipes#recipe-making-guidelines-and-best-practices): start from the CFX Default structure, "just work" without manual edits, use only open source or sharable resources, support OneSync, use the `{{maxClients}}`, `{{addPrincipalsMaster}}`, `{{serverEndpoints}}` and `{{svLicense}}` placeholders, and accept txAdmin's random database name. See [Writing your own recipe](/docs/txadmin/writing-recipes) for a full example.

_Last updated: 2026-09-22_

---

## Everyday admin with txAdmin

URL: https://fivemad.com/docs/txadmin/everyday-admin

Run a FiveM server day to day with txAdmin: players, warns, kicks and bans, whitelist modes, scheduled restarts, live console, logs, backups and admin permissions.

Once the server is running, txAdmin is where you spend your time: dealing with players, restarting, reading logs and managing staff. This page covers the features you'll use every day and the settings worth changing early.

[txAdmin Menu Beta: Introduction (Project Error)](https://www.youtube.com/watch?v=jWKg0VQK0sc) (YouTube video)

## The dashboard

The dashboard shows server status, player count, uptime, the next scheduled restart and the **performance chart**: server thread tick times plotted against the number of players. Spikes that line up with player joins or specific times often point to a resource doing heavy work. Pair it with the profiler (see [Threads and performance](/docs/development/threads-performance)).

From the dashboard you can **start, stop and restart** the server and send an **announcement** to everyone.

## Players

### Finding a player

The **Players** page searches everyone who has ever joined, by name, identifier or notes, not just who is online. Click a player to open their **player modal**: play time, first and last join, identifiers (license, Discord, Cfx.re, Steam), hardware IDs, their history of warns and bans, and **notes** your staff left.

In game, `/tx` opens the menu's player list, sortable by ID, name or distance. `/tx 12` jumps straight to player 12.

### Warn, kick, ban

| Action | What happens |
| --- | --- |
| **DM** | A private message on the player's screen. |
| **Warn** | A full screen warning the player must acknowledge (holding a key) before they can continue. Recorded in their history. Works for offline players too: they see it when they next join. |
| **Kick** | Disconnects them with your reason. |
| **Ban** | Temporary (hours, days, weeks) or permanent. txAdmin bans every identifier it knows for the player, plus hardware IDs, so a new Rockstar account alone doesn't get around it. |

Always write a clear reason. The player sees it, and your team sees it months later. By default txAdmin hides the admin's name in bans and warns (`txAdmin-hideAdminInPunishments`).

You can **revoke** a ban or warn from the player's history, and **ban by identifier** for someone who isn't online.

### Freeze, spectate, bring, go to

Menu only, from the player's page in `/tx`: freeze their ped, spectate them, bring them to you, go to them, heal them. Troll actions (drunk, fire, wild attack) exist too and are behind their own permission. Give that permission to nobody you wouldn't trust with a ban hammer.

## Whitelist

**Settings > Player Manager** has the whitelist mode:

| Mode | Who can join |
| --- | --- |
| Disabled | Everyone (except banned players). |
| Admin only | Only txAdmin admins. Handy during maintenance. |
| Approved license | Players whose Rockstar license an admin approved. New players appear as **whitelist requests** with a short ID they can give you. |
| Discord member | Players who are members of your Discord server (needs the [Discord bot](/docs/txadmin/discord-bot)). |
| Discord role | Players who have one of the roles you pick in your Discord server. |

With **Approved license**, a rejected player sees a request ID on the connect screen. Approve it on the **Whitelist** page or with the bot's whitelist command.

## Scheduled restarts

FiveM servers run better with regular restarts: memory from leaky scripts is freed and state is reset. In **Settings > Restarter**, add times in 24 hour format:

```text
06:00, 12:00, 18:00, 00:00
```

Players get warnings at 30, 15, 10, 5, 4, 3, 2 and 1 minutes. Resources can react to the `txAdmin:events:scheduledRestart` event (for example to save data), and frameworks usually save players on shutdown.

From the dashboard you can **skip** the next restart or schedule a one off **temporary** restart.

> [!TIP]
> Pick restart times when fewest people play, and announce them in Discord. Every 6 to 12 hours is common for RP servers with many scripts. Small, clean servers can go much longer.

## Crash and hang handling

txAdmin restarts FXServer automatically when it **crashes** or **hangs** (stops responding to txAdmin's checks). If it keeps restarting in a loop, open the Live Console, scroll to the last lines before the crash, and look at [Common errors](/docs/server-setup/common-errors).

## Live Console

The **Live Console** shows everything FXServer prints and lets you type server commands (`ensure myresource`, `restart ox_inventory`, `refresh`). It keeps a command history and has search. The same log is written to files in `txData`, so you can read yesterday's output.

Handy commands:

```text
refresh                 rescan the resources folder
ensure my_resource      start or restart a resource
stop my_resource
status                  list connected players
clientkick 12 reason    kick player 12
say Hello everyone      message from the console
```

## Logs

- **Server log** (**Server Log** page): joins, leaves, deaths, chat, explosions, menu actions, plus custom lines resources add. Filter by player to see what someone did.
- **Action log** (System logs): what every **admin** did in txAdmin: bans, warns, restarts, settings changes, console commands. This is how you keep staff honest.
- **Console log files** in `txData`.

## Resources page

Lists every resource with its state. Start, stop and restart single resources without touching the console. Useful for a quick `restart` after editing a config on a live server (if the resource supports restarting cleanly).

## CFG editor

**CFG Editor** edits `server.cfg` (and other cfg files it references) in the browser. Changes apply on the next restart. Restrict it with the `server.cfg.editor` permission: whoever can edit the cfg can effectively run any command.

## Admins and permissions

**Admin Manager** (needs `manage.admins` or the master account):

1. **Add admin**: a name, and their **Cfx.re** username and/or **Discord ID**. The identifiers let them use the in-game menu and log in with Cfx.re.
2. Give them a **backup password** or let them set one on first login.
3. Pick permissions. From txAdmin's permission list:

| Permission | Allows |
| --- | --- |
| `all_permissions` | Everything. Give it to almost nobody. |
| `manage.admins` | Add, edit and remove admins. |
| `settings.view` / `settings.write` | View / change settings. |
| `console.view` / `console.write` | See / type in the live console. `console.write` is effectively full control. |
| `control.server` | Start, stop, restart the server. |
| `commands.resources` | Start and stop resources. |
| `server.cfg.editor` | Read and write server.cfg. |
| `announcement` | Send announcements. |
| `txadmin.log.view` / `server.log.view` | View logs. |
| `players.direct_message`, `players.warn`, `players.kick`, `players.ban` | Player actions. |
| `players.whitelist` | Approve whitelist requests. |
| `players.freeze`, `players.heal`, `players.spectate`, `players.teleport`, `players.playermode`, `players.troll` | Menu actions. |
| `menu.vehicle`, `menu.clear_area`, `menu.viewids` | Menu vehicle spawn/fix, area reset, show player IDs. |
| `players.remove_ids` | Remove identifiers and hardware IDs from the database. |

A sensible **moderator**: `players.direct_message`, `players.warn`, `players.kick`, `players.ban`, `players.spectate`, `players.freeze`, `players.teleport`, `menu.viewids`, `server.log.view`. A **senior admin** adds `control.server`, `commands.resources`, `announcement`, `players.whitelist`.

Permissions are stored in `txData/admins.json`.

## Backups

txAdmin keeps its own data (players, bans, warns, whitelist, settings) in `txData`, not in MariaDB. It does **not** back up your server folder or your framework database. Back up:

- `txData` (whole folder),
- your server data folder (`server.cfg`, `resources`, ideally in git),
- your MariaDB database, nightly (see [Database setup](/docs/server-setup/database#backups)).

Copy them off the machine. txAdmin also has a **database cleanup** action (on the master admin's **Master Actions** page) that removes old players with little play time, old warns and expired bans, to keep its player database small on busy servers.

## Settings worth changing early

- **Game > Menu**: enable or disable the in-game menu, align it right, change the page key.
- **Game > Notifications**: hide the default announcement, DM, warning or restart UI if a resource of yours shows them instead (it listens to the txAdmin events).
- **Player Manager**: whitelist mode, ban templates, and the message players see when banned or not whitelisted (put your Discord link there).
- **Restarter**: schedule.
- **Discord Bot**: see the [Discord bot page](/docs/txadmin/discord-bot).

_Last updated: 2026-09-22_

---

## txAdmin Discord bot

URL: https://fivemad.com/docs/txadmin/discord-bot

Set up txAdmin's built in Discord bot: create the application, token and intents, invite it, add the live status embed with /status add, and use Discord whitelisting.

txAdmin has a Discord bot built in. You don't host anything extra: txAdmin itself logs in as your bot. It gives you:

- a **persistent status embed** that updates every minute (online state, players, next restart, uptime, connect buttons),
- **Discord based whitelisting** (member of your server, or has a role),
- slash commands for staff, like whitelisting a player and looking up player info,
- an optional **announcements channel** where txAdmin posts server events such as restarts.

[txAdmin Discord Bot setup: status and whitelist (Brave Development)](https://www.youtube.com/watch?v=pfEtkIcRdHg) (YouTube video)

## 1. Create the Discord application

1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) and click **New Application**. Name it after your server.
2. Open the **Bot** page.
3. Click **Reset Token** and copy the token. Treat it like a password: anyone with it controls your bot.
4. Under **Privileged Gateway Intents**, enable **Server Members Intent**. Without it the bot can't see who is in your Discord, and member or role whitelisting fails.
5. Optional: turn off **Public Bot** so nobody else can invite it.

## 2. Invite it to your Discord

1. Open **OAuth2 > URL Generator**.
2. Scopes: `bot` and `applications.commands`.
3. Bot permissions: at least **View Channels**, **Send Messages**, **Embed Links** and **Read Message History** (the status embed is a message the bot edits).
4. Open the generated URL and add the bot to your server.

## 3. Configure txAdmin

In txAdmin, **Settings > Discord Bot**:

| Field | Value |
| --- | --- |
| Enabled | On |
| Token | The bot token from step 1 |
| Guild / Server ID | Right click your server icon in Discord > **Copy Server ID** (enable Developer Mode in Discord's Advanced settings first) |
| Announcements channel | Optional. Right click a channel > **Copy Channel ID**. txAdmin posts server events (like restarts) there. |

Save. The txAdmin **System Logs** page shows whether the bot logged in or why it failed.

## 4. Add the status embed

In the channel where you want the status, type:

```text
/status add
```

The bot posts an embed and keeps editing it every minute. It needs permission to send messages in that channel. To move it, run `/status add` in the new channel and delete the old message.

### Customise the embed

**Settings > Discord Bot** has two JSON editors, the **embed JSON** and the **config JSON**. The embed supports these placeholders (from txAdmin's [discord-status docs](https://github.com/citizenfx/txAdmin/blob/master/docs/discord-status.md)):

| Placeholder | Value |
| --- | --- |
| `{{serverName}}` | txAdmin's name for the server |
| `{{serverClients}}` / `{{serverMaxClients}}` | Players online / slots |
| `{{serverJoinUrl}}` | `https://cfx.re/join/xxxxxx` |
| `{{serverBrowserUrl}}` | Server browser page |
| `{{serverCfxId}}` | Your server's Cfx.re ID |
| `{{statusString}}` / `{{statusColor}}` | Online, partial or offline text and colour from the config JSON |
| `{{uptime}}` | For example `1 hr, 50 mins` |
| `{{nextScheduledRestart}}` | For example `in 2 hrs, 48 mins` |

A minimal embed:

```json title="Embed JSON"
{
  "title": "{{serverName}}",
  "url": "{{serverBrowserUrl}}",
  "description": "Press Connect below, or F8 and `connect cfx.re/join/xxxxxx`.",
  "fields": [
    { "name": "> STATUS", "value": "```\n{{statusString}}\n```", "inline": true },
    { "name": "> PLAYERS", "value": "```\n{{serverClients}}/{{serverMaxClients}}\n```", "inline": true },
    { "name": "> NEXT RESTART", "value": "```\n{{nextScheduledRestart}}\n```", "inline": true },
    { "name": "> UPTIME", "value": "```\n{{uptime}}\n```", "inline": true }
  ]
}
```

And the config, which sets the status texts, colours and up to 5 link buttons:

```json title="Config JSON"
{
  "onlineString": "Online",
  "onlineColor": "#0BA70B",
  "partialString": "Partial",
  "partialColor": "#FFF100",
  "offlineString": "Offline",
  "offlineColor": "#A70B28",
  "buttons": [
    { "emoji": "1062338355909640233", "label": "Connect", "url": "{{serverJoinUrl}}" },
    { "emoji": "1062339910654246964", "label": "Rules", "url": "https://example.com/rules" }
  ]
}
```

`color` and `footer` are set by txAdmin, so leave them out. txAdmin can't validate the embed until Discord accepts it: if it doesn't appear, check **System Logs**. A visual editor like [discohook.org](https://discohook.org/) helps (paste the object inside its `embeds` array). The `emoji` fields take a unicode emoji or a custom emoji ID; replace the example IDs above with your own.

## 5. Discord whitelisting

In **Settings > Player Manager**, set the whitelist mode:

- **Discord member**: anyone in your Discord server can join. Good against random joiners and ban evaders who don't want to rejoin your Discord.
- **Discord role**: only members with one of the roles you pick. The classic "Whitelisted" role for RP servers. Your application team gives the role, the player can join.

Players must have **Discord running and linked** to FiveM so the server receives their `discord:` identifier. If they get "not whitelisted" while having the role, it's almost always that: Discord wasn't open when they launched FiveM.

For **Approved license** mode, staff can approve requests from Discord with the bot's whitelist command instead of opening the panel.

## Troubleshooting

| Problem | Fix |
| --- | --- |
| Bot offline | Wrong token (reset it and paste again), or the bot is disabled in settings. Check System Logs. |
| Whitelist says everyone is not a member | **Server Members Intent** not enabled, or wrong Guild ID. |
| `/status add` does nothing | Slash commands take a moment to register after the bot joins. Also check the bot has permission in that channel. |
| Embed never updates | Someone deleted the message. Run `/status add` again. |
| Custom emoji don't show | The bot must be in the server that owns the emoji, and the ID must be right. |

The official txAdmin channel also has a short video on removing an admin from the bot, linked in the [video archive](/docs/videos).

_Last updated: 2026-09-22_

---

## Updating txAdmin and FXServer

URL: https://fivemad.com/docs/txadmin/updating

txAdmin ships inside FXServer, so updating the artifact updates txAdmin. How to update, what to back up, migrating old start.bat configs to TXHOST variables, and rollbacks.

Since early 2020 txAdmin is a component of FXServer. There is no separate txAdmin download and no separate update button: **each FXServer artifact contains a specific txAdmin version**. Update the artifact and you update txAdmin.

## How to tell which version you run

- The txAdmin panel shows its version in the sidebar or footer, and the FXServer build number on the dashboard.
- The console prints both on start.

When a new txAdmin version is out, it arrives in a new artifact. The recommended artifact may lag behind the latest one by a few builds.

## The update, step by step

The artifact update routine is the same one described in [Updating artifacts safely](/docs/server-setup/updating-artifacts). Short version:

1. Check the build on our [Artifacts page](/artifacts), avoid builds flagged as broken.
2. Back up `txData` (it holds `admins.json`, player database, bans, warns and settings) and your database.
3. Stop the server and close FXServer.
4. Rename the old artifact folder, extract the new one to a fresh folder.
5. On Linux, make sure `txData` is where txAdmin expects it (by default next to `run.sh`, which is inside the artifact folder), or set `TXHOST_DATA_PATH`.
6. Start FXServer. txAdmin migrates its own config and database automatically on first start.
7. Check the dashboard, live console and in-game menu.

> [!WARNING]
> Going **back** to an older artifact after txAdmin migrated its data can fail, because the old version may not read the new format. That's why you back up `txData` before updating, not after.

## Migrating old start scripts (txAdmin v8)

Older guides start txAdmin with convars on the command line:

```bat title="start.bat (old style)"
@echo off
"C:/FXServer/server/FXServer.exe" +set serverProfile "server2" +set txAdminPort "40125"
pause
```

Since **txAdmin v8.0.0**, host settings are `TXHOST_*` environment variables. The `txAdminPort`, `txAdminInterface` and `txDataPath` convars (and the `txAdminZapConfig.json` file) are deprecated and will stop working in a future update. The txAdmin docs give this replacement:

```bat title="start.bat (current)"
@echo off
set TXHOST_DATA_PATH=C:\FXServer\txData-server2
set TXHOST_TXA_PORT=40125
"C:/FXServer/server/FXServer.exe"
pause
```

On Linux, add `export TXHOST_...=...` lines to a small `env.sh` and start with `source env.sh && ./run.sh`, or use `Environment=` lines in your systemd unit.

If both old and new configs exist, the new one wins. `TXHOST_IGNORE_DEPRECATED_CONFIGS=true` silences the warnings. The concept of **profiles** (`serverProfile`) will likely be deprecated too, so use one `txData` per server instead.

## What usually changes after an update

- New settings with default values (check the Settings pages after big updates).
- The in-game menu may look different or have new permissions: review your admins' permissions in the Admin Manager.
- Discord bot: new permissions or intents are occasionally needed. Check **System Logs** if the bot stops working.
- Deprecated features disappear. The [feature graveyard](https://github.com/citizenfx/txAdmin/blob/master/docs/feature-graveyard.md) lists what was removed and why (for example built in SSL: use a reverse proxy or Cloudflare Tunnel instead).

## Keeping up with changes

- The txAdmin [GitHub releases](https://github.com/citizenfx/txAdmin/releases) and the txAdmin Discord announce new versions.
- The official [txAdmin YouTube channel](https://www.youtube.com/@txAdmin) has short videos for some features.
- Cfx.re's forum announces artifact changes that affect server owners.

## FiveM for GTA V Enhanced

Enhanced uses a different server build (Cfx Server) with its own downloads, and txAdmin has a separate "FiveM Basic Server (Enhanced)" recipe. Don't point an Enhanced artifact at your Legacy `txData` and server folder and expect it to work: read the [Legacy and Enhanced notes](/docs/server-setup#fivem-legacy-and-fivem-for-gta-v-enhanced) and test on a copy.

_Last updated: 2026-09-22_

---


# Development

## Start developing for FiveM

URL: https://fivemad.com/docs/development

How to start writing FiveM scripts: choosing Lua, JavaScript or C#, setting up VS Code with Lua language server and FiveM natives, git, a dev server and a learning plan.

Writing FiveM scripts is one of the most rewarding ways to learn programming: you change a line, type `ensure`, and see the result in a game world a second later. This section takes you from zero to publishing your own resource.

## How FiveM code works, in one minute

- Your code lives in **resources**: folders with an `fxmanifest.lua` and some scripts.
- **Client scripts** run on every player's PC, inside their game. They draw things, read keys, spawn local effects, and call game **natives**.
- **Server scripts** run once, in FXServer. They own the truth: money, inventories, database, permissions.
- The two sides talk with **events**. The client can never be trusted, so the server checks everything.
- A web page (**NUI**) can be your UI, written in HTML, CSS and JavaScript (or React, Vue, Svelte...).

That's the whole model. Every page in this section expands one piece.

## Pick a language

FiveM runs three scripting runtimes, and a resource can mix them.

| Language | Runtime | Pros | Cons |
| --- | --- | --- | --- |
| **Lua 5.4** (CfxLua) | Built in | What 90% of resources, frameworks and tutorials use. Simple, fast to iterate. | Dynamic typing: mistakes show up at runtime. |
| **JavaScript / TypeScript** | V8 (client), Node.js (server, 16 by default, 22 with `node_version '22'`) | npm packages on the server, TypeScript types, familiar to web devs. | Fewer examples, some framework APIs are Lua first. |
| **C#** | Mono on Legacy (the Enhanced platform uses .NET 10) | Strong typing, big projects stay tidy, vMenu is written in C#. | Needs a build step, fewer community examples. |

**Start with Lua.** Frameworks (QBCore, Qbox, ESX), libraries (ox_lib) and almost every tutorial and forum answer are Lua. You can always add a React UI or a TypeScript server later.

> [!NOTE]
> Since June 2025, all Lua scripts run on Lua 5.4 and Lua 5.3 is deprecated. You'll still see `lua54 'yes'` in manifests: it's no longer required on current artifacts but it's harmless, and some tools and older guides still expect it.

## Tools you need

### 1. A local dev server

Develop on your own PC, never on the live server. Set one up with txAdmin in ten minutes: [Windows setup](/docs/server-setup/windows). Use the **FiveM Basic Server** recipe for learning, or the framework you target. Keep `sv_maxclients` low and consider a separate license key for it.

### 2. Visual Studio Code

[VS Code](https://code.visualstudio.com/) is what most FiveM developers use. Install these extensions:

| Extension | Why |
| --- | --- |
| **Lua** by sumneko (Lua Language Server) | Autocomplete, type checking, go to definition, diagnostics. |
| **CfxLua IntelliSense** (`overextended/cfxlua-vscode`) | Sets up [fivem-lls-addon](https://github.com/overextended/fivem-lls-addon): declarations for every FiveM and GTA native, plus CfxLua syntax like `` `backtick hashes` `` and compound operators. |
| **GitLens** or the built in Git panel | See what changed, when, and why. |
| **ESLint / Prettier** | If you write JavaScript or NUI. |

With the native declarations installed, typing `GetEntityCoo` completes to `GetEntityCoords(entity, alive)` with parameter hints. That alone saves hours of alt tabbing to the docs. The ox libraries also ship Lua type definitions ([ox_types](https://github.com/overextended/ox_types)).

[Setting up VSCode for FiveM Lua Development (CharlesHacks)](https://www.youtube.com/watch?v=JOnYzPzrzXI) (YouTube video)

### 3. Git

Put every resource (or your whole server folder) in git from day one. It's your undo button, your backup, and how you work with other developers. Keep secrets out of it: see [Security basics](/docs/server-setup/security#5-secrets-out-of-git-and-screenshots).

### 4. The docs, bookmarked

- [Scripting manual](https://docs.fivem.net/docs/scripting-manual/) and [scripting reference](https://docs.fivem.net/docs/scripting-reference/) on docs.fivem.net.
- [Natives reference](https://docs.fivem.net/natives/): every function the game gives you.
- [Resource manifest reference](https://docs.fivem.net/docs/scripting-reference/resource-manifest/).
- For UI and game data lookups, fivemad has references for [controls](/tools/controls-reference), [blips and markers](/tools/blip-marker-browser), [models and hashes](/tools/model-hash-browser), [props](/tools/objects-list), [particles](/tools/particles-list), [sounds](/tools/sound-browser) and the [map with coordinates](/tools/interactive-map).

## A learning plan

Work through these in order. Each page ends with something that runs.

1. [Your first resource](/docs/development/first-resource): folder, manifest, a `/hello` command, restarting, reading the F8 console.
2. [Client, server and events](/docs/development/client-server-events): the two sides and how they talk safely.
3. [Natives](/docs/development/natives): finding and using game functions, hashes, common natives.
4. [Threads and performance](/docs/development/threads-performance): loops, `Wait`, resmon and the profiler.
5. [State bags and OneSync](/docs/development/state-bags-onesync): syncing data, entity ownership, routing buckets.
6. [NUI basics](/docs/development/nui): HTML UIs, messages, callbacks, focus.
7. [Exports and dependencies](/docs/development/exports-dependencies): reusing code between resources, working with frameworks and libraries.
8. [Debugging](/docs/development/debugging): reading errors, print debugging, dev tools, common bugs.
9. [Streaming custom assets](/docs/development/streaming-assets): cars, clothes, maps, props and sounds.
10. [Publishing a resource](/docs/development/publishing): versioning, README, license, the forum, Tebex and escrow.

If you prefer video, the [Lua scripting course](/docs/videos) in the video archive follows a similar path.

## Habits that make you better fast

- **Read other people's code.** Open ox_lib, a Qbox resource or vMenu's source on GitHub and see how they solve things.
- **Keep the F8 console open** while testing. Errors tell you the file and line.
- **Small steps.** Change one thing, `ensure`, test. Don't write 300 lines and then start the server.
- **Server decides, client displays.** If you remember one rule, remember that one.
- **Don't copy paste from leaked scripts.** Bad habits, license trouble, and sometimes backdoors.
- **Ask good questions** on the [forum](https://forum.cfx.re): what you tried, the exact error, the code (formatted), what you expected.

_Last updated: 2026-09-22_

---

## Your first FiveM resource

URL: https://fivemad.com/docs/development/first-resource

Build a FiveM resource from scratch: folder, fxmanifest.lua, client and server scripts, a /hello command, a car spawner, ensure and restart, and reading the F8 console.

In this tutorial you build a resource with a client script and a server script, add chat commands, spawn a car, and learn the edit, `ensure`, test loop you'll use every day. You need a local server (see [Windows setup](/docs/server-setup/windows)) and VS Code (see [Start developing](/docs/development)).

[FiveM Scripting: Creating Your First Script (Twisle)](https://www.youtube.com/watch?v=dkqbgV2KUKw) (YouTube video)

## 1. Create the folder

Inside your server data folder, go to `resources`. Create a category folder `[local]` for your own work if it doesn't exist, and inside it a folder for the resource:

```text
resources/
└─ [local]/
   └─ hello_world/
      ├─ fxmanifest.lua
      ├─ client.lua
      └─ server.lua
```

The folder name **is** the resource name. Use lowercase, no spaces: `hello_world`, not `Hello World`.

## 2. Write the manifest

`fxmanifest.lua` tells FXServer what the resource is and which files run where:

```lua title="resources/[local]/hello_world/fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

name 'hello_world'
author 'You'
description 'My first FiveM resource'
version '1.0.0'

client_script 'client.lua'
server_script 'server.lua'
```

- `fx_version 'cerulean'` is the current manifest version. Always use it for new resources.
- `game 'gta5'` says this is for FiveM (RedM uses `rdr3`).
- `client_script` and `server_script` list the files for each side. Use the plural forms with `{ }` for several files, and globs like `'client/*.lua'` work.

You can generate manifests with the [fxmanifest Generator](/tools/fxmanifest-generator), which also warns about common mistakes.

## 3. A client command

```lua title="resources/[local]/hello_world/client.lua"
RegisterCommand('hello', function(source, args, rawCommand)
    local name = args[1] or 'world'
    TriggerEvent('chat:addMessage', {
        color = { 0, 200, 255 },
        args = { 'Hello', ('Hello, %s!'):format(name) },
    })
end, false)
```

- `RegisterCommand(name, handler, restricted)` creates `/hello`. On the client, `source` is always 0. `args` is a table of the words after the command.
- `TriggerEvent('chat:addMessage', ...)` sends a local event to the chat resource, which shows the message.
- `false` means anyone can use it. `true` would require the `command.hello` ACE permission.

## 4. A server command

```lua title="resources/[local]/hello_world/server.lua"
RegisterCommand('whoami', function(source, args)
    if source == 0 then
        print('This command was run from the server console.')
        return
    end

    local name = GetPlayerName(source)
    local license = GetPlayerIdentifierByType(source, 'license')

    print(('[hello_world] %s (id %d) asked who they are'):format(name, source))

    TriggerClientEvent('chat:addMessage', source, {
        args = { 'Server', ('You are %s, player id %d, %s'):format(name, source, license or 'no license') },
    })
end, false)
```

On the server, `source` is the **server ID** of the player who typed the command, or `0` for the console. `print` goes to the server console (txAdmin Live Console), and `TriggerClientEvent(name, target, ...)` sends an event to one player (`-1` sends to everyone).

## 5. Start it

In the txAdmin **Live Console** (or the server window), type:

```text
refresh
ensure hello_world
```

- `refresh` rescans the resources folder, so FXServer notices your new folder.
- `ensure` starts it (or restarts it if it's running).

You should see `Started resource hello_world`. To start it on every boot, add it to `server.cfg`:

```cfg title="server.cfg"
ensure hello_world
# or, to start everything in [local]:
ensure [local]
```

## 6. Test in game

Connect to your server, press <kbd>T</kbd> to open chat, and type `/hello` or `/hello Bob`. Then `/whoami`. You should see both messages, and the server console shows the `print` line.

## 7. The edit loop

Change the message in `client.lua`, save, then in the server console:

```text
ensure hello_world
```

The resource restarts and every connected client reloads it. Test again. This loop (edit, save, `ensure`, test) is how you'll work. You only need `refresh` again when you **add** a resource or change `fxmanifest.lua`.

> [!TIP]
> You can also type `ensure hello_world` in the **F8 console** in game if your account has permission to run server commands (the txAdmin master admin does, through `add_ace group.admin command allow`).

## 8. Read the F8 console

Press <kbd>F8</kbd> in game. This is the **client console**. Client `print` output and client errors show here. Add a print to `client.lua`:

```lua
print('hello_world client loaded')
```

`ensure` again and look for the line in F8. Now break something on purpose:

```lua
RegisterCommand('broken', function()
    local ped = nil
    print(ped.health) -- indexing nil
end, false)
```

Run `/broken` and F8 shows something like:

```text
SCRIPT ERROR: @hello_world/client.lua:14: attempt to index a nil value (local 'ped')
```

It tells you the resource, the file, the **line**, and what went wrong. Server errors look the same in the server console. More in [Debugging](/docs/development/debugging).

## 9. Spawn a car

Now use some game natives. This is the example from the official "creating your first script" guide:

```lua title="client.lua"
RegisterCommand('car', function(source, args)
    local vehicleName = args[1] or 'adder'

    if not IsModelInCdimage(vehicleName) or not IsModelAVehicle(vehicleName) then
        TriggerEvent('chat:addMessage', { args = { 'Invalid vehicle model: ' .. vehicleName } })
        return
    end

    RequestModel(vehicleName)
    while not HasModelLoaded(vehicleName) do
        Wait(500)
    end

    local playerPed = PlayerPedId()
    local pos = GetEntityCoords(playerPed)

    local vehicle = CreateVehicle(vehicleName, pos.x, pos.y, pos.z, GetEntityHeading(playerPed), true, false)
    SetPedIntoVehicle(playerPed, vehicle, -1)

    SetEntityAsNoLongerNeeded(vehicle)
    SetModelAsNoLongerNeeded(vehicleName)

    TriggerEvent('chat:addMessage', { args = { 'Enjoy your new ' .. vehicleName .. '!' } })
end, false)
```

What's going on:

- `IsModelInCdimage` / `IsModelAVehicle` check the model exists and is a vehicle. Natives accept a model name string and hash it for you.
- `RequestModel` + `HasModelLoaded` loads the model. `Wait(500)` gives the game time, without it the loop would freeze the game.
- `PlayerPedId()` is your character, `GetEntityCoords` its position (a `vector3`).
- `CreateVehicle(model, x, y, z, heading, isNetwork, netMissionEntity)` spawns it, networked so others see it.
- `SetPedIntoVehicle(ped, vehicle, -1)` seats you as the driver (`-1`).
- `SetModelAsNoLongerNeeded` frees the model from memory.

Try `/car sultan` or `/car zentorno`. Find spawn names in the [Model & Hash Browser](/tools/model-hash-browser).

> [!WARNING]
> Spawning vehicles from the client is fine for a learning server, but on a real server anyone could trigger it. Real resources spawn vehicles on the server, after checking permissions and money. See [Client, server and events](/docs/development/client-server-events).

## 10. Organise as it grows

When the resource gets bigger, split it:

```text
hello_world/
├─ fxmanifest.lua
├─ config.lua          shared settings
├─ client/
│  └─ main.lua
└─ server/
   └─ main.lua
```

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

shared_script 'config.lua'
client_scripts { 'client/*.lua' }
server_scripts { 'server/*.lua' }
```

```lua title="config.lua"
Config = {}
Config.DefaultCar = 'adder'
Config.Greeting = 'Hello'
```

Shared scripts load first, on both sides, so `Config` is available in client and server files.

## What you learned

- A resource is a folder with `fxmanifest.lua`.
- `refresh` finds new resources, `ensure` starts or restarts them.
- Client scripts run in the game, server scripts in FXServer, and `print` goes to F8 or the server console.
- Errors show file and line.
- Natives do the game work, and loading models needs a wait loop.

Next: [Client, server and events](/docs/development/client-server-events).

_Last updated: 2026-09-22_

---

## Client, server and events

URL: https://fivemad.com/docs/development/client-server-events

How FiveM client and server scripts talk: local and net events, TriggerServerEvent, TriggerClientEvent, source, callbacks with ox_lib, and why you never trust the client.

Every FiveM script runs on one of two sides, and the sides can only talk through **events**. Getting this right is the difference between a script that works and a script that gives cheaters free money.

[FiveM Lua Scripting Network Events (CharlesHacks, Zero to Hero Ep. 4)](https://www.youtube.com/watch?v=6-M5o_wiQP0) (YouTube video)

## The two sides

| | Client | Server |
| --- | --- | --- |
| Runs | On each player's PC, inside their game | Once, inside FXServer |
| Knows | Its own player, what's near them, input, the screen | All players, the database, the truth |
| Can do | Draw, read keys, play animations, local effects, most game natives | Kick, ban, save data, send events to anyone, server natives |
| Trust | **None.** Cheaters control it. | Full. |

A resource can have client, server and shared scripts. Shared scripts (config, utility functions) run on both sides, but each side has its own copy: changing `Config.x` on the client does nothing on the server.

## Local events

`TriggerEvent` fires an event on the **same side**, to every resource that listens:

```lua
-- any resource on the same side
AddEventHandler('myres:somethingHappened', function(what)
    print('It happened: ' .. what)
end)

TriggerEvent('myres:somethingHappened', 'a thing')
```

Prefix event names with your resource name (`myres:...`) so they don't clash with other resources.

## Network events

To cross from client to server or back, the receiving side must **register** the event as a net event.

### Client to server

```lua title="client.lua"
RegisterCommand('report', function(_, args)
    local message = table.concat(args, ' ')
    TriggerServerEvent('myres:report', message)
end, false)
```

```lua title="server.lua"
RegisterNetEvent('myres:report', function(message)
    local src = source                 -- who sent it, copy it right away
    if type(message) ~= 'string' or #message == 0 or #message > 200 then return end
    print(('[report] %s (%d): %s'):format(GetPlayerName(src), src, message))
end)
```

`source` is a global that FiveM sets to the **server ID of the player who triggered the event**. Copy it into a local at the top of the handler. After any `Wait` or async call, the global may belong to a different event.

### Server to client

```lua title="server.lua"
TriggerClientEvent('myres:notify', src, 'Your report was sent')   -- one player
TriggerClientEvent('myres:notify', -1, 'Server restart in 5 min') -- everyone
```

```lua title="client.lua"
RegisterNetEvent('myres:notify', function(text)
    BeginTextCommandThefeedPost('STRING')
    AddTextComponentSubstringPlayerName(text)
    EndTextCommandThefeedPostTicker(false, false)
end)
```

`RegisterNetEvent(name, handler)` both allows the event over the network and adds the handler. The older two step form (`RegisterNetEvent(name)` then `AddEventHandler(name, fn)`) does the same thing.

> [!NOTE]
> Without `RegisterNetEvent`, network triggers of that event are ignored. That's a safety feature: only events you explicitly register can be called from the other side.

### Big payloads

Events are for small data. For large data (a big table, a long string), use `TriggerLatentClientEvent(name, target, bytesPerSecond, ...)` or `TriggerLatentServerEvent`, which send it in the background without choking the connection. Or rethink: maybe the client only needs part of it.

## Getting an answer back: callbacks

Events are fire and forget. When the client needs an answer ("can I afford this?"), use a **callback**. FiveM has no built in client/server callback, so use ox_lib's:

```lua title="server.lua"
lib.callback.register('myres:getBalance', function(source)
    local player = exports.qbx_core:GetPlayer(source)   -- or your framework
    return player and player.PlayerData.money.bank or 0
end)
```

```lua title="client.lua"
local balance = lib.callback.await('myres:getBalance', false)
print('Bank balance: ' .. balance)
```

Both files need `shared_script '@ox_lib/init.lua'` in the manifest and `ox_lib` started. QBCore (`QBCore.Functions.CreateCallback` / `TriggerCallback`) and ESX (`ESX.RegisterServerCallback` / `ESX.TriggerServerCallback`) have their own versions.

## Security: never trust the client

A cheater with an executor can call **any** net event you registered, with **any** arguments, as often as they like. So every server handler must assume the worst.

### Bad

```lua title="server.lua (DON'T)"
RegisterNetEvent('fishing:sell', function(amount, price)
    local player = GetPlayer(source)
    player.addMoney(amount * price)     -- client decided the price and the amount
end)
```

### Good

```lua title="server.lua"
local FISH_PRICE = 25
local SELL_POINT = vector3(-1847.0, -1195.0, 14.3)
local lastSell = {}

RegisterNetEvent('fishing:sell', function()
    local src = source
    local player = GetPlayer(src)
    if not player then return end

    -- rate limit
    local now = os.time()
    if lastSell[src] and now - lastSell[src] < 2 then return end
    lastSell[src] = now

    -- position check on the server (OneSync)
    local ped = GetPlayerPed(src)
    if #(GetEntityCoords(ped) - SELL_POINT) > 5.0 then return end

    -- the server counts what the player has
    local count = player.getItemCount('fish')
    if count <= 0 then return end

    player.removeItem('fish', count)
    player.addMoney(count * FISH_PRICE)
end)

AddEventHandler('playerDropped', function()
    lastSell[source] = nil
end)
```

The rules:

1. **The server decides values**: prices, rewards, amounts, item names come from server config, not from arguments.
2. **Use `source`** to know who's asking. Never accept a player ID as an argument to act on "yourself".
3. **Validate arguments**: type, range, length, whitelist (`if not ALLOWED[item] then return end`).
4. **Check the situation**: distance (OneSync lets the server read `GetEntityCoords(GetPlayerPed(src))`), job, cooldown, whether they actually have the item.
5. **Rate limit** anything that gives something.
6. **Don't trigger server events from client "loops"** that give rewards. Give rewards when the server confirms the action.
7. **Log** money and item changes, so you can find abuse later.

## Useful built in events

| Event | Side | When |
| --- | --- | --- |
| `playerConnecting` | Server | A player starts connecting. Lets you defer, check bans, show adaptive cards. |
| `playerJoining` | Server | The player got a server ID and is joining. |
| `playerDropped` | Server | A player left. `source` is the player, first argument is the reason. |
| `onResourceStart` / `onResourceStop` | Both | Any resource started or stopped. Check `GetCurrentResourceName() == resourceName` to react to your own. |
| `onClientResourceStart` | Client | A resource started on this client. |
| `gameEventTriggered` | Client | Game events like `CEventNetworkEntityDamage`. See [Game Damage Events](/tools/damage-events) for kills, deaths and vehicle damage. |

```lua title="server.lua"
AddEventHandler('playerDropped', function(reason)
    local src = source
    print(('%s left: %s'):format(GetPlayerName(src), reason))
end)

AddEventHandler('onResourceStop', function(resourceName)
    if resourceName ~= GetCurrentResourceName() then return end
    -- save state before the resource stops
end)
```

## Commands as the entry point

`RegisterCommand` works on both sides. A client command that needs the server should just send an event, and let the server check permissions:

```lua title="server.lua"
RegisterCommand('heal', function(source, args)
    local target = tonumber(args[1]) or source
    if not IsPlayerAceAllowed(source, 'myres.heal') then return end
    TriggerClientEvent('myres:heal', target)
end, false)
```

```cfg title="server.cfg"
add_ace group.admin myres.heal allow
```

## Common mistakes

- Registering a client event with `AddEventHandler` only, then triggering it from the server: nothing happens, it isn't a net event.
- Using `source` after a `Wait()` or inside a callback: copy it first.
- Sending the full player list or huge tables every second: send changes only, or use [state bags](/docs/development/state-bags-onesync).
- Trusting `GetPlayerName` for identity: names can be anything. Use identifiers or your framework's citizen ID.

Next: [Natives](/docs/development/natives).

_Last updated: 2026-09-22_

---

## Natives: talking to the game

URL: https://fivemad.com/docs/development/natives

What FiveM natives are, how to find them on docs.fivem.net, read their signatures, use hashes and joaat, handle entities, and a cheat sheet of the natives you use most.

**Natives** are the functions the game engine exposes: `GetEntityCoords`, `SetPedIntoVehicle`, `DrawMarker` and thousands more. FiveM adds its own **CFX natives** on top (`GetPlayerIdentifierByType`, `SetResourceKvp`, state bags...). Almost everything your scripts do in the game world goes through a native.

[FiveM Lua Scripting Commands and Natives (CharlesHacks, Zero to Hero Ep. 3)](https://www.youtube.com/watch?v=CDzz67tp8FU) (YouTube video)

## Finding natives

The reference is at **[docs.fivem.net/natives](https://docs.fivem.net/natives/)**. It lists every known native, grouped by namespace (`PLAYER`, `PED`, `VEHICLE`, `ENTITY`, `OBJECT`, `HUD`, `GRAPHICS`, `STREAMING`, `TASK`, `CFX`...), with parameters, return values and often community notes. The data comes from the open [citizenfx/natives](https://github.com/citizenfx/natives) repository.

Tips for searching:

- Guess the verb and the thing: `SetVehicle...`, `GetPed...`, `IsEntity...`, `Create...`, `Delete...`.
- Filter by **client** or **server** on the page. Some natives exist only on the server (`GetPlayerIdentifierByType`, `DropPlayer`), most game natives only on the client.
- Natives without a proper name show as `_0x1234ABCD` or `N_0x...`. They work, they just haven't been named yet.
- Read the **examples and notes** at the bottom of a native's page. That's where people document the quirks.

With the [VS Code setup](/docs/development#2-visual-studio-code) (Lua Language Server plus the FiveM native declarations), you get autocomplete and parameter hints for all of them.

## Reading a signature

The docs show natives in C style:

```c
Vehicle CREATE_VEHICLE(Hash modelHash, float x, float y, float z, float heading, BOOL isNetwork, BOOL netMissionEntity);
```

In Lua you call the PascalCase name:

```lua
local veh = CreateVehicle(modelHash, x, y, z, heading, true, false)
```

- `Hash` is a number (see below), but most natives also accept a model name string and hash it.
- `Vehicle`, `Ped`, `Object`, `Entity` are **entity handles**: numbers valid on this client only.
- `BOOL` is `true` / `false` in Lua.
- Parameters marked with `*` are pointers (outputs). In Lua they come back as extra return values: `local found, groundZ = GetGroundZFor_3dCoord(x, y, z, false)`.
- `Vector3` returns are `vector3` values in Lua: `pos.x`, `pos.y`, `pos.z`, and you can subtract them and use `#(a - b)` for distance.

## Hashes and joaat

GTA identifies models, weapons, animations sets and much more by a 32 bit **hash** of the name, computed with Jenkins one-at-a-time (**joaat**).

```lua
local h1 = GetHashKey('adder')   -- native, works everywhere
local h2 = joaat('adder')        -- CfxLua helper, same result
local h3 = `adder`               -- CfxLua backtick syntax, hashed at compile time
print(h1 == h2, h2 == h3)        -- true true
```

Hashes can be shown as signed or unsigned numbers, or as hex. `adder` is the same model whether you see it as a negative or positive number. Use the [joaat Hash Calculator](/tools/hash-calculator) to convert a name to all three forms, and the [Model & Hash Browser](/tools/model-hash-browser) to look up vehicles, peds and weapons with pictures.

> [!TIP]
> Hashes are case insensitive: `joaat('ADDER') == joaat('adder')`. That's why spawn names work in any case.

## Entities, handles and network IDs

- An **entity handle** is a local number. Handle `123` on your client is not the same entity on another client or on the server.
- To tell another machine about an entity, send its **network ID**: `NetworkGetNetworkIdFromEntity(entity)` on one side, `NetworkGetEntityFromNetworkId(netId)` on the other (use `NetToVeh` / `NetToPed` on the client if you like).
- Check it still exists before using it: `DoesEntityExist(entity)`.
- With OneSync, the **server** can read and create entities too: `GetEntityCoords(GetPlayerPed(src))`, `CreateVehicleServerSetter(...)`. See [State bags and OneSync](/docs/development/state-bags-onesync).

## Loading things before using them

Models, animation dictionaries, particle assets, texture dictionaries and scaleforms must be **requested and loaded** before use:

```lua
local function loadModel(model)
    local hash = type(model) == 'number' and model or joaat(model)
    if not IsModelInCdimage(hash) then return nil end
    RequestModel(hash)
    local timeout = GetGameTimer() + 5000
    while not HasModelLoaded(hash) do
        if GetGameTimer() > timeout then return nil end
        Wait(0)
    end
    return hash
end

local function loadAnimDict(dict)
    RequestAnimDict(dict)
    while not HasAnimDictLoaded(dict) do Wait(0) end
end
```

Release them when done (`SetModelAsNoLongerNeeded`, `RemoveAnimDict`). ox_lib has ready made helpers: `lib.requestModel`, `lib.requestAnimDict`, `lib.requestNamedPtfxAsset`.

## A cheat sheet of common natives

### Player and ped

| Native | Use |
| --- | --- |
| `PlayerPedId()` | Your character's ped (client). Also available as `cache.ped` with ox_lib. |
| `PlayerId()` | Your local player index (client). |
| `GetPlayerServerId(PlayerId())` | Your server ID (client). |
| `GetPlayerPed(serverId)` | A player's ped on the server (OneSync). |
| `GetEntityCoords(ped)` / `GetEntityHeading(ped)` | Position and heading. |
| `SetEntityCoords(ped, x, y, z, false, false, false, false)` | Teleport. |
| `GetEntityHealth(ped)` / `SetEntityHealth(ped, 200)` | Health (peds: 100 dead, 200 full for the freemode ped). |
| `IsPedInAnyVehicle(ped, false)` / `GetVehiclePedIsIn(ped, false)` | Vehicle checks. |
| `GiveWeaponToPed(ped, joaat('weapon_pistol'), 50, false, true)` | Give a weapon. |
| `TaskPlayAnim(ped, dict, name, 8.0, -8.0, -1, flags, 0, false, false, false)` | Play an animation. Build the flags with the [Animation Flags Calculator](/tools/animation-flags-calculator). |

### Vehicles

| Native | Use |
| --- | --- |
| `CreateVehicle(model, x, y, z, heading, true, false)` | Spawn (client). |
| `SetPedIntoVehicle(ped, veh, -1)` | Seat as driver. |
| `SetVehicleNumberPlateText(veh, 'FIVEMAD')` | Plate. |
| `SetVehicleFixed(veh)` / `SetVehicleEngineHealth(veh, 1000.0)` | Repair. |
| `SetVehicleModKit(veh, 0)` then `SetVehicleMod(veh, modType, index, false)` | Tuning. |
| `TaskVehicleDriveToCoord(...)` | AI driving. The driving style flag comes from the [Driving Style Calculator](/tools/driving-style-calculator). |
| `DeleteEntity(veh)` | Remove. |

### World and UI

| Native | Use |
| --- | --- |
| `AddBlipForCoord(x, y, z)` + `SetBlipSprite`, `SetBlipColour` | Map blips. Browse sprites and colours in the [Blip, Marker & Checkpoint Browser](/tools/blip-marker-browser). |
| `DrawMarker(type, x, y, z, ...)` | 3D markers, must be called every frame. |
| `IsControlJustPressed(0, 38)` | Key input. Control 38 is <kbd>E</kbd>. Find indexes in the [Controls Reference](/tools/controls-reference). |
| `BeginTextCommandDisplayHelp('STRING')` ... | Help text top left. Colour codes like `~g~` preview in [Draw Text Colors](/tools/text-colors). |
| `PlaySoundFrontend(-1, name, set, true)` | UI sounds. Find names in the [Sound Browser](/tools/sound-browser). |
| `UseParticleFxAsset(asset)` + `StartParticleFxNonLoopedAtCoord(...)` | Particles. Names and dictionaries in the [Particle Effects List](/tools/particles-list) and with video previews on [/particles](/particles). |
| `CreateObject(joaat(model), x, y, z, true, false, false)` | Props. Search models with pictures in the [Objects / Props List](/tools/objects-list). |

### CFX natives (FiveM specific)

| Native | Use |
| --- | --- |
| `GetPlayerIdentifierByType(src, 'license')` | A player's identifier (server). |
| `GetPlayers()` | All player server IDs (server). |
| `DropPlayer(src, reason)` | Kick (server). |
| `GetConvar('name', 'default')` | Read a convar. |
| `SetResourceKvp` / `GetResourceKvpString` | Small persistent storage. |
| `GetCurrentResourceName()` | Your resource's name. |
| `PerformHttpRequest(url, cb, method, data, headers)` | HTTP from the server. |

## Coordinates

Most natives take world coordinates. Get them in game by printing `GetEntityCoords(PlayerPedId())`, or pick them on the [Interactive Map](/tools/interactive-map), which shows coordinates as you move over the map.

## Common native mistakes

- **Forgetting to load a model**: the entity doesn't appear or the game returns 0.
- **Calling a per frame native once**: `DrawMarker`, `DrawText`, `DisableControlAction` must run every frame in a loop with `Wait(0)`.
- **Using a client native on the server** (or the other way round): the docs page tells you which side it's for.
- **Passing an integer where a float is expected** in C# or JS is an error, in Lua it's usually fine, but write `1.0` for clarity.
- **Old names**: natives get renamed as people learn what they do. If a tutorial's native doesn't exist, search the hash on the natives page.

Next: [Threads and performance](/docs/development/threads-performance).

_Last updated: 2026-09-22_

---

## Threads and performance

URL: https://fivemad.com/docs/development/threads-performance

Write FiveM scripts that don't eat frames: CreateThread and Wait, dynamic waits, distance checks, ox_lib points, resmon, the profiler and reading its results.

Every client script shares the same game frame with GTA itself and every other resource. A resource that uses 1 ms per frame on a 60 FPS client is taking 6% of the frame budget. Ten of those and players feel it. This page shows how loops work, the patterns that keep them cheap, and how to measure.

[FiveM Lua Scripting Threads and Controls (CharlesHacks, Zero to Hero Ep. 5)](https://www.youtube.com/watch?v=9Mg-AO-YtUA) (YouTube video)

## Threads and Wait

Lua in FiveM uses coroutines. `CreateThread` starts one, and `Wait(ms)` pauses it and gives control back to the game:

```lua
CreateThread(function()
    while true do
        -- do something
        Wait(1000) -- sleep one second
    end
end)
```

- `Wait(0)` means "run again next frame". Needed for things drawn or checked every frame (markers, text, disabling controls).
- A `while true` loop **without** a `Wait` freezes the game (client) or the server (server side). txAdmin will eventually restart a server stuck like this.
- `Wait` only works inside a thread or an event/command handler, which already run as coroutines.
- `SetTimeout(ms, fn)` runs a function once after a delay, without a loop.

## The classic mistake

```lua title="client.lua (slow)"
CreateThread(function()
    while true do
        Wait(0)
        local pos = GetEntityCoords(PlayerPedId())
        for _, shop in ipairs(Config.Shops) do            -- 40 shops
            if #(pos - shop.coords) < 20.0 then
                DrawMarker(2, shop.coords.x, shop.coords.y, shop.coords.z, 0,0,0, 0,0,0, 0.3,0.3,0.3, 255,255,255,150, false,true,2, nil,nil,false)
            end
        end
    end
end)
```

It checks 40 distances **every frame** even when you're on the other side of the map. Multiply by every resource written like this.

## Pattern 1: dynamic wait

Sleep long when nothing is near, go per frame only when needed:

```lua title="client.lua"
CreateThread(function()
    while true do
        local sleep = 1000
        local pos = GetEntityCoords(PlayerPedId())

        for _, shop in ipairs(Config.Shops) do
            local dist = #(pos - shop.coords)
            if dist < 20.0 then
                sleep = 0
                DrawMarker(2, shop.coords.x, shop.coords.y, shop.coords.z, 0,0,0, 0,0,0, 0.3,0.3,0.3, 255,255,255,150, false,true,2, nil,nil,false)
                if dist < 1.5 and IsControlJustPressed(0, 38) then -- E
                    openShop(shop)
                end
            end
        end

        Wait(sleep)
    end
end)
```

Far from every shop, the loop runs once a second. That's usually a 20 to 50x cut in cost.

## Pattern 2: ox_lib points and zones

ox_lib does the distance bookkeeping for you and only calls your code near the point:

```lua title="client.lua"
for _, shop in ipairs(Config.Shops) do
    lib.points.new({
        coords = shop.coords,
        distance = 20,
        nearby = function(self)
            -- runs every frame only while within 20 units
            DrawMarker(2, self.coords.x, self.coords.y, self.coords.z, 0,0,0, 0,0,0, 0.3,0.3,0.3, 255,255,255,150, false,true,2, nil,nil,false)
            if self.currentDistance < 1.5 and IsControlJustPressed(0, 38) then
                openShop(shop)
            end
        end,
    })
end
```

`lib.zones` does the same for boxes, spheres and polygons with `onEnter` / `onExit`. Interaction resources like **ox_target** avoid loops entirely: players aim at something and pick an option.

## Pattern 3: events instead of polling

Don't check "is the player in a vehicle?" every frame if you can react to a change. ox_lib's `cache` updates values and fires events when they change:

```lua
lib.onCache('vehicle', function(vehicle)
    if vehicle then
        print('Entered vehicle', vehicle)
    else
        print('Left vehicle')
    end
end)
```

On the server, react to `playerDropped`, `onResourceStop`, state bag change handlers (see [State bags](/docs/development/state-bags-onesync)) instead of loops.

## More habits that matter

- **Cache what doesn't change within a loop**: call `PlayerPedId()` once per iteration, not five times. (ox_lib's `cache.ped` keeps it for you.)
- **Use vector math**: `#(a - b)` is faster and simpler than `GetDistanceBetweenCoords`.
- **Don't create entities, blips or threads in loops** without cleaning them up.
- **Avoid string building and table creation every frame**: they create garbage for the Lua GC.
- **Server side, never block**: use async database calls (`MySQL.query` with a callback, or `.await` inside a thread), not busy waits.
- **Don't send events every frame.** Send on change, or at most a few times per second, and batch.
- **Unload what you load**: models, anim dicts, ptfx assets, scaleforms.

## Measuring: resmon

Press <kbd>F8</kbd> and type:

```text
resmon 1
```

The resource monitor shows each client resource's **CPU time in ms per frame** and memory. Rough guide:

| ms | Meaning |
| --- | --- |
| `0.00` to `0.02` | Idle, great. |
| `0.02` to `0.10` | Fine for most resources. |
| `0.10` to `0.50` | Worth a look, especially if it's constant while nothing happens. |
| `> 0.50` constant | Something runs every frame that shouldn't. |

Test in the situations that matter: standing still, driving, near the resource's zone, with the UI open. A HUD or a target system will naturally use a bit more. On the server, txAdmin's performance chart shows tick times, and the server console prints `hitch` warnings when a tick takes too long.

## Measuring: the profiler

For "which function exactly?", use the built in profiler. It works on the client (F8) and the server console:

```text
profiler record 500
profiler view
```

- `profiler record 500` records 500 frames (the docs recommend 500).
- `profiler status` shows whether it's still recording.
- `profiler view` opens the result in Chrome's performance view (on the server, it prints a link you open yourself).
- `profiler saveJSON myprofile.json` saves it to a file.

In the view, the green graph is FPS and the yellow one CPU time. Spikes are hitches. Hover a frame to see which resource and which line took the time.

To skip reading flame charts, drop the saved JSON into the [Profiler Analyzer](/tools/profiler-analyzer): it shows which resources and threads use your frame or tick time and suggests fixes.

[Fivem Resmon & Event Log Tutorial (Lith Studios)](https://www.youtube.com/watch?v=yTSm2ba4RBk) (YouTube video)

## Server performance

- **Tick time**: the server runs its main loop on one thread. Long running Lua on the server delays everything, including sync.
- **Database**: slow queries show up as `mysql_slow_query_warning` messages when you set that convar. Add indexes to columns you search by (identifier, citizenid, plate).
- **Entities**: thousands of networked objects hurt everyone. Clean up what your scripts spawn.
- **Scheduled restarts** hide memory leaks but don't fix them. Find them with resmon's memory column and the profiler.

## Assets are performance too

A perfectly coded server still stutters if it streams 4K textures on every car. Oversized `.ytd` files cause texture loss and memory pressure. See [Streaming custom assets](/docs/development/streaming-assets#keep-it-light) and the [YTD Optimizer](/tools/ytd-optimizer).

Next: [State bags and OneSync](/docs/development/state-bags-onesync).

_Last updated: 2026-09-22_

---

## State bags, OneSync and entity ownership

URL: https://fivemad.com/docs/development/state-bags-onesync

Sync data the FiveM way: GlobalState, Player and Entity state bags, change handlers, replication rules, OneSync entity ownership, server side entities and routing buckets.

With OneSync on, the server knows about every player and entity and decides which clients see what. On top of that, FiveM gives you **state bags**: key/value data attached to the server, a player or an entity, synced to clients automatically. Together they replace a lot of hand written event syncing.

[How to use State Bags (CharlesHacks, FiveM Lua Scripting Master Series)](https://www.youtube.com/watch?v=6CSXtJpH0qQ) (YouTube video)

## OneSync in two minutes

- Enabled with `set onesync on` in `server.cfg`. Every current framework requires it.
- The server tracks all networked entities. Clients only receive entities near them: the culling radius is 424 units around each player.
- Each networked entity has an **owner**: the client that simulates it (usually the closest or the one who created it). The owner sends updates, the server forwards them.
- The server can **read** entity state (`GetEntityCoords(GetPlayerPed(src))`, `GetVehicleNumberPlateText`) and **create** entities.
- **Routing buckets** split the world into separate dimensions.
- Up to 48 slots free, up to 2048 with the right Cfx.re tier.

## State bags

There are three kinds, all with the same API:

| Bag | Where | Who can write (default) |
| --- | --- | --- |
| `GlobalState` | Server wide | Server only |
| `Player(serverId).state` (server) / `LocalPlayer.state` (client) | One player | The server, or that player's client |
| `Entity(entity).state` | One networked entity | The server, or the entity's owner |

### Set and read

```lua title="server.lua"
GlobalState.weather = 'RAIN'
GlobalState.maintenance = false

Player(src).state:set('job', 'police', true)          -- true = replicate to clients

local veh = CreateVehicleServerSetter(`police3`, 'automobile', 441.0, -1019.0, 28.5, 90.0)
Entity(veh).state:set('fuel', 100.0, true)
```

```lua title="client.lua"
print(GlobalState.weather)                           -- 'RAIN'
print(LocalPlayer.state.job)                         -- 'police'

local veh = GetVehiclePedIsIn(PlayerPedId(), false)
if veh ~= 0 then
    print(Entity(veh).state.fuel)
end
```

Setting with `.key = value` uses the default replication: values set by the server replicate to clients, values set by a client do **not** replicate. `state:set(key, value, replicated)` lets you choose. The server can also keep private data on a bag with `replicated = false`.

### React to changes

```lua title="client.lua"
AddStateBagChangeHandler('fuel', nil, function(bagName, key, value, _reserved, replicated)
    local entity = GetEntityFromStateBagName(bagName)
    if entity == 0 then return end
    print(('Fuel of %d is now %.1f'):format(entity, value))
end)
```

- The second argument filters by bag name (`nil` for all bags). Bag names look like `player:12`, `entity:345` or `global`.
- `GetEntityFromStateBagName` and `GetPlayerFromStateBagName` turn a bag name back into a handle.
- The entity may not exist yet on this client when the handler fires, so check for `0`.

### Rules and limits

- **Flat keys only.** Nested writes like `Entity(x).state.car.fuel = 5` don't sync, the getters and setters are naive. Use `Entity(x).state['car:fuel']` or set the whole table again.
- **Keep values small.** Every replicated change goes to every client that can see the bag.
- **Security**: by default a client can write its own player bag and bags of entities it owns (not replicated unless it chooses to). If your resources only set state from the server, set `sv_stateBagStrictMode true` so clients can't write at all. Never trust a value a client could have written.

## When to use what

| You want | Use |
| --- | --- |
| A value everyone can read, changes rarely (weather, server flags) | `GlobalState` |
| Per player data other scripts or clients need (job, duty, radio channel, is dead) | `Player(src).state` |
| Data that belongs to a car or object (fuel, locked, owner, siren mode) | `Entity(ent).state` |
| A one off action ("play this sound now") | An event |
| A request with an answer | A callback |
| Large or private data | Server memory or database, send only what's needed |

## Entity ownership

- `NetworkGetEntityOwner(entity)` (server) returns the server ID of the client that owns it.
- Ownership moves as players move. Scripts that change an entity (freeze it, set its velocity) should do it on the owner, or on the server with the server setters.
- Before changing a networked entity on a client that doesn't own it, request control: `NetworkRequestControlOfEntity(entity)` and wait for `NetworkHasControlOfEntity(entity)`. It can fail or take time.
- `SetEntityOrphanMode` (server) controls what happens to an entity when its owner leaves, so server created vehicles don't vanish.

## Creating entities on the server

With OneSync the server can create entities, which is safer than trusting clients to spawn things:

```lua title="server.lua"
RegisterNetEvent('garage:takeOut', function(plate)
    local src = source
    -- ...check that src owns this car and is near the garage...
    local coords = vector4(215.0, -810.0, 30.7, 157.0)
    local veh = CreateVehicleServerSetter(`sultan`, 'automobile', coords.x, coords.y, coords.z, coords.w)
    while not DoesEntityExist(veh) do Wait(0) end
    SetVehicleNumberPlateText(veh, plate)
    Entity(veh).state:set('owner', GetPlayerIdentifierByType(src, 'license'), true)
    TriggerClientEvent('garage:enter', src, NetworkGetNetworkIdFromEntity(veh))
end)
```

The client then gets the entity from the network ID:

```lua title="client.lua"
RegisterNetEvent('garage:enter', function(netId)
    local veh = NetworkGetEntityFromNetworkId(netId)
    local timeout = GetGameTimer() + 3000
    while not DoesEntityExist(veh) and GetGameTimer() < timeout do
        Wait(0)
        veh = NetworkGetEntityFromNetworkId(netId)
    end
    if DoesEntityExist(veh) then
        SetPedIntoVehicle(PlayerPedId(), veh, -1)
    end
end)
```

`CreateVehicleServerSetter` is the recommended server vehicle native (it takes the vehicle type, like `automobile`, `bike`, `heli`). `CreateVehicle`, `CreatePed` and `CreateObjectNoOffset` also exist on the server. If you enable `sv_entityLockdown strict`, the server is the **only** place entities can be created, so this pattern becomes required.

## Routing buckets

A routing bucket is a separate world. Players and entities in different buckets can't see or interact with each other. Bucket `0` is the default.

```lua title="server.lua"
-- put a player in their own apartment instance
SetPlayerRoutingBucket(src, 1000 + src)
SetRoutingBucketPopulationEnabled(1000 + src, false)  -- no ambient peds and traffic there
SetRoutingBucketEntityLockdownMode(1000 + src, 'strict')

-- back to the main world
SetPlayerRoutingBucket(src, 0)
```

Use cases: character selection, apartments and instanced interiors, races, events, admin testing. Entities created by a player in a bucket stay in that bucket (`SetEntityRoutingBucket` moves them).

[How to use Routing Buckets (CharlesHacks)](https://www.youtube.com/watch?v=Bh2JuQoWbno) (YouTube video)

## Common mistakes

- Expecting a client written state value to show up on other clients: it doesn't unless replicated, and the server should be the writer anyway.
- Nested table writes to state bags (see limits above).
- Keeping entity handles across machines: send network IDs.
- Deleting or changing an entity you don't own and wondering why it comes back.
- Forgetting that players in another routing bucket are invisible to each other, then debugging "sync bugs".

Next: [NUI basics](/docs/development/nui).

_Last updated: 2026-09-22_

---

## NUI basics: HTML interfaces in FiveM

URL: https://fivemad.com/docs/development/nui

Build FiveM UIs with NUI: ui_page and files, SendNUIMessage, RegisterNUICallback with fetch, SetNuiFocus, dev tools, React or Vue with a build step, and common pitfalls.

**NUI** is FiveM's built in Chromium (CEF) browser. Every resource can have a web page that sits on top of the game: HUDs, menus, phones, inventories, loading screens. You write it with HTML, CSS and JavaScript, or any framework that builds to static files (React, Vue, Svelte, Solid...).

[How to Create HUDs and UIs using NUI (CharlesHacks, Zero to Hero Ep. 7)](https://www.youtube.com/watch?v=Z2yUTkE94pQ) (YouTube video)

## How it fits together

```text
 Lua client script  ── SendNUIMessage({...}) ──►  your page (window 'message' event)
 Lua client script  ◄── RegisterNUICallback ────  fetch('https://<resource>/<name>')
```

- Lua sends data **to** the page with `SendNUIMessage`.
- The page sends data **back** with an HTTP style `fetch` to `https://<resource-name>/<callback-name>`, which triggers a `RegisterNUICallback` handler in Lua.
- `SetNuiFocus` decides whether the page gets the mouse and keyboard.
- The page never talks to the server directly. If the server needs to know, Lua forwards it with an event.

## A minimal example

```text
nui_demo/
├─ fxmanifest.lua
├─ client.lua
└─ html/
   ├─ index.html
   ├─ style.css
   └─ app.js
```

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

client_script 'client.lua'

ui_page 'html/index.html'

files {
    'html/index.html',
    'html/style.css',
    'html/app.js',
}
```

Every file the page loads must be listed in `files`, or the client never downloads it and you get a blank or broken UI.

```html title="html/index.html"
<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <div id="panel" class="hidden">
    <h1 id="title">Hello</h1>
    <button id="close">Close</button>
  </div>
  <script src="app.js"></script>
</body>
</html>
```

```css title="html/style.css"
html, body { margin: 0; background: transparent; font-family: sans-serif; }
.hidden { display: none; }
#panel {
  position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%);
  padding: 24px; background: rgba(15, 15, 15, 0.9); color: #fff; border-radius: 8px;
}
```

Keep the `body` background **transparent**, or the page covers the game.

```js title="html/app.js"
const panel = document.getElementById('panel');
const title = document.getElementById('title');

window.addEventListener('message', (event) => {
  const data = event.data;
  if (data.action === 'open') {
    title.textContent = data.title;
    panel.classList.remove('hidden');
  } else if (data.action === 'close') {
    panel.classList.add('hidden');
  }
});

function post(name, body = {}) {
  return fetch(`https://${GetParentResourceName()}/${name}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json; charset=UTF-8' },
    body: JSON.stringify(body),
  }).then((r) => r.json());
}

document.getElementById('close').addEventListener('click', () => post('close'));

document.addEventListener('keyup', (e) => {
  if (e.key === 'Escape') post('close');
});
```

`GetParentResourceName()` is available inside NUI pages and returns your resource name, so the callback URL stays right if someone renames the folder.

```lua title="client.lua"
local open = false

local function setOpen(state)
    open = state
    SetNuiFocus(state, state)          -- keyboard focus, mouse cursor
    SendNUIMessage({ action = state and 'open' or 'close', title = 'Hello from Lua' })
end

RegisterCommand('demo', function()
    setOpen(not open)
end, false)

RegisterNUICallback('close', function(data, cb)
    setOpen(false)
    cb({ ok = true })                  -- always answer, or fetch() hangs
end)
```

`ensure nui_demo`, type `/demo`, and the panel appears with a mouse cursor. <kbd>Esc</kbd> or the button closes it.

## Focus

`SetNuiFocus(hasFocus, hasCursor)`:

- `SetNuiFocus(true, true)`: the page gets keyboard and mouse. The player can't move or use game controls. Use for menus.
- `SetNuiFocus(false, false)`: the page is display only (HUDs). The game keeps control.
- `SetNuiFocusKeepInput(true)` lets the game still receive keyboard input while the page has focus, for UIs where the player keeps walking. Disable the controls you don't want yourself.

> [!WARNING]
> Always give the player a way out (<kbd>Esc</kbd>, a close button) and release focus on close. A UI that keeps focus traps the player, who has to quit the game. Also release focus on `onResourceStop`.

If your UI opens with <kbd>Tab</kbd> (inventories do), check `IsNuiFocused()` first so it doesn't steal focus from another open UI like the txAdmin menu.

## Debugging NUI

Type `nui_devtools` in the F8 console to open Chrome DevTools for NUI: console logs, element inspector, network tab. Errors in your JavaScript show there, not in F8.

Other tips:

- Develop the page in a normal browser first, faking the `message` events with `window.postMessage({ action: 'open', title: 'test' })`.
- `ui_page` can point to a dev server URL (`ui_page 'http://localhost:5173'`) while you work, so hot reload works. Switch back to the built file before you ship.

## React, Vue and friends

Frameworks work fine. You build to static files and point `ui_page` at the built `index.html`:

```lua title="fxmanifest.lua"
ui_page 'web/build/index.html'

files {
    'web/build/index.html',
    'web/build/**/*',
}
```

- Use **relative** asset paths in your build (Vite: `base: './'`), because the page is served from `https://cfx-nui-<resource>/`.
- Starters save setup time: [project-error/fivem-react-boilerplate-lua](https://github.com/project-error/fivem-react-boilerplate-lua) (React + TypeScript + Lua) and [overextended/fivem-typescript-boilerplate](https://github.com/overextended/fivem-typescript-boilerplate).
- Ship the **built** folder in releases. Server owners shouldn't need Node to run your resource.

## Loading screens

A loading screen is a special NUI page shown while the player joins:

```lua title="fxmanifest.lua"
loadscreen 'html/index.html'
files { 'html/**/*' }
-- optional: keep it until you close it yourself
loadscreen_manual_shutdown 'yes'
```

With manual shutdown, call `ShutdownLoadingScreenNui()` from a client script when your spawn is ready, or players stay on the loading screen forever.

## Performance

- NUI pages that animate constantly (CSS animations, requestAnimationFrame, big videos) cost GPU and CPU on every client. Pause them when hidden.
- Don't `SendNUIMessage` every frame. Send when data changes, or a few times per second for HUD values.
- Keep images reasonable in size. Every file in `files` is downloaded by every player.

## Common mistakes

| Symptom | Cause |
| --- | --- |
| Blank UI | `ui_page` or its assets not listed in `files`, wrong path, or absolute asset paths in a framework build. |
| `fetch` never resolves | The Lua `RegisterNUICallback` handler didn't call `cb()`. |
| UI shows but clicks do nothing | `SetNuiFocus(true, true)` not called. |
| Player stuck with a cursor | Focus not released on close or on resource stop. |
| White or black background over the game | `body` or `html` background isn't transparent. |
| Works in browser, not in game | Using APIs NUI doesn't allow, or the callback URL doesn't match the resource name. Use `GetParentResourceName()`. |

Next: [Exports and dependencies](/docs/development/exports-dependencies).

_Last updated: 2026-09-22_

---

## Exports and dependencies

URL: https://fivemad.com/docs/development/exports-dependencies

Share code between FiveM resources with exports, call framework functions, declare dependencies in fxmanifest, import @resource files and bridge frameworks.

Resources are isolated from each other: a global variable in one resource doesn't exist in another. To share functionality you use **exports** (call a function in another resource) and **shared files** (load another resource's file into yours with `@resource/path`). **Dependencies** make sure the resource you rely on is there and starts first.

[FiveM Scripting 15: Server and Client Sided Exports (Jeva)](https://www.youtube.com/watch?v=7VvwSEXYO-w) (YouTube video)

## Exports

### Defining an export

```lua title="banking/server.lua"
local accounts = {}

exports('getBalance', function(identifier)
    return accounts[identifier] or 0
end)

exports('addBalance', function(identifier, amount)
    if type(amount) ~= 'number' or amount <= 0 then return false end
    accounts[identifier] = (accounts[identifier] or 0) + amount
    return true
end)
```

`exports(name, fn)` works in Lua without any manifest entry. Exports are per side: a server export is only callable from server scripts, a client export only from client scripts.

### Calling an export

```lua title="another_resource/server.lua"
local balance = exports.banking:getBalance(identifier)
exports['banking']:addBalance(identifier, 500)
```

Use the bracket form when the resource name has a dash: `exports['qb-core']:GetCoreObject()`. Note the **colon**: exports are called like methods.

If the resource isn't started, the call errors with `No such export getBalance in resource banking`. Guard with `GetResourceState('banking') == 'started'` if it's optional.

### JavaScript and C#

```js
exports('getBalance', (identifier) => accounts[identifier] ?? 0);
const balance = exports.banking.getBalance(identifier);
```

C# resources call them through `Exports["banking"].getBalance(identifier)`.

## Using a framework through exports

Frameworks expose their core object or functions as exports:

```lua
-- QBCore
local QBCore = exports['qb-core']:GetCoreObject()
local Player = QBCore.Functions.GetPlayer(source)

-- Qbox
local player = exports.qbx_core:GetPlayer(source)
exports.qbx_core:AddMoney(source, 'cash', 100, 'fishing')

-- ESX Legacy
local ESX = exports['es_extended']:getSharedObject()
local xPlayer = ESX.GetPlayerFromId(source)

-- ox_inventory
exports.ox_inventory:AddItem(source, 'water', 1)
```

See the [Frameworks](/docs/frameworks) pages for more.

## Importing files with @resource

A manifest can load another resource's file as if it were yours:

```lua title="fxmanifest.lua"
shared_script '@ox_lib/init.lua'
server_script '@oxmysql/lib/MySQL.lua'
```

- `@ox_lib/init.lua` sets up the `lib` global and `cache` in your resource.
- `@oxmysql/lib/MySQL.lua` gives you the `MySQL` global.
- `@qbx_core/modules/lib.lua` and `@qbx_core/modules/playerdata.lua` are Qbox helpers.
- `@es_extended/imports.lua` sets up `ESX` in your resource.

The file runs inside **your** resource's environment, so this is faster than calling an export for every small helper. The other resource must be present (and for ox_lib, started first).

## Dependencies

List what your resource needs in the manifest:

```lua title="fxmanifest.lua"
dependencies {
    'oxmysql',
    'ox_lib',
    '/onesync',             -- requires OneSync
    '/server:12913',        -- requires at least this server artifact
    '/gameBuild:3095',      -- requires at least this game build (name like 'h4' works too)
}
```

FXServer then:

- starts listed resources before yours, and refuses to start yours if one is missing,
- refuses to start it if the server or game requirements aren't met, with a clear error.

This is much more reliable than hoping `ensure` order in `server.cfg` is right. The `/server:`, `/onesync`, `/gameBuild:`, `/policy:` and `/native:` forms come from the official manifest reference. The build numbers above are just examples: use the ones your resource really needs.

## `provide`: replacing another resource

```lua title="fxmanifest.lua"
provide 'mysql-async'
```

Tells FXServer this resource satisfies dependencies on `mysql-async`. oxmysql uses it so old resources that depend on mysql-async or ghmattimysql keep working. Only use `provide` if you really implement the same API.

## Writing framework independent resources

If you want your resource to work on QBCore, Qbox and ESX, don't sprinkle framework calls everywhere. Put them behind a small **bridge**:

```lua title="bridge/server.lua"
Bridge = {}

local function detect()
    if GetResourceState('qbx_core') == 'started' then return 'qbx' end
    if GetResourceState('qb-core') == 'started' then return 'qb' end
    if GetResourceState('es_extended') == 'started' then return 'esx' end
    return 'standalone'
end

local fw = detect()
local QBCore = fw == 'qb' and exports['qb-core']:GetCoreObject() or nil
local ESX = fw == 'esx' and exports['es_extended']:getSharedObject() or nil

function Bridge.addMoney(src, amount)
    if fw == 'qbx' then
        return exports.qbx_core:AddMoney(src, 'cash', amount)
    elseif fw == 'qb' then
        local p = QBCore.Functions.GetPlayer(src)
        return p and p.Functions.AddMoney('cash', amount)
    elseif fw == 'esx' then
        local x = ESX.GetPlayerFromId(src)
        if x then x.addMoney(amount) return true end
    end
    return false
end
```

The rest of your code calls `Bridge.addMoney(src, 100)` and never cares which framework runs. Paid resources on Tebex use exactly this pattern, often leaving the bridge files open under `escrow_ignore`. (Qbox also ships QBCore compatibility, so many `qb-core` calls work on Qbox too.)

## Load order inside a resource

- `shared_scripts` load first, on both sides.
- Then `client_scripts` (client) or `server_scripts` (server), in the order listed.
- Globs (`client/*.lua`) load in alphabetical order.

So put `config.lua` and library imports at the top of `shared_scripts`.

## Common mistakes

- `No such export`: wrong resource name (check the folder name), resource not started, calling a server export from the client (or the reverse), or the export was renamed in a new version.
- `attempt to index a nil value (global 'lib')`: you forgot `shared_script '@ox_lib/init.lua'`.
- Circular dependencies: A depends on B and B on A. Move shared code into a third resource.
- Exporting huge tables every call: exports copy data between resources. Return what's needed.

Next: [Debugging](/docs/development/debugging).

_Last updated: 2026-09-22_

---

## Debugging FiveM resources

URL: https://fivemad.com/docs/development/debugging

Find and fix bugs in FiveM scripts: read SCRIPT ERROR lines, print and dump tables, the F8 and server consoles, NUI devtools, common Lua errors and a debugging routine.

Most FiveM bugs are found in minutes if you know where to look. This page is the routine: where errors show up, how to read them, how to narrow down a bug, and the errors you'll see most.

## Where output goes

| Output from | Shows in |
| --- | --- |
| Server scripts (`print`, errors) | The server console / txAdmin **Live Console**, and txAdmin's log files |
| Client scripts | The **F8** console in game, and `CitizenFX.log` in the FiveM application data `logs` folder |
| NUI JavaScript | NUI DevTools (`nui_devtools` in F8) |
| Resource start/stop messages | Server console |

Keep the F8 console and the Live Console open side by side while you test.

## Reading a script error

```text
SCRIPT ERROR: @my_shop/server/main.lua:42: attempt to perform arithmetic on a nil value (local 'price')
> handler (@my_shop/server/main.lua:42)
> fn (@ox_lib/imports/callback/server.lua:28)
```

- `@my_shop/server/main.lua:42`: resource, file, **line**. Go there first.
- `attempt to perform arithmetic on a nil value (local 'price')`: what went wrong and which variable. `price` is `nil` on line 42.
- The lines starting with `>` are the **stack trace**: how the code got there. Here an ox_lib callback called our handler.

Now ask: why is `price` nil? Usually a table lookup with a key that doesn't exist (`Config.Prices[item]` with a typo in `item`), or an argument the other side didn't send.

## Print debugging

Plain `print` is still the most used tool:

```lua
print('buy called', src, item, amount)
print(json.encode(data, { indent = true }))   -- dump a table
```

- `json.encode` turns tables into readable text. `print(someTable)` alone prints only `table: 0x...`.
- ox_lib has `lib.print.info(...)`, `lib.print.debug(...)` with log levels you can switch with a convar (`ox:printlevel`).
- Prefix your prints with the resource or function name so you can find them among other output.
- Remove debug prints (or put them behind a `Config.Debug` flag) before release. Spamming the console costs performance.

## A debugging routine

1. **Reproduce it.** Find the exact steps that trigger the bug.
2. **Read the first error**, not the last. Later errors are often side effects.
3. **Check which side** the problem is on: does the server get the event? Put a print at the top of the server handler. Does the client get the reply? Print in the client handler.
4. **Check the inputs**: print the arguments at the start of the function. Half of all bugs are "the value wasn't what I thought".
5. **Cut it in half**: comment out half of the suspicious code, see if the bug stays, repeat.
6. **Restart just your resource** (`ensure name`) instead of the whole server, it's faster. But if things behave oddly after many restarts, restart the server: some resources don't clean up on stop.
7. **Check the load order**: framework not started yet, dependency missing, `ensure` order in `server.cfg`.
8. **Change one thing at a time**, then test.

## The errors you'll see most

| Error | Usually means |
| --- | --- |
| `attempt to index a nil value (global 'QBCore')` / `'ESX'` / `'lib'` | You never got the framework or library object in this file or resource. Add `local QBCore = exports['qb-core']:GetCoreObject()`, `shared_script '@ox_lib/init.lua'`, or `@es_extended/imports.lua`. |
| `attempt to index a nil value (local 'Player')` | `GetPlayer(source)` returned nil: wrong `source` (used after a `Wait`), player not loaded yet, or the player left. Check before using. |
| `attempt to call a nil value (field 'X')` | Calling a function that doesn't exist: typo, wrong framework version, or a method renamed in an update. |
| `No such export X in resource Y` | Resource not started, wrong name, wrong side, or the export doesn't exist in that version. |
| `attempt to compare number with nil` | A value you compare is missing. Often a config key typo. |
| `bad argument #1 to 'X'` | Wrong type passed to a function or native (a string where a number is expected, a nil). |
| `Couldn't load resource X` | Manifest syntax error or missing file. |
| `SCRIPT ERROR ... stack overflow` | A function calls itself forever, or two events trigger each other. |
| `json.decode` error | The string isn't valid JSON, often an HTML error page from `PerformHttpRequest`. |
| Nothing happens, no error | The event isn't registered as a net event, the handler name has a typo, or the code never runs. Add a print at the entry point. |

## Client debugging tools

- **F8 console commands**: `resmon 1` (resource CPU and memory), `netgraph` (network graph), `cl_drawfps true`, `profiler record` (see [Threads and performance](/docs/development/threads-performance)).
- **`nui_devtools`**: Chrome DevTools for NUI. Your JavaScript errors and `console.log` appear there.
- **Draw it**: draw a marker or text at the coordinates your code uses, to see where it thinks things are.
- **Coordinates**: print `GetEntityCoords(PlayerPedId())` and `GetEntityHeading(PlayerPedId())` to grab positions for configs, or pick them on the [Interactive Map](/tools/interactive-map).

## Server debugging tools

- The txAdmin **Live Console** with search, and the log files in `txData`.
- `status` lists players and their IDs.
- `mysql_debug` and `mysql_slow_query_warning` convars for oxmysql.
- The server **profiler** (`profiler record 500` in the server console, then `profiler saveJSON file.json`) for slow ticks. Drop the file into the [Profiler Analyzer](/tools/profiler-analyzer) to see which resources use the most time.
- txAdmin's performance chart for hitches over time.

## Debugging streamed assets

- Missing model or texture: check the file is in `stream/`, the name matches exactly (case matters on Linux), and the resource is started. The [Vehicle Pack Validator](/tools/vehicle-pack-validator) checks a vehicle resource for broken links between metas, stream files and the manifest.
- A `data_file` path that doesn't match a file listed in `files` is silently ignored.
- Oversized asset warnings in the server console point to textures that need shrinking.

More in [Streaming custom assets](/docs/development/streaming-assets).

## Tools that make debugging easier

- The Lua Language Server in VS Code flags undefined globals and wrong argument counts **before** you run the code. See [Start developing](/docs/development#2-visual-studio-code).
- Git: `git diff` shows exactly what changed since it last worked. `git stash` lets you test the old version in seconds.

## Asking for help

When you're stuck, a good question gets an answer fast:

- What you're trying to do, in one sentence.
- The exact error text (copied, not a phone photo of the screen).
- The relevant code, formatted, with line numbers matching the error.
- What you already tried.
- Artifact build, framework and version.

Post it on [forum.cfx.re](https://forum.cfx.re) in the Development category or in the framework's Discord support channel.

Next: [Streaming custom assets](/docs/development/streaming-assets).

_Last updated: 2026-09-22_

---

## Streaming custom assets

URL: https://fivemad.com/docs/development/streaming-assets

Add custom vehicles, clothing, props, maps, MLOs and sounds to FiveM: the stream folder, data_file entries, YDR, YFT, YTD, YMAP and YTYP files, naming rules and size limits.

"Streaming" means sending game assets (models, textures, maps, sounds) from your server to players and loading them into the game. In FiveM it is mostly automatic: put the files in a resource's `stream` folder, add the right `data_file` lines for metadata, and `ensure` the resource.

[FiveM Vehicle Development: Spawning FiveM ready, add-on and replace vehicles (Snowy Aura)](https://www.youtube.com/watch?v=XLfHruC_hv8) (YouTube video)

## The two halves of an asset

1. **Binary assets** go in `stream/`: `.yft` (vehicles and fragments), `.ydr` (props), `.ydd` (clothing and ped parts), `.ytd` (textures), `.ybn` (collisions), `.ymap` (placements), `.ytyp` (archetypes), `.ycd` (animations) and friends. Everything under `stream/`, including subfolders, is registered with the game automatically.
2. **Metadata** (`.meta` XML files like `vehicles.meta`) goes anywhere else in the resource, listed in `files` and registered with a `data_file` line. This tells the game what the new things **are**.

```text
my_asset_pack/
├─ fxmanifest.lua
├─ stream/           binary assets, auto streamed
│  ├─ mycar.yft
│  ├─ mycar_hi.yft
│  └─ mycar.ytd
└─ data/             metadata, registered with data_file
   ├─ vehicles.meta
   ├─ handling.meta
   ├─ carcols.meta
   └─ carvariations.meta
```

## Common data_file types

| data_file | File | For |
| --- | --- | --- |
| `VEHICLE_METADATA_FILE` | `vehicles.meta` | Vehicle definitions (model name, handling id, layout, class) |
| `HANDLING_FILE` | `handling.meta` | Driving physics |
| `CARCOLS_FILE` | `carcols.meta` | Mod kits, sirens, lights |
| `VEHICLE_VARIATION_FILE` | `carvariations.meta` | Colours, liveries, extras, kits per model |
| `VEHICLE_LAYOUTS_FILE` | `vehiclelayouts.meta` | Seat and entry animations (custom layouts) |
| `DLCTEXT_FILE` | `dlctext.meta` | Text labels |
| `SHOP_PED_APPAREL_META_FILE` | `<ped>_<collection>.meta` | Add-on clothing collections |
| `DLC_ITYP_REQUEST` | `*.ytyp` | Custom archetypes (props and MLOs) |
| `WEAPONINFO_FILE`, `WEAPON_ANIMATIONS_FILE`, `WEAPONCOMPONENTSINFO_FILE` | weapon metas | Add-on or edited weapons |
| `AUDIO_GAMEDATA`, `AUDIO_SOUNDDATA`, `AUDIO_SYNTHDATA`, `AUDIO_WAVEPACK` | audio `.rel` data and `.awc` folders | Custom sounds and engine audio |
| `TIMECYCLEMOD_FILE` | timecycle modifiers | Visual effects and interior lighting |

Every `data_file` path must also be in `files { }`, or clients never download it.

## Vehicles

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

files {
    'data/**/vehicles.meta',
    'data/**/handling.meta',
    'data/**/carcols.meta',
    'data/**/carvariations.meta',
}

data_file 'VEHICLE_METADATA_FILE' 'data/**/vehicles.meta'
data_file 'HANDLING_FILE' 'data/**/handling.meta'
data_file 'CARCOLS_FILE' 'data/**/carcols.meta'
data_file 'VEHICLE_VARIATION_FILE' 'data/**/carvariations.meta'

client_script 'names.lua'
```

```lua title="names.lua"
AddTextEntry('mycar', 'My Custom Car')   -- the name shown in game
```

Things that break vehicle packs:

- The `modelName` in `vehicles.meta` must match the `.yft` file name.
- The `handlingId` in `vehicles.meta` must exist in `handling.meta`.
- `kits` in `carvariations.meta` must reference a mod kit ID that exists in `carcols.meta`, and **mod kit IDs and siren IDs must be unique** across all your packs. Clashes make tuning parts or sirens show up on the wrong car.
- Duplicate model names across two packs: one silently wins.

The [Vehicle Pack Validator](/tools/vehicle-pack-validator) finds these broken links in a whole vehicle resource. The [Vehicle Handling Editor](/tools/vehicle-handling-editor) edits handling from a UI, and the [Vehicle Sirens Editor](/tools/vehicle-sirens) edits `carcols.meta` sirens and finds free or clashing siren IDs. Installation steps for server owners are in [Vehicle packs](/docs/resources/vehicle-packs).

## Clothing

There are two ways:

- **Replace** clothing: files named like the game's own (`jbib_003_u.ydd`) replace a base game item for everyone. Simple but destructive, and conflicts between packs are common.
- **Add-on** clothing (recommended): a new collection that adds new drawables on top of the base game.

An add-on clothing pack for the male freemode ped looks like this:

```text
my_clothes/
├─ fxmanifest.lua
├─ mp_m_freemode_01_mp_m_mypack.meta      collection metadata
└─ stream/
   ├─ mp_m_freemode_01_mp_m_mypack.ymt    ped variation data
   ├─ mp_m_freemode_01_mp_m_mypack^jbib_000_u.ydd
   └─ mp_m_freemode_01_mp_m_mypack^jbib_diff_000_a_uni.ytd
```

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

files { 'mp_m_freemode_01_mp_m_mypack.meta' }
data_file 'SHOP_PED_APPAREL_META_FILE' 'mp_m_freemode_01_mp_m_mypack.meta'
```

The file names encode the ped, the collection, the component (`jbib` = tops, `lowr` = legs, `feet`, `accs`, `hair`...), the drawable number and texture variants, and the `.ymt` must match the drawables exactly. Getting this right by hand is tedious, which is why most people use a tool: community tools like Durty Cloth Tool or grzyClothTool build whole packs, and the [YMT Creator](/tools/ymt-creator) generates the `.ymt` for a pack from its drawable and texture file names. Server owner steps are in [Maps, MLOs and clothing](/docs/resources/maps-mlos-clothing).

## Props

A custom prop needs:

- the model `.ydr` (and its `.ytd` if textures aren't embedded) and usually a `.ybn` collision,
- a `.ytyp` that defines the archetype (name, bounding box, LOD distance, textures),
- a `.ymap` if you want it placed in the world, or `CreateObject` from a script.

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

data_file 'DLC_ITYP_REQUEST' 'stream/my_props.ytyp'
```

Create the `.ytyp` with the [YTYP Creator](/tools/ytyp-creator), which calculates the bounds from your model's XML, and find base game props to reuse in the [Objects / Props List](/tools/objects-list).

## Maps (YMAP) and MLOs

- A `.ymap` places entities (props, buildings) with position, rotation and LOD distance. Drop it in `stream/` and it loads with the resource.
- Map resources traditionally add `this_is_a_map 'yes'` to the manifest.
- An **MLO** is an interior: a `.ytyp` with rooms, portals and entity sets, plus a `.ymap` that places it, plus models and collisions. Most MLO resources declare their `.ytyp` with `DLC_ITYP_REQUEST`.
- Many MLOs replace or edit parts of the base map, so two MLOs in the same spot conflict. Only use one per location.

Build simple placements with the [YMAP Builder](/tools/ymap-builder) (props by coordinates, with correct rotations, extents and LOD distances), or use CodeWalker for full map editing. The [Interactive Map](/tools/interactive-map) helps you find coordinates.

## Sounds

Custom sounds in FiveM use the game's native audio system: an `.awc` wave bank plus `.dat54.rel` data, registered with `AUDIO_WAVEPACK` and `AUDIO_SOUNDDATA` entries, then played with natives like `PlaySoundFromEntity`. The [Native Audio Builder](/tools/native-audio-builder) turns WAV, MP3 or OGG files into a ready resource (bank, data, `fxmanifest.lua` and Lua). For simple UI sounds, NUI audio (an `<audio>` tag in your page) is often enough.

## Textures

- `.ytd` files hold textures. Every texture uses video memory on every client that loads it.
- Most "texture loss" (blurry or missing textures when many players and cars are around) comes from oversized textures, typically 4K textures on add-on cars and clothes.
- Edit or replace textures inside a `.ytd` export with the [Texture Editor](/tools/texture-editor).

## Keep it light

FXServer prints a warning when an asset uses a lot of physical memory ("oversized assets can and WILL lead to streaming issues"). Take it seriously:

- **2048x2048 is the practical maximum** for most textures, 1024 or 512 for small parts. Nobody sees the difference on a door handle.
- Use DXT1 for textures without alpha, DXT5 or BC7 with alpha, and generate **mipmaps**.
- The [YTD Optimizer](/tools/ytd-optimizer) shrinks many `.ytd` files at once: caps texture size, picks compression, rebuilds mips and shows the memory saved.
- Keep proper LODs on your models, so far away objects are cheap to draw.
- Every MB you stream is downloaded by every player on first join. Remove packs nobody uses.

## Workflow summary

1. Get or make the asset (Blender with Sollumz for models, CodeWalker for maps, a clothing tool for clothes).
2. Put binaries in `stream/`, metas in `data/`.
3. Write the manifest (the [fxmanifest Generator](/tools/fxmanifest-generator) has a vehicle pack preset with all the `data_file` lines).
4. Validate, optimise textures.
5. `refresh`, `ensure`, test in game, check the server console for warnings.

The [video archive](/docs/videos) has full courses on streaming vehicles and clothing, CodeWalker and Blender with Sollumz.

Next: [Publishing a resource](/docs/development/publishing).

_Last updated: 2026-09-22_

---

## Publishing a FiveM resource

URL: https://fivemad.com/docs/development/publishing

Release your FiveM resource properly: structure, versioning, README, license, config, the forum.cfx.re release rules, and selling on Tebex with Cfx.re asset escrow.

A resource that works on your server is half done. A resource other people can install, configure and update without messaging you is a release. This page covers what to ship, how to version it, where to post it, and how selling works.

## Before you release

### Make it configurable

Put everything a server owner might change in a `config.lua` (shared) and, if needed, a `server/config.lua` for secrets like webhooks:

```lua title="config.lua"
Config = {}

Config.Locale = 'en'
Config.Debug = false

Config.Shops = {
    { label = 'Downtown 24/7', coords = vec3(25.7, -1347.3, 29.5), blip = true },
}
```

Nothing hard coded that someone else would need to change: coordinates, prices, job names, item names, keys.

### Support the common stacks, or say which you need

If your resource uses a framework, either put framework calls behind a bridge (see [Exports and dependencies](/docs/development/exports-dependencies#writing-framework-independent-resources)) or clearly state "Qbox only" or "ESX Legacy only". List every dependency in `fxmanifest.lua` so FXServer refuses to start with something missing.

### Clean up

- Remove debug prints, test commands and your own server's paths.
- No secrets in the files: webhook URLs, API keys, license keys.
- Remove unused files and assets.
- Run it on a **clean** test server (fresh recipe deploy) to make sure it doesn't depend on something only your server has.
- Check performance: `resmon` idle should be near `0.00 ms`. See [Threads and performance](/docs/development/threads-performance).
- Streamed assets: textures at sensible sizes (the forum asks you to state file sizes, polygon counts and texture sizes for models).

### Ship built files

If your UI uses React, Vue or similar, include the **built** `web/build` folder in the release zip. Server owners shouldn't need Node.js to install your resource. Keep the source in the repository for people who want to change it.

## Repository layout

```text
my_resource/
├─ fxmanifest.lua
├─ config.lua
├─ client/
├─ server/
├─ locales/
├─ web/            (source) + web/build (built UI, in releases)
├─ install/        SQL files, item definitions for each framework
├─ README.md
├─ LICENSE
└─ CHANGELOG.md
```

## Versioning

Use [semantic versioning](https://semver.org/): `MAJOR.MINOR.PATCH`.

- **PATCH** (1.2.3 to 1.2.4): bug fixes, no config changes.
- **MINOR** (1.2.4 to 1.3.0): new features, old configs still work.
- **MAJOR** (1.3.0 to 2.0.0): breaking changes (config format, database schema, events renamed).

Put the version in `fxmanifest.lua` (`version '1.3.0'`), tag the release in git (`v1.3.0`), and write what changed in `CHANGELOG.md` and the GitHub release notes. If the database schema changes, ship a migration SQL file and say so loudly.

A simple version check on start helps users know an update exists. Many resources compare `GetResourceMetadata(GetCurrentResourceName(), 'version', 0)` with the latest GitHub release via `PerformHttpRequest`. Keep it to one request on start, and let owners turn it off.

## The README

A good README answers, in this order:

1. **What it does**, in two sentences, with a screenshot or a short video.
2. **Requirements**: artifact build, game build, OneSync, framework, dependencies with links.
3. **Installation**: exact steps. Where to put the folder, `ensure` order, SQL to import, items to add, convars to set.
4. **Configuration**: what the main config options do.
5. **Exports and events** other developers can use.
6. **Support**: where to report bugs (GitHub issues is best).
7. **License**.

The [Script Thumbnail Creator](/tools/script-thumbnail-creator) turns your screenshots into release thumbnails for the forum, YouTube, Discord and Tebex in every size at once.

## Pick a license

Without a license, nobody legally may use or change your code. Common choices in the FiveM world:

| License | In short |
| --- | --- |
| **MIT** | Do anything, keep the copyright notice. Used by txAdmin, pma-voice, bob74_ipl. |
| **GPL-3.0** | Changes that are distributed must stay open under GPL. Used by QBCore and ox_inventory. |
| **LGPL-3.0** | Like GPL for the library itself, but it can be used by other code with fewer obligations. Used by ox_lib and oxmysql. |
| **Custom / all rights reserved** | Usual for paid resources. |

Respect the licenses of what **you** use: if you fork a GPL resource and distribute it, your version is GPL too. Don't sell someone else's free work.

## Releasing on forum.cfx.re

The Releases category on [forum.cfx.re](https://forum.cfx.re) is where most server owners look. Read the pinned [Releases Rules and FAQ](https://forum.cfx.re/t/releases-rules-and-faq/240725) before posting. Key points from it:

- Tag the post **free** or **paid**, and **escrow** if the resource uses asset escrow.
- **Free** resources must be available through a public git repository, a direct forum upload, or a free Tebex package with escrow.
- **Paid** resources must be sold **only through Tebex** with Cfx.re's asset delivery system.
- List the features, show them (a demonstration video is preferred over screenshots), and for models and maps give sizes, polygon counts, textures and LOD details. Paid and escrowed releases use a small table: code accessible, subscription based, approximate lines, requirements, support.
- **Not allowed**: requiring users to join a Discord, enter license tokens or register accounts to get or run the resource; third party encryption or obfuscation; remote code execution; IP infringement ("de-badging does not make your asset compliant"); resource packs and huge asset packs; deprecated code patterns like `GetPlayerPed(-1)`.
- Don't paste AI output as your description.
- You need forum trust level 1, and you can post one release every 48 hours. The first image must be uploaded to the forum so it shows as the preview.

## Selling on Tebex with asset escrow

Cfx.re partners with **Tebex** for selling resources. The flow:

1. Create a Tebex store and link it to your Cfx.re account through the Cfx.re Portal.
2. Upload your resource to Cfx.re's **asset escrow** system. Files you list under `escrow_ignore` in the manifest stay readable, everything else is encrypted:

```lua title="fxmanifest.lua"
escrow_ignore {
    'config.lua',
    'locales/*.lua',
    'client/open.lua',
    'server/open.lua',
}
```

3. Create a Tebex package that delivers that asset.
4. Buyers get the resource tied to their Cfx.re account and download it from the Cfx.re Portal. It only runs on servers whose license key belongs to that account.

Good practice for paid resources:

- Leave config, locales and framework bridge files open so buyers can adapt them.
- Say clearly what's open and what's escrowed.
- Offer support through a proper channel (the forum rules say you can't **require** Discord to get or run the resource).
- Follow the platform rules: no selling Rockstar's content or other people's IP. See [Requirements](/docs/getting-started/requirements#the-rules-you-agree-to).

> [!NOTE]
> At the early access launch of FiveM for GTA V Enhanced, asset escrow was not yet implemented on that platform. If you target Enhanced, check the current Cfx.re docs before promising escrowed releases there.

## After release

- Answer issues, tag fixes as PATCH releases, keep a changelog.
- Test on new recommended artifacts and new game builds. Check our [Artifacts page](/artifacts) now and then.
- When you stop maintaining it, say so in the README (and archive the repository), so people don't wait for fixes.

_Last updated: 2026-09-22_

---


# Resources

## Installing and ordering resources

URL: https://fivemad.com/docs/resources

How to install FiveM resources: where the folder goes, ensure vs start, category folders, load order, dependencies, SQL and items, updating, and what to check first.

A **resource** is any folder with an `fxmanifest.lua`: a script, a map, a car pack, a loading screen. Installing one takes a minute once you know the pattern. Most "it doesn't work" reports come from the same five mistakes, listed at the end.

## The install pattern

1. **Download** the resource. From GitHub, use the **Releases** page and download the release zip (not "Code > Download ZIP") when the project publishes releases: releases contain built files like compiled UIs.
2. **Extract** it into your server's `resources` folder, usually into a category folder like `resources/[standalone]` or `resources/[local]`.
3. **Check the folder**: the `fxmanifest.lua` must be directly inside it. Rename the folder if needed (remove `-main`, `-master` or version suffixes, unless the README says the name must stay).
4. **Read the README**: dependencies, SQL files, items, convars, required folder name.
5. **Import SQL** if there is any (HeidiSQL: select your database, File > Run SQL file).
6. **Add it to `server.cfg`** with `ensure name`, after its dependencies.
7. **Start it** without a full restart: `refresh`, then `ensure name` in the live console.
8. **Check** the server console and F8 for errors.

## ensure, start, stop, restart

| Command | Effect |
| --- | --- |
| `ensure name` | Start if stopped, restart if running. Use this in `server.cfg`. |
| `start name` | Start if stopped. Does nothing if running. |
| `stop name` | Stop it. |
| `restart name` | Restart if running. |
| `refresh` | Rescan the resources folder for new or changed manifests. |
| `ensure [folder]` | Start every resource in a category folder. |

`ensure` is what you want in `server.cfg`. The name is always the **folder name**, never what the manifest or README title says.

## Category folders

Folders in square brackets are **categories**, not resources:

```text
resources/
├─ [cfx-default]/     mapmanager, spawnmanager, chat...
├─ [ox]/              oxmysql, ox_lib, ox_target, ox_inventory
├─ [framework]/       qbx_core or qb-core or es_extended...
├─ [standalone]/      pma-voice, bob74_ipl...
├─ [maps]/            MLOs and ymaps
├─ [cars]/            vehicle packs
└─ [local]/           your own resources
```

They're just for tidiness, and they let you start a group with one line. Categories can be nested (`[cars]/[police]/`). Don't put a resource and its category at the same level with the same name.

## Load order

Resources start in the order of the `ensure` lines. A good general order:

```cfg title="server.cfg"
# 1. Cfx defaults
ensure mapmanager
ensure chat
ensure spawnmanager

# 2. Database and core libraries
ensure oxmysql
ensure ox_lib

# 3. Framework core
ensure qbx_core            # or qb-core / es_extended

# 4. Libraries that depend on the framework
ensure ox_target
ensure ox_inventory

# 5. Framework resources and everything else
ensure [qbx]
ensure [standalone]
ensure [maps]
ensure [cars]

# 6. Your own
ensure [local]
```

If a resource declares `dependencies` in its manifest, FXServer starts them first automatically and refuses to start the resource if one is missing. That's the safety net, not a reason to skip a sensible order. More in [Exports and dependencies](/docs/development/exports-dependencies#dependencies).

> [!TIP]
> Big servers keep the resource list in a separate `resources.cfg` and `exec resources.cfg` from `server.cfg`. The [server.cfg Generator](/tools/server-cfg-generator) can lay out the resource section for you.

## Framework resources

Resources written for a framework need extra steps, usually in the README:

- **Items**: add them to the inventory's item list (`ox_inventory/data/items.lua`, `qb-core/shared/items.lua`, or the ESX `items` table) and put the item images in the inventory's image folder. The [Inventory Icons](/tools/inventory-icons) tool makes transparent item icons and the matching `items.lua` entries.
- **Jobs**: add the job to the framework's job list. See the framework quick starts: [QBCore](/docs/frameworks/qbcore), [Qbox](/docs/frameworks/qbox), [ESX](/docs/frameworks/esx).
- **SQL**: import the tables.
- **Config**: pick the framework, target system (ox_target, qb-target), inventory and notification system in the resource's `config.lua`.

## Updating a resource

1. Read the changelog for breaking changes and SQL migrations.
2. Back up the old folder (and the database if there's a migration).
3. Replace the files, but **keep your config** (copy `config.lua` back, or merge new options into it).
4. Run migration SQL if any.
5. `ensure name` or restart the server.

Keeping your server folder in git makes this much safer: you see exactly what changed and can roll back.

## The five classic mistakes

1. **Nested folder**: `[local]/mycar/mycar/fxmanifest.lua`. The manifest must be one level down.
2. **Wrong name**: `ensure mycar` for a folder called `mycar-main`, or case differences on Linux.
3. **Missing dependency**: the README said ox_lib, you don't have it, or it starts after.
4. **SQL not imported**: `Table 'x' doesn't exist` in the console.
5. **Source zip instead of release**: the UI is blank or shows a message that it isn't built, because the built files are missing. Download the release.

## Where to find resources

- [Recommended open source resources](/docs/resources/recommended): the well known basics.
- [forum.cfx.re Releases](https://forum.cfx.re): free and paid, with the rules that releases must follow.
- GitHub organisations of the frameworks: [overextended](https://github.com/overextended), [Qbox-project](https://github.com/Qbox-project), [qbcore-framework](https://github.com/qbcore-framework), [esx-framework](https://github.com/esx-framework).

Avoid "leaks" sites and packs of hundreds of resources from unknown sources. See [Security basics](/docs/server-setup/security#6-what-you-install).

## Pages in this section

- [Recommended open source resources](/docs/resources/recommended)
- [Maps, MLOs and clothing packs](/docs/resources/maps-mlos-clothing)
- [Vehicle packs](/docs/resources/vehicle-packs)

_Last updated: 2026-09-22_

---

## Recommended open source resources

URL: https://fivemad.com/docs/resources/recommended

Well known, maintained open source FiveM resources: oxmysql, ox_lib, ox_target, ox_inventory, pma-voice, vMenu, bob74_ipl, screencapture and more, with install notes.

These are the building blocks most servers use, all open source and maintained on GitHub. The list is deliberately short: well known projects with public code, used by the official txAdmin recipes or by thousands of servers. Repository activity was checked in September 2026.

## The Overextended (ox) stack

[Overextended](https://github.com/overextended) maintains a set of libraries and systems that the Qbox framework is built on and that work with QBCore, ESX and standalone servers. Documentation is at [overextended.dev](https://overextended.dev/).

> [!IMPORTANT]
> Always download ox resources from their **Releases** page (`releases/latest/download/<name>.zip`). The repositories contain source code with web UIs that must be built first. The release zips are ready to use.

### oxmysql

The database connector almost every framework uses. Supports the old `mysql-async` and `ghmattimysql` syntax, promises and async queries, named and unnamed placeholders. License LGPL-3.0.

- Repo: [overextended/oxmysql](https://github.com/overextended/oxmysql)
- Needs: MariaDB (recommended over MySQL 8), `set mysql_connection_string "..."` before `ensure oxmysql`.
- Setup: [Database setup](/docs/server-setup/database#connect-with-oxmysql).

### ox_lib

A shared library of UI and utilities: notifications, progress bars and circles, context menus, input dialogs, alert dialogs, radial menus, text UI, skill checks, callbacks (`lib.callback`), points and zones, a player `cache`, locale handling, and helpers for loading models and animations. License LGPL-3.0.

- Repo: [overextended/ox_lib](https://github.com/overextended/ox_lib)
- Use in a resource: `shared_script '@ox_lib/init.lua'` in the manifest, and `ensure ox_lib` before resources that use it.

```lua
lib.notify({ title = 'Garage', description = 'Vehicle stored', type = 'success' })

if lib.progressBar({ duration = 3000, label = 'Repairing', canCancel = true }) then
    -- finished
end
```

### ox_target

"Third eye" targeting: hold a key, aim at an entity, model or zone, pick an option. Replaces loops that check distances and show "Press E" prompts. License MIT.

- Repo: [overextended/ox_target](https://github.com/overextended/ox_target)
- Has compatibility with the qb-target export API for older resources.

### ox_inventory

A slot based inventory with weight, stashes, shops, crafting, weapon handling, item metadata and drops. Supports Qbox (default), ESX and ox_core. License GPL-3.0.

- Repo: [overextended/ox_inventory](https://github.com/overextended/ox_inventory)
- Items are defined in `ox_inventory/data/items.lua`, images go in `ox_inventory/web/images`. The [Inventory Icons](/tools/inventory-icons) tool makes transparent item images and the matching `items.lua` lines.

### ox_doorlock and ox_fuel

- [ox_doorlock](https://github.com/overextended/ox_doorlock): door locks you can create in game, with job and item access. GPL-3.0.
- [ox_fuel](https://github.com/overextended/ox_fuel): a simple fuel system built for ox_inventory. GPL-3.0.

## Voice

### pma-voice

Proximity voice using FiveM's built in Mumble server, with radio and phone call channels. The voice system used by the QBCore, Qbox and ESX recipes. License MIT.

- Repo: [AvarianKnight/pma-voice](https://github.com/AvarianKnight/pma-voice)
- Config is done with convars in `server.cfg`:

```cfg title="server.cfg"
setr voice_useNativeAudio true        # 3D sound with game effects (needed for submixes)
setr voice_useSendingRangeOnly true   # only hear people in range, stops mumble trolling
ensure pma-voice
```

Use only one of the audio modes (native, 2D or 3D). pma-voice isn't compatible with other voice systems, including vMenu's voice chat: disable that one. Players change their proximity range with <kbd>F11</kbd> by default.

## Admin and freeroam

### vMenu

A server side trainer menu by Tom Grobbe (Vespura): vehicle spawner and tuning, weather and time, player appearance, weapons, noclip, teleports, saved outfits and vehicles, all behind a permissions file. Written in C#. It's the standard for freeroam, car meet and photography servers, and a handy admin tool on dev servers.

- Repo: [TomGrobbe/vMenu](https://github.com/TomGrobbe/vMenu), docs at [docs.vespura.com/vmenu](https://docs.vespura.com/vmenu/) (separate pages for Legacy and Enhanced).

Installation, following the official docs:

1. Download `vMenu-<version>.zip` from the GitHub **Releases** page. Make sure your artifacts are up to date.
2. Extract everything into `resources/vMenu/` so the manifest is at `resources/vMenu/fxmanifest.lua`. The folder **must** be called `vMenu`, case sensitive.
3. Edit `resources/vMenu/config/permissions.cfg` to choose who gets what.
4. In `server.cfg`, execute the permissions **before** starting vMenu:

```cfg title="server.cfg"
exec @vMenu/config/permissions.cfg
ensure vMenu
```

When you update, replace all files **except** `permissions.cfg` and the rest of `vMenu/config/`.

[How to install vMenu into a FiveM Server! 2026 Updated (HighwayTrooper)](https://www.youtube.com/watch?v=4Qv_3NBYcWo) (YouTube video)

### txAdmin

Already built into FXServer, with an in-game menu (`/tx`). See [txAdmin](/docs/txadmin).

## World and interiors

### bob74_ipl

Loads and configures GTA Online's interiors (apartments, offices, clubhouses, bunkers, nightclubs and more) and the IPLs (map pieces) the base game hides in multiplayer. Without it, many online interiors are empty or have holes. Used by all the framework recipes. License MIT.

- Repo: [Bob74/bob74_ipl](https://github.com/Bob74/bob74_ipl)
- Start it early, before MLOs that edit the same areas.

## Utilities

### screencapture

Screenshots and short video capture from the game, for phones, report systems and anticheats. It describes itself as a successor to the older `screenshot-basic`. License AGPL-3.0.

- Repo: [itschip/screencapture](https://github.com/itschip/screencapture) (download the release zip).
- The original [citizenfx/screenshot-basic](https://github.com/citizenfx/screenshot-basic) still exists but hasn't been updated since 2023.

### PolyZone

Defines zones (boxes, circles, polygons) and tells you when a player enters or leaves. Many older QBCore resources depend on it. For new code, ox_lib's `lib.zones` does the same job. License MIT.

- Repo: [mkafrin/PolyZone](https://github.com/mkafrin/PolyZone)

### scully_emotemenu

An emote and walk style menu used by the Qbox recipe. License GPL-3.0.

- Repo: [Scullyy/scully_emotemenu](https://github.com/Scullyy/scully_emotemenu)

### A loading screen

The Qbox recipe uses [D4isDAVID/loadscreen](https://github.com/D4isDAVID/loadscreen), a configurable loading screen (MIT). Or write your own, it's a simple NUI page: see [NUI basics](/docs/development/nui#loading-screens).

## Phones and bigger systems

- [npwd](https://github.com/project-error/npwd) by Project Error: an open source phone with apps, used by the Qbox recipe.
- Framework specific systems (garages, jobs, housing) come with the framework recipes. See [Popular recipes](/docs/txadmin/popular-recipes).

## A starter set by server type

| Server | Start with |
| --- | --- |
| Freeroam / car meets | Basic Server recipe, vMenu, pma-voice, bob74_ipl |
| Custom game mode | Basic Server recipe, oxmysql, ox_lib, bob74_ipl, then your own code |
| Roleplay | A framework recipe (Qbox, QBCore or ESX), which already includes most of the above |

## Before you add anything

- Is it maintained? Look at the last commit and open issues.
- Does it support your framework and artifact?
- Is the code readable? Obfuscated "free" resources are a red flag.
- Does it duplicate something you already have (two inventories, two target systems, two voice resources)? Pick one.

_Last updated: 2026-09-22_

---

## Installing maps, MLOs and clothing packs

URL: https://fivemad.com/docs/resources/maps-mlos-clothing

Install custom maps, MLO interiors and clothing packs on a FiveM server: folder layout, manifests, conflicts, game builds, add-on vs replace clothing and texture sizes.

Maps and clothing are "asset" resources: mostly files in a `stream` folder plus a manifest. They're easy to install and easy to get wrong in subtle ways (conflicts, texture loss, wrong game build). This page is for server owners. If you make these assets, see [Streaming custom assets](/docs/development/streaming-assets).

[How To Install Custom Clothing into a FiveM Server For FREE! 2026 (HighwayTrooper)](https://www.youtube.com/watch?v=KmX1CtAMcsQ) (YouTube video)

## Maps and MLOs

A **map** resource adds or changes things in the world (`.ymap` placements, models, collisions). An **MLO** is an interior with rooms, like a custom police station or a shop you can walk into.

### Install

1. Extract the resource into `resources/[maps]/`. Check `fxmanifest.lua` is directly inside the resource folder.
2. Read the README: some MLOs need a specific **game build**, another resource (often `bob74_ipl`), or tell you to remove something that conflicts.
3. Add it to `server.cfg` **after** `bob74_ipl`:

```cfg title="server.cfg"
ensure bob74_ipl
ensure [maps]
```

4. `refresh` and `ensure` it, or restart. Players download it on their next join.
5. Fly to the location and check: walls, floors, collisions (can you fall through?), doors, lighting.

A typical map resource manifest:

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'
this_is_a_map 'yes'

data_file 'DLC_ITYP_REQUEST' 'stream/my_mlo.ytyp'
```

If a map comes as a singleplayer mod (`dlc.rpf`), it isn't FiveM ready: the files must be extracted into a `stream` folder and the metadata turned into `data_file` lines.

### Conflicts

- **Two MLOs in the same place** fight each other: flickering walls, missing floors, invisible interiors. Only use one per location.
- Many MLOs **remove or replace** base map pieces around them. Two such maps next to each other can remove each other's surroundings.
- **bob74_ipl** loads online interiors that some MLOs replace (for example some apartments and clubhouses). The MLO's README usually says what to disable in `bob74_ipl`'s config.
- Map packs that edit the same `.ymap` as another pack: the last one started wins.

### Game builds

Newer MLOs may use props from recent DLCs. If your `sv_enforceGameBuild` is older than what the MLO needs, you'll see missing props or empty spots. Check the README and your build (see [server.cfg explained](/docs/server-setup/server-cfg#sv_enforcegamebuild)).

### Placing props yourself

For simple additions (benches, barriers, a few decorations), you don't need a full map editor. The [YMAP Builder](/tools/ymap-builder) builds a `.ymap` from props placed by coordinates, and the [Objects / Props List](/tools/objects-list) helps you find the right model with pictures and sizes. Find coordinates on the [Interactive Map](/tools/interactive-map).

## Clothing

### Add-on vs replace

| Type | What it does | Use it? |
| --- | --- | --- |
| **Add-on** | Adds new drawables on top of the base game, as a new collection with its own `.ymt` and `.meta`. | Yes. Packs don't break each other or base clothes. |
| **Replace** | Overwrites a base game item (same file name as the original). | Avoid. Players lose the original item and packs overwrite each other. |

Most modern packs (and EUP conversions for FiveM) are add-on.

### Install

1. Extract into `resources/[clothing]/`.
2. Check the resource has a `.meta` file registered in the manifest and the `.ymt` and drawables in `stream`:

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

files { 'mp_m_freemode_01_mp_m_mypack.meta' }
data_file 'SHOP_PED_APPAREL_META_FILE' 'mp_m_freemode_01_mp_m_mypack.meta'
```

3. `ensure` it **before** your clothing menu resource (illenium-appearance, qb-clothing, esx_skin...), so the menu sees the new items.
4. Test with both male and female freemode peds if the pack has both.

### How players see new clothes

The clothing menu shows new drawables at the **end** of each category. If you install several packs, their numbers shift when you add or remove a pack before them, which changes what saved outfits point to. Decide your packs early and add new ones at the end of the `ensure` list.

### Making or merging packs

Merging many small packs into one is common on RP servers to control numbering. Community tools like Durty Cloth Tool and grzyClothTool build and merge packs, and the [YMT Creator](/tools/ymt-creator) generates the ped variation `.ymt` for a pack from its drawable and texture file names. For textures, the [Clothing Designer](/tools/clothing-designer) paints on a clothing model and exports new `.ytd` textures.

## Texture sizes (the big one)

Clothing and map packs are the most common cause of **texture loss**: blurry roads, missing textures, invisible objects when many players are around. The reason is almost always oversized textures (4K where 1K would do).

- Watch the server console for oversized asset warnings when the resource starts.
- Shrink `.ytd` textures to 2048 or less, with mipmaps. The [YTD Optimizer](/tools/ytd-optimizer) does it in bulk and shows the memory you save.
- Fewer, well made packs beat many heavy ones.

## Checklist

- [ ] Manifest directly inside the resource folder.
- [ ] `ensure` after `bob74_ipl` (maps) or before the clothing menu (clothes).
- [ ] No two MLOs in the same place.
- [ ] Game build matches what the asset needs.
- [ ] No oversized asset warnings, or you shrank the textures.
- [ ] Tested in game with a fresh client cache if something looks wrong.

_Last updated: 2026-09-22_

---

## Installing vehicle packs

URL: https://fivemad.com/docs/resources/vehicle-packs

Add custom cars to a FiveM server: FiveM ready vs singleplayer add-ons, folder layout, data_file lines, vehicle names, framework shops, ID clashes and textures.

Custom vehicles are one of the most requested additions to any server, and one of the most common causes of problems when done carelessly. This page shows the clean way to install them.

[How to Install CUSTOM CARS into your FiveM Server (TraseDev)](https://www.youtube.com/watch?v=3kd978TV56Q) (YouTube video)

## FiveM ready or not?

- **FiveM ready** vehicles come as a resource: a folder with `fxmanifest.lua`, a `stream` folder and meta files. Drop in and `ensure`.
- **Singleplayer add-on** vehicles come as a `dlc.rpf` for GTA V mods. They need converting: open the RPF with a tool like OpenIV or CodeWalker, copy the `.yft`/`.ytd` files into `stream/` and the `.meta` files into `data/`, then write a manifest. It's the same result as a FiveM ready pack, just done by you.
- **Replace** vehicles overwrite a base game car. Avoid them on multiplayer servers: they remove a vanilla car for everyone.

## Folder layout

One resource per car, or a pack with one subfolder per car:

```text
[cars]/
└─ my_cars/
   ├─ fxmanifest.lua
   ├─ names.lua
   ├─ stream/
   │  ├─ car1/  car1.yft  car1_hi.yft  car1.ytd
   │  └─ car2/  car2.yft  car2_hi.yft  car2.ytd  car2+hi.ytd
   └─ data/
      ├─ car1/  vehicles.meta  handling.meta  carvariations.meta  carcols.meta
      └─ car2/  vehicles.meta  handling.meta  carvariations.meta
```

## The manifest

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

description 'My vehicle pack'
version '1.0.0'

files {
    'data/**/vehicles.meta',
    'data/**/handling.meta',
    'data/**/carvariations.meta',
    'data/**/carcols.meta',
    'data/**/vehiclelayouts.meta',
}

data_file 'HANDLING_FILE' 'data/**/handling.meta'
data_file 'VEHICLE_METADATA_FILE' 'data/**/vehicles.meta'
data_file 'CARCOLS_FILE' 'data/**/carcols.meta'
data_file 'VEHICLE_VARIATION_FILE' 'data/**/carvariations.meta'
data_file 'VEHICLE_LAYOUTS_FILE' 'data/**/vehiclelayouts.meta'

client_script 'names.lua'
```

The `**` glob matches every car folder, so you don't need a line per car. Leave out types a pack doesn't have. The [fxmanifest Generator](/tools/fxmanifest-generator) has a "Vehicle pack" preset that writes this for you.

```lua title="names.lua"
AddTextEntry('car1', 'Vapid Example GT')
AddTextEntry('car2', 'Bravado Sample')
```

The key is the `gameName` from `vehicles.meta` (usually the model name). Without it, the car shows as `NULL` in menus and garages.

## Install and test

1. Put the pack in `resources/[cars]/` and add `ensure my_cars` (or `ensure [cars]`) to `server.cfg`.
2. `refresh` and `ensure my_cars`, or restart.
3. Spawn the car by its model name (vMenu, txAdmin's menu, `/car` from [your first resource](/docs/development/first-resource), or your framework's admin command).
4. Check: model and textures load, handling feels right, doors and seats work, tuning parts appear, lights and sirens (for emergency vehicles) work.

## Adding it to your framework

Spawning works right away, but players can only buy and store it once the framework knows about it:

- **QBCore**: add the vehicle to `qb-core/shared/vehicles.lua` (model, name, brand, price, category, shop).
- **Qbox**: add it to `qbx_core/shared/vehicles.lua`, and to the vehicle shop's config if needed.
- **ESX**: add it to the `vehicles` table (and category) used by `esx_vehicleshop`.

Follow your framework's vehicle file format exactly: copy an existing entry and change the values.

## Things that go wrong

| Problem | Cause |
| --- | --- |
| Car spawns invisible or doesn't spawn | The `.yft` name doesn't match `modelName` in `vehicles.meta`, or the meta isn't registered (`data_file` path not in `files`). |
| Car drives like a default car | `handlingId` in `vehicles.meta` doesn't match `handlingName` in `handling.meta`, or `HANDLING_FILE` isn't registered. |
| Tuning parts from another car appear, or none at all | **Mod kit ID clash**: two packs use the same kit ID in `carcols.meta`. IDs must be unique across the whole server. |
| Wrong siren pattern or lights | **Siren ID clash** in `carcols.meta`. Find free IDs with the [Vehicle Sirens Editor](/tools/vehicle-sirens). |
| Two cars with the same name | Duplicate `modelName` in two packs. One silently wins. |
| Blurry textures, texture loss around the city | Oversized `.ytd` files. See below. |
| Name shows `NULL` | Missing `AddTextEntry` or text label. |

The [Vehicle Pack Validator](/tools/vehicle-pack-validator) reads a whole vehicle resource and lists every broken link between its metas, stream files and manifest: missing handling IDs, kit references, model names and `data_file` paths. Run it before you install a pack you didn't make.

## Keep packs light

Vehicles are the biggest streaming load on most servers.

- Keep textures at 2048 or less (1024 for most parts), compressed, with mipmaps. 4K liveries and interiors cause texture loss for everyone. The [YTD Optimizer](/tools/ytd-optimizer) shrinks many `.ytd` files at once and shows the memory saved.
- Watch the server console for oversized asset warnings when the pack starts.
- Don't stream 300 cars nobody drives. Every car is downloaded by every player.
- Prefer quality packs made for FiveM over raw singleplayer ports with huge polygon counts.

## Tuning and handling

- Edit handling from a UI with the [Vehicle Handling Editor](/tools/vehicle-handling-editor) and export `handling.meta`.
- Look up base game vehicles, their spawn names and hashes in the [Model & Hash Browser](/tools/model-hash-browser).

## Legal note

Many "real car" packs are models of real brands, and some are ripped from other games. Selling access to them, or to Rockstar's own vehicles, breaks the platform rules. Free use on your server is common practice, but know the risk. See [Requirements: the rules](/docs/getting-started/requirements#the-rules-you-agree-to).

_Last updated: 2026-09-22_

---


# Frameworks

## Frameworks compared: QBCore, Qbox, ESX and more

URL: https://fivemad.com/docs/frameworks

Do you need a FiveM framework? An honest comparison of QBCore, Qbox, ESX Legacy, ox_core, ND Core and vRP: what each gives you, pros, cons, and how to choose.

A **framework** is the shared base of a roleplay style server: player accounts and characters, money, jobs and grades, items and inventory, vehicles and garages, and a standard API that other resources build on. Picking one is the biggest technical decision you'll make for an RP server, because most scripts you buy or write will be tied to it.

[FiveM Frameworks Explained: ESX vs QBCore vs QBox (All Things Hosting)](https://www.youtube.com/watch?v=r0j0Ppn-G0o) (YouTube video)

## Do you need one?

**No framework (standalone)** if you run freeroam, racing, drifting, car meets, a minigame or a custom game mode. The Basic Server recipe plus vMenu, ox_lib and your own scripts is lighter, simpler and easier to reason about.

**A framework** if you want roleplay: characters, jobs, an economy, inventories, housing, and the thousands of community resources that expect one.

## The main frameworks

| | QBCore | Qbox | ESX Legacy | ox_core | ND Core | vRP |
| --- | --- | --- | --- | --- | --- | --- |
| **Repo** | [qbcore-framework](https://github.com/qbcore-framework) | [Qbox-project](https://github.com/Qbox-project) | [esx-framework](https://github.com/esx-framework) | [overextended/ox_core](https://github.com/overextended/ox_core) | [ND-Framework](https://github.com/ND-Framework/ND_Core) | [vRP-framework/vRP](https://github.com/vRP-framework/vRP) |
| **Docs** | [qbcore.org/docs](https://qbcore.org/docs) | [docs.qbox.re](https://docs.qbox.re) | [docs.esx-framework.org](https://docs.esx-framework.org) | [overextended.dev](https://overextended.dev) | Repo README | Repo README |
| **txAdmin recipe** | Yes (listed) | Yes (listed) | Yes (listed) | No | No | No |
| **Inventory** | qb-inventory (ox_inventory optional) | ox_inventory | ESX inventory, ox_inventory optional | ox_inventory | ox_inventory | Built in |
| **Script ecosystem** | Largest | QBCore compatible (bridge) plus its own | Very large, oldest | Small, dev focused | Small | Small today |
| **License** | GPL-3.0 (qb-core) | See repos | See repos | LGPL-3.0 | GPL-3.0 | MIT |
| **Best for** | Most available scripts, lots of tutorials | New RP servers wanting modern, maintained code | Teams who know ESX, huge script catalogue | Developers building their own game mode | Lightweight custom RP | Legacy servers |

## Honest pros and cons

### QBCore

- **Pros**: the biggest pool of free and paid scripts, most YouTube tutorials target it, a complete recipe with ~60 resources, easy to start.
- **Cons**: many resources are older and vary in quality and performance; lots of servers run heavily modified forks, so "QBCore compatible" doesn't always mean drop in; the default recipe is big, so you'll spend time removing what you don't need.

### Qbox

- **Pros**: started as a QBCore fork and is now its own framework built on the ox stack (ox_lib, ox_inventory, ox_target); a `qb-core` compatibility bridge (`qbx:enableBridge`) lets many QBCore resources run; active maintenance and code review; good docs.
- **Cons**: requires MariaDB 10.9+ and the ox stack (no qb-inventory); some older QBCore scripts need small changes; smaller community than QBCore or ESX.

### ESX Legacy

- **Pros**: the oldest big framework, huge catalogue of scripts, the recipe is official and maintained by the ESX team, many experienced developers know it.
- **Cons**: years of different ESX versions (v1 final, 1.2, Legacy) mean old tutorials and scripts often don't match Legacy; older addons can be slow; the style differs a lot from QB-based code.

### ox_core

- **Pros**: clean, modern, by the Overextended team, TypeScript and Lua, made to be extended.
- **Cons**: not a batteries included RP server: few ready jobs, you build more yourself. Best for developers.

### ND Core

- **Pros**: lightweight, works with ox_inventory, readable code.
- **Cons**: small community and ecosystem.

### vRP

- **Pros**: one of the earliest frameworks, some servers still run it.
- **Cons**: few new resources target it today, and knowledge is scattered. Not recommended for a new server.

## How to choose

1. **Is it roleplay?** If not, go standalone.
2. **Does your team already know one?** Use it. Experience beats a "better" framework.
3. **Starting fresh?** Deploy **Qbox** and **ESX Legacy** (and QBCore if you like) on a dev machine with txAdmin, play each for an evening, and read some of their code.
4. **Check the scripts you want.** If the paid scripts you plan to buy only support one framework, that decides it. Most big script stores support all three main ones.
5. **Think about performance and maintenance**: fewer, well written resources beat a huge pack.

> [!WARNING]
> Switching frameworks later means migrating the database and rewriting or replacing most scripts. Choose before you have players.

## What every framework gives you

Whichever you pick, you'll work with the same concepts:

| Concept | QBCore | Qbox | ESX |
| --- | --- | --- | --- |
| Get the core | `exports['qb-core']:GetCoreObject()` | `exports.qbx_core:...` exports, or `@qbx_core/modules/lib.lua` | `exports['es_extended']:getSharedObject()` or `@es_extended/imports.lua` |
| Get a player (server) | `QBCore.Functions.GetPlayer(src)` | `exports.qbx_core:GetPlayer(src)` | `ESX.GetPlayerFromId(src)` |
| Add money | `Player.Functions.AddMoney('cash', 100)` | `exports.qbx_core:AddMoney(src, 'cash', 100)` | `xPlayer.addMoney(100)` |
| Jobs defined in | `qb-core/shared/jobs.lua` | `qbx_core/shared/jobs.lua` | Database tables `jobs` and `job_grades` |
| Items defined in | `qb-core/shared/items.lua` | `ox_inventory/data/items.lua` | Database table `items` (or `ox_inventory/data/items.lua` with ox_inventory) |
| Usable item | `QBCore.Functions.CreateUseableItem` | `exports.qbx_core:CreateUseableItem` or ox_inventory item exports | `ESX.RegisterUsableItem` |

## Quick starts

- [QBCore quick start](/docs/frameworks/qbcore)
- [Qbox quick start](/docs/frameworks/qbox)
- [ESX Legacy quick start](/docs/frameworks/esx)

Each covers the txAdmin install, folder structure, making yourself admin, adding a job and an item, and common pitfalls.

_Last updated: 2026-09-22_

---

## QBCore quick start

URL: https://fivemad.com/docs/frameworks/qbcore

Install QBCore with the txAdmin recipe, understand its folders, make yourself admin, add a job and a usable item, write a small QBCore script, and avoid common pitfalls.

QBCore is one of the most popular FiveM roleplay frameworks, with the largest catalogue of compatible scripts. This quick start gets a QBCore server running and shows you how to add your own job, item and script. Official docs: [qbcore.org/docs](https://qbcore.org/docs).

[How to make a QBCore FiveM RP Server 2026 (HighwayTrooper)](https://www.youtube.com/watch?v=WDIvTwGDelo) (YouTube video)

## 1. Install with txAdmin

Requirements: an artifact, a license key, and **MariaDB** (QBCore's guide pairs it with HeidiSQL, see [Database setup](/docs/server-setup/database)).

1. Start FXServer, link your Cfx.re account in txAdmin.
2. Choose **Popular Recipes > QBCore**.
3. Enter your license key and the database connection (leave the database name empty).
4. **Run Recipe**, then **Save & Run Server**.

> [!IMPORTANT]
> On the first start, some resources build with yarn. QBCore's docs say to let yarn install run all the way through before restarting.

What the recipe installs is listed in [Popular recipes](/docs/txadmin/popular-recipes#qbcore). Its `server.cfg` enforces game build `3095`, sets `setr qb_locale "en"` and `setr UseTarget false`.

## 2. The folder structure

```text
resources/
├─ [cfx-default]/     Cfx default resources
├─ [standalone]/      oxmysql, PolyZone, connectqueue, progressbar, bob74_ipl...
├─ [voice]/           pma-voice, qb-radio
├─ [defaultmaps]/     hospital, dealer, prison maps
└─ [qb]/
   ├─ qb-core/        the framework
   │  ├─ config.lua
   │  ├─ shared/      jobs.lua, gangs.lua, items.lua, vehicles.lua, weapons.lua, locations.lua
   │  ├─ server/
   │  └─ client/
   ├─ qb-inventory/
   ├─ qb-policejob/ ...
```

`qb-core/shared/*.lua` is where most "data" lives: jobs, gangs, items, vehicles.

## 3. Make yourself admin

The recipe's `server.cfg` builds a permission chain:

```cfg title="server.cfg (from the QBCore recipe)"
add_ace qbcore.god command allow
add_principal qbcore.god group.admin
add_principal qbcore.god qbcore.admin
add_principal qbcore.admin qbcore.mod
```

Add yourself to `qbcore.god` with your identifier (find it in txAdmin's player info):

```cfg title="server.cfg"
add_principal identifier.fivem:123456 qbcore.god
# or: add_principal identifier.license:abcdef... qbcore.god
```

Restart, join, and try `/admin` for qb-adminmenu. txAdmin's own menu (`/tx`) works independently of this.

[How to Add Admin Permissions in QBCore and TXAdmin (Brave Development)](https://www.youtube.com/watch?v=fNjG5jBN8p0) (YouTube video)

## 4. Add a job

Jobs are in `qb-core/shared/jobs.lua`. Copy an existing entry:

```lua title="qb-core/shared/jobs.lua"
QBCore.Shared.Jobs = {
    -- ...existing jobs...
    burgershot = {
        label = 'Burger Shot',
        defaultDuty = true,
        offDutyPay = false,
        grades = {
            ['0'] = { name = 'Trainee', payment = 50 },
            ['1'] = { name = 'Cook', payment = 75 },
            ['2'] = { name = 'Manager', isboss = true, payment = 120 },
        },
    },
}
```

- The key (`burgershot`) is the job name scripts check.
- Grades are **string** keys (`'0'`, `'1'`) in QBCore.
- `isboss = true` gives access to the boss menu (qb-management).

Restart `qb-core` (or the server) and give yourself the job: `/setjob [your id] burgershot 2`.

## 5. Add a usable item

Items live in `qb-core/shared/items.lua`:

```lua title="qb-core/shared/items.lua"
QBCore.Shared.Items = {
    -- ...
    burger = {
        name = 'burger',
        label = 'Burger',
        weight = 250,
        type = 'item',
        image = 'burger.png',
        unique = false,
        useable = true,
        shouldClose = true,
        description = 'A juicy Burger Shot burger',
    },
}
```

Put `burger.png` in the inventory's image folder (`qb-inventory/html/images/`). The [Inventory Icons](/tools/inventory-icons) tool makes transparent item images from prop pictures or your own images.

Make it do something when used, in a server script of your own resource:

```lua title="my_food/server.lua"
local QBCore = exports['qb-core']:GetCoreObject()

QBCore.Functions.CreateUseableItem('burger', function(source, item)
    local Player = QBCore.Functions.GetPlayer(source)
    if not Player then return end
    if Player.Functions.RemoveItem(item.name, 1, item.slot) then
        TriggerClientEvent('my_food:eat', source)
        -- raise hunger through your HUD/status resource here
    end
end)
```

Give it to yourself with `/giveitem [your id] burger 1`.

## 6. A small QBCore script

A `/paycheck` command that pays bank money based on the player's job grade, with server side checks:

```lua title="my_paycheck/fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'
server_script 'server.lua'
dependency 'qb-core'
```

```lua title="my_paycheck/server.lua"
local QBCore = exports['qb-core']:GetCoreObject()
local lastClaim = {}

QBCore.Commands.Add('paycheck', 'Claim a bonus paycheck (once per hour)', {}, false, function(source)
    local src = source
    local Player = QBCore.Functions.GetPlayer(src)
    if not Player then return end

    local cid = Player.PlayerData.citizenid
    if lastClaim[cid] and os.time() - lastClaim[cid] < 3600 then
        TriggerClientEvent('QBCore:Notify', src, 'You already claimed it this hour', 'error')
        return
    end

    local job = Player.PlayerData.job
    local amount = 100 + (job.grade.level * 50)
    Player.Functions.AddMoney('bank', amount, 'paycheck-bonus')
    lastClaim[cid] = os.time()
    TriggerClientEvent('QBCore:Notify', src, ('Paid $%d for %s'):format(amount, job.label), 'success')
end)
```

Useful player data: `Player.PlayerData.citizenid`, `.charinfo` (first and last name), `.job` (`name`, `label`, `grade.level`, `onduty`), `.gang`, `.money` (`cash`, `bank`, `crypto`), `.metadata`.

## Common pitfalls

- **Editing `shared/*.lua` on a live server**: other resources cache shared data. Restart the server after changing jobs or items.
- **Old tutorials**: QBCore has changed a lot. Code with `TriggerEvent('QBCore:GetObject', ...)` is outdated: use `exports['qb-core']:GetCoreObject()`.
- **Modified forks**: many paid scripts expect a stock or a specific version of QBCore. Keep a note of what you changed in core files, or better, don't change core files.
- **qb-target vs ox_target**: `UseTarget` is `false` by default in the recipe. Decide early and configure resources to match.
- **Performance**: the full recipe runs many resources you may not need. Remove jobs and systems you don't use, check `resmon`.
- **XAMPP**: use a real MariaDB.

## Next steps

- Browse [qbcore.org/docs](https://qbcore.org/docs) for each resource's config.
- Swap in ox_inventory if you want it (the QBCore docs and ox_inventory's docs cover the conversion).
- The [video archive](/docs/videos) has a frameworks course with QBCore installs and follow ups.

_Last updated: 2026-09-22_

---

## Qbox quick start

URL: https://fivemad.com/docs/frameworks/qbox

Install Qbox with the txAdmin recipe, understand qbx_core and the ox stack, make yourself admin, add a job and an ox_inventory item, write a small Qbox script, avoid pitfalls.

Qbox began as a fork of QBCore and is now its own framework, built on the Overextended stack (ox_lib, ox_inventory, ox_target) with a compatibility bridge so many QBCore resources still run. Official docs: [docs.qbox.re](https://docs.qbox.re).

[Installing FiveM with QBox (BadCode.Codes)](https://www.youtube.com/watch?v=whEnm6baAnI) (YouTube video)

## 1. Requirements

From the Qbox installation docs:

- **MariaDB 10.9.0 or newer** (a current LTS is recommended). **MySQL is not supported, and XAMPP is not supported.** See [Database setup](/docs/server-setup/database).
- An up to date recommended artifact and a license key.
- txAdmin, which Qbox "highly recommends" for installing.

## 2. Install with txAdmin

1. Start FXServer, link your Cfx.re account.
2. **Popular Recipes > Qbox**.
3. License key, database connection (leave the name empty), **Run Recipe**.
4. **Save & Run Server**.

What the recipe installs is in [Popular recipes](/docs/txadmin/popular-recipes#qbox). Its config is split into `server.cfg`, `permissions.cfg`, `ox.cfg`, `voice.cfg` and `misc.cfg`, and it sets game build `3258`.

## 3. The structure

```text
resources/
├─ [cfx-default]/
├─ [ox]/             ox_lib, oxmysql, ox_target, ox_inventory, ox_doorlock, ox_fuel
├─ [qbx]/
│  ├─ qbx_core/      the framework
│  │  ├─ shared/     jobs.lua, gangs.lua, vehicles.lua, weapons.lua, locations.lua...
│  │  ├─ config/
│  │  └─ modules/    lib.lua, playerdata.lua (importable helpers)
│  ├─ qbx_garages/ ...
├─ [standalone]/     illenium-appearance, Renewed-Banking, scully_emotemenu...
├─ [voice]/          pma-voice, mm_radio
├─ [npwd]/           phone
└─ [assets]/         maps
```

Useful `server.cfg` convars from the recipe:

| Convar | Default in recipe | Meaning |
| --- | --- | --- |
| `qbx:enableBridge` | `"true"` | Enables the qb-core bridge so QBCore resources work. |
| `qbx:enableQueue` | `"true"` | qbx_core's built in join queue. |
| `qbx:max_jobs_per_player` | `1` | Multi job support if you raise it. |
| `qbx:enableVehiclePersistence` | `"false"` | Respawn deleted player vehicles. |
| `qbx:discordLink` | `"discord.gg/qbox"` | Change to your Discord. |

## 4. Make yourself admin

Qbox uses FiveM's ACE groups. The deployer already added **your** identifiers through `{{addPrincipalsMaster}}`, and `permissions.cfg` defines the groups. To add another admin:

```cfg title="permissions.cfg"
add_principal identifier.fivem:123456 group.admin
```

Restart, then open the admin menu (qbx_adminmenu) in game. qbx_core also has commands like `/setjob`, `/givemoney`, `/car`, `/dv` and `/tp`, and ox_inventory adds `/giveitem`.

## 5. Add a job

Jobs are in `qbx_core/shared/jobs.lua`. Job names must be lowercase, and grades use **number** keys:

```lua title="qbx_core/shared/jobs.lua"
return {
    -- ...existing jobs...
    ['burgershot'] = {
        label = 'Burger Shot',
        defaultDuty = true,
        offDutyPay = false,
        grades = {
            [0] = { name = 'Trainee', payment = 50 },
            [1] = { name = 'Cook', payment = 75 },
            [2] = { name = 'Manager', isboss = true, bankAuth = true, payment = 120 },
        },
    },
}
```

`isboss` gives access to the management menu, `bankAuth` to the society account. Police style jobs add `type = 'leo'`. Restart the server, then `/setjob [id] burgershot 2`.

> [!NOTE]
> The recipe sets `qbx:cleanPlayerGroups "true"`: on start, players' jobs and gangs that no longer exist in the config files are removed from the database. Don't delete a job from `jobs.lua` by accident.

## 6. Add an item (ox_inventory)

Qbox uses **ox_inventory**, so items are defined in `ox_inventory/data/items.lua`:

```lua title="ox_inventory/data/items.lua"
['burger'] = {
    label = 'Burger',
    weight = 220,
    stack = true,
    close = true,
    description = 'A juicy Burger Shot burger',
    client = {
        status = { hunger = 200000 },
        anim = 'eating',
        prop = 'burger',
        usetime = 2500,
    },
},
```

The `client` block alone makes it usable: ox_inventory plays the animation and prop, and the `status` field feeds hunger to the status system. Put `burger.png` in `ox_inventory/web/images/` (the [Inventory Icons](/tools/inventory-icons) tool makes transparent icons and `items.lua` entries). Test with `/giveitem [id] burger 1`.

For server logic on use, point the item at an export of your resource:

```lua title="ox_inventory/data/items.lua"
['lockpick'] = {
    label = 'Lockpick',
    weight = 160,
    server = { export = 'my_crime.lockpick' },
},
```

```lua title="my_crime/server.lua"
exports('lockpick', function(event, item, inventory, slot, data)
    if event == 'usingItem' then
        -- return false to cancel the use
        return true
    end
end)
```

Check the [ox_inventory docs](https://overextended.dev/ox_inventory) for the full item options (degrade, consume, buttons, weapons).

## 7. A small Qbox script

```lua title="my_paycheck/fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

shared_scripts {
    '@ox_lib/init.lua',
    '@qbx_core/modules/lib.lua',
}
server_script 'server.lua'

dependencies { 'ox_lib', 'qbx_core' }
```

```lua title="my_paycheck/server.lua"
local lastClaim = {}

lib.addCommand('paycheck', { help = 'Claim a bonus paycheck (once per hour)' }, function(source)
    local player = exports.qbx_core:GetPlayer(source)
    if not player then return end

    local cid = player.PlayerData.citizenid
    if lastClaim[cid] and os.time() - lastClaim[cid] < 3600 then
        exports.qbx_core:Notify(source, 'You already claimed it this hour', 'error')
        return
    end

    local job = player.PlayerData.job
    local amount = 100 + (job.grade.level * 50)
    exports.qbx_core:AddMoney(source, 'bank', amount, 'paycheck-bonus')
    lastClaim[cid] = os.time()
    exports.qbx_core:Notify(source, ('Paid $%d for %s'):format(amount, job.label), 'success')
end)
```

Key qbx_core server exports (from the [Qbox docs](https://docs.qbox.re)): `GetPlayer(source)`, `AddMoney(identifier, moneyType, amount, reason)`, `RemoveMoney(...)`, `SetJob(identifier, jobName, grade)`, `CreateUseableItem(item, cb)`, `Notify(source, text, type, duration)`, `GetPlayersData()`, `HasPrimaryGroup(source, filter)`. `identifier` can be a server ID or a citizen ID.

## Common pitfalls

- **MySQL or XAMPP**: not supported. Use MariaDB.
- **Mixing inventories**: Qbox is built around ox_inventory. Don't install qb-inventory next to it.
- **QBCore scripts**: most work through the bridge, but scripts that edit qb-core internals or use removed QBCore functions need changes. Check the Qbox docs' converting section.
- **Downloading ox resources from source**: use release zips.
- **Editing `jobs.lua` without a restart**: shared data is loaded on start.
- **Deleting jobs** with `qbx:cleanPlayerGroups` on: players lose that job from the database.

## Next steps

- Read the Qbox docs for each `qbx_*` resource's config.
- The [video archive](/docs/videos) has a Qbox series (jobs, boss menu, items) in the frameworks course.

_Last updated: 2026-09-22_

---

## ESX Legacy quick start

URL: https://fivemad.com/docs/frameworks/esx

Install ESX Legacy with the official txAdmin recipe, learn its structure, make yourself admin, add a job and an item in the database, write a small ESX script, avoid pitfalls.

ESX is the oldest of the big FiveM roleplay frameworks, and **ESX Legacy** is its current, maintained line. It has a huge catalogue of scripts and an official txAdmin recipe maintained by the ESX team. Official docs: [docs.esx-framework.org](https://docs.esx-framework.org).

[How to make an ESX FiveM Server! (HighwayTrooper)](https://www.youtube.com/watch?v=9UwKUztfVO8) (YouTube video)

## 1. Install with txAdmin

Requirements: an artifact, a license key, and **MariaDB**. The ESX docs are clear: use MariaDB only, not XAMPP, which they describe as outdated and known to cause data loss. See [Database setup](/docs/server-setup/database).

1. Start FXServer, link your Cfx.re account.
2. **Popular Recipes > ESX Legacy**.
3. License key and database connection (leave the name empty).
4. **Run Recipe** (the addons repository is big, so this step can take a while), then **Save & Run Server**.

What gets installed is listed in [Popular recipes](/docs/txadmin/popular-recipes#esx-legacy). The recipe's `server.cfg` sets game build `3258`, pma-voice settings and some security convars like `sv_filterRequestControl 2`.

## 2. The structure

```text
resources/
├─ [cfx-default]/
├─ [core]/            es_extended and the core ESX resources (from esx_core)
├─ [esx_addons]/      jobs, shops, society, vehicle shop and more (from ESX-Legacy-Addons)
└─ [standalone]/      oxmysql, ox_lib, pma-voice, bob74_ipl, phone
```

Start order in the recipe's `server.cfg`:

```cfg
ensure chat
ensure oxmysql
ensure esx_lib
ensure es_extended
ensure [core]
ensure [standalone]
ensure [esx_addons]
```

ESX stores most data **in the database**: users, jobs, job grades, items, owned vehicles.

## 3. Make yourself admin

ESX has its own player groups (the `group` column of the `users` table), synced to ACE. The recipe's `server.cfg` lets `es_extended` manage principals, so ESX can put you in `group.admin` when your ESX group is admin.

1. Join the server once so your user row exists.
2. From the **server console** (txAdmin Live Console), set your group: `setgroup [your id] admin`.
3. Reconnect.

Alternatively, edit the `group` column for your row in the `users` table with HeidiSQL while you're offline. ESX's admin commands (`/car`, `/dv`, `/tp`, `/setjob`, `/giveitem`, `/noclip`...) then work for you. txAdmin's `/tx` menu works independently.

## 4. Add a job

Jobs live in two tables: `jobs` (name, label) and `job_grades` (job_name, grade, name, label, salary, skin_male, skin_female). Add them with SQL:

```sql
INSERT INTO `jobs` (`name`, `label`) VALUES ('burgershot', 'Burger Shot');

INSERT INTO `job_grades` (`job_name`, `grade`, `name`, `label`, `salary`, `skin_male`, `skin_female`) VALUES
  ('burgershot', 0, 'trainee', 'Trainee', 50, '{}', '{}'),
  ('burgershot', 1, 'cook', 'Cook', 75, '{}', '{}'),
  ('burgershot', 2, 'boss', 'Manager', 120, '{}', '{}');
```

Then reload jobs without a restart with the `refreshjobs` command (console or as admin), and assign it: `setjob [id] burgershot 2`. By ESX convention the top grade named `boss` gets the society boss menu in addons that support it.

## 5. Add an item

With the default ESX inventory, items are rows in the `items` table:

```sql
INSERT INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`) VALUES
  ('burger', 'Burger', 1, 0, 1);
```

Run `refreshitems`, then `giveitem [id] burger 1`. Make it usable in a server script:

```lua title="my_food/server.lua"
ESX.RegisterUsableItem('burger', function(source)
    local xPlayer = ESX.GetPlayerFromId(source)
    if not xPlayer then return end
    xPlayer.removeInventoryItem('burger', 1)
    TriggerClientEvent('esx_status:add', source, 'hunger', 200000)
    xPlayer.showNotification('You ate a burger')
end)
```

If you switched to **ox_inventory**, items are defined in `ox_inventory/data/items.lua` instead (same format as in the [Qbox quick start](/docs/frameworks/qbox#6-add-an-item-ox_inventory)). The [Inventory Icons](/tools/inventory-icons) tool makes transparent item images.

## 6. A small ESX script

```lua title="my_paycheck/fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

shared_script '@es_extended/imports.lua'
server_script 'server.lua'

dependency 'es_extended'
```

`@es_extended/imports.lua` gives your resource the `ESX` object. (The older way, `local ESX = exports['es_extended']:getSharedObject()`, also works.)

```lua title="my_paycheck/server.lua"
local lastClaim = {}

ESX.RegisterCommand('paycheck', 'user', function(xPlayer, args, showError)
    local id = xPlayer.getIdentifier()
    if lastClaim[id] and os.time() - lastClaim[id] < 3600 then
        xPlayer.showNotification('You already claimed it this hour', 'error')
        return
    end

    local job = xPlayer.getJob()
    local amount = 100 + (job.grade * 50)
    xPlayer.addAccountMoney('bank', amount, 'paycheck-bonus')
    lastClaim[id] = os.time()
    xPlayer.showNotification(('Paid $%d for %s'):format(amount, job.label), 'success')
end, false, { help = 'Claim a bonus paycheck (once per hour)' })
```

Useful `xPlayer` methods (from es_extended's player class): `getIdentifier()`, `getName()`, `getGroup()`, `getJob()`, `setJob(name, grade)`, `getMoney()`, `addMoney(amount, reason)`, `removeMoney(...)`, `getAccount('bank')`, `addAccountMoney(account, amount, reason)`, `getInventoryItem(name)`, `addInventoryItem(name, count)`, `removeInventoryItem(name, count)`, `canCarryItem(name, count)`, `showNotification(msg)`, `triggerEvent(name, ...)`. Server helpers: `ESX.GetPlayerFromId(src)`, `ESX.GetExtendedPlayers()`, `ESX.GetJobs()`, `ESX.RegisterUsableItem`, `ESX.RegisterCommand`.

## Common pitfalls

- **Old ESX tutorials**: code with `TriggerEvent('esx:getSharedObject', function(obj) ESX = obj end)` is from old ESX versions. Use `@es_extended/imports.lua` or the export.
- **Old addons**: many `esx_*` scripts on the internet target ESX 1.1 or 1.2 and use removed functions or `mysql-async`. oxmysql provides `mysql-async` compatibility, but test old scripts carefully.
- **XAMPP**: the ESX docs say not to use it.
- **Jobs not showing**: you inserted the SQL but didn't run `refreshjobs` or restart, or `job_grades.job_name` doesn't match `jobs.name`.
- **Money types**: cash is `money`, bank is the `bank` account, and some servers use `black_money`. Use `addAccountMoney` with the right account name.
- **Locale**: the recipe leaves `setr esx:locale` commented, so ESX uses the language picked in txAdmin. Uncomment and set it to override.

## Next steps

- Read [docs.esx-framework.org](https://docs.esx-framework.org) for es_extended's full API.
- Swap in ox_inventory if you want slot based inventory (see the ESX course videos in the [video archive](/docs/videos)).

_Last updated: 2026-09-22_

---


# Tools

## Tool guides

URL: https://fivemad.com/docs/tools

A guide for every fivemad tool: what it is for, every option, what it exports and how to use the result in your FiveM resource or server.

Every tool on fivemad runs in your browser and is free, with no account. These pages explain how to use each one: what it is for, what every option does, what you get out of it and how to put that into your server or resource. Each guide has an **Open the tool** button at the top.

> [!TIP]
> Looking for one specific thing, like a native, a file name or a flag? Press <kbd>Ctrl</kbd> <kbd>K</kbd> and search. The search looks inside every guide, not only the titles.

## Generators

Tools that make something for you from a few inputs.

| Guide | Use it to |
| --- | --- |
| [Generators](/docs/tools/generators) | Make a roleplay character, server names, a gang with ranks and turf, or a script idea with a build plan |
| [Inventory Icons](/docs/tools/inventory-icons) | Build a clean icon pack from game props or your own images, with the items list for your inventory |
| [Script Thumbnail Creator](/docs/tools/script-thumbnail-creator) | Export release images for forum.cfx.re, YouTube, Discord and Tebex in every size at once |
| [Item Icons](/docs/tools/item-icons) | Browse ready made item pictures on our sister site |

## Config and code

Builders and editors for the files a server and its resources are made of.

| Guide | Use it to |
| --- | --- |
| [server.cfg Generator](/docs/tools/server-cfg-generator) | Write a complete server.cfg with OneSync, endpoints, tags, resources and permissions |
| [fxmanifest.lua Generator](/docs/tools/fxmanifest-generator) | Start a resource with a valid manifest |
| [Vehicle Handling Editor](/docs/tools/vehicle-handling-editor) | Tune a car and export handling.meta or runtime Lua |
| [Clothing Designer](/docs/tools/clothing-designer) | Paint clothing textures in 3D and export .ytd files |
| [3D Tattoo Editor](/docs/tools/tattoo-editor) | Place a tattoo on the freemode ped and copy the overlay XML |
| [Drawable Studio](/docs/tools/drawable-studio) | Open a model export in 3D, edit materials and lights, paint and export |
| [Weapons Meta Editor](/docs/tools/weapons-meta-editor) | Change damage, range, fire rate and recoil from the game defaults |
| [YTYP Creator](/docs/tools/ytyp-creator) | Write archetype definitions for custom props |
| [Texture Editor](/docs/tools/texture-editor) | Replace and convert the textures of a .ytd |
| [Vehicle Sirens Editor](/docs/tools/vehicle-sirens) | Design light patterns and export carcols.meta sirens |
| [Vehicle Pack Validator](/docs/tools/vehicle-pack-validator) | Find every broken link in a vehicle resource before you ship it |
| [YMT Creator](/docs/tools/ymt-creator) | Generate the ped variation .ymt for an addon clothing pack |
| [YTD Optimizer](/docs/tools/ytd-optimizer) | Shrink many .ytd files at once |
| [Native Audio Builder](/docs/tools/native-audio-builder) | Turn sound files into a native audio resource |
| [YMAP Builder](/docs/tools/ymap-builder) | Place props by coordinates and export a .ymap |

## Server

Checks and helpers for a running server.

| Guide | Use it to |
| --- | --- |
| [Server Status Checker](/docs/tools/server-status-checker) | See if a server is online, its players, build and resources |
| [Profiler Analyzer](/docs/tools/profiler-analyzer) | Find the resources and threads that cost you frame or tick time |
| [Cfx Blacklist Checker](/docs/tools/cfx-blacklist-checker) | Check an IP or host before you rent it |
| [Server Status Badge](/docs/tools/server-uptime-badge) | Embed a live player count badge |
| [FXServer artifacts](/docs/tools/artifacts) | Pick a server build that is known to work |

## Calculators

Flag values and codes for natives.

| Guide | Use it to |
| --- | --- |
| [joaat Hash Calculator](/docs/tools/hash-calculator) | Get GetHashKey values in signed, unsigned and hex form |
| [Driving Style Calculator](/docs/tools/driving-style-calculator) | Build the driving style flag for AI drivers |
| [Animation Flags Calculator](/docs/tools/animation-flags-calculator) | Build the flag value for TaskPlayAnim |
| [Warning Screen Buttons](/docs/tools/warning-buttons) | Build the button flags for SetWarningMessage |
| [Draw Text Colors](/docs/tools/text-colors) | Preview ~r~ ~b~ ~h~ text codes |

## References

Searchable lists of game data with ready snippets.

| Guide | Use it to |
| --- | --- |
| [Model & Hash Browser](/docs/tools/model-hash-browser) | Find vehicles, peds and weapons with spawn names and hashes |
| [Interactive Map](/docs/tools/interactive-map) | Get coordinates, measure distances and drop pins |
| [3D world](/docs/tools/world-3d) | Freecam or walk through the map in 3D |
| [Blip, Marker & Checkpoint Browser](/docs/tools/blip-marker-browser) | Pick blip sprites, colours, markers and checkpoints |
| [Weapon Stats & Components](/docs/tools/weapon-stats) | Look up weapon hashes, components and tints |
| [Objects / Props List](/docs/tools/objects-list) | Find props with pictures, sizes and hashes |
| [Particle Effects List](/docs/tools/particles-list) | Find particle effects and their asset dictionaries |
| [Particle videos](/docs/tools/particle-videos) | Watch particle effects before you use them |
| [Sound Browser](/docs/tools/sound-browser) | Listen to frontend sounds and copy the call |
| [Controls Reference](/docs/tools/controls-reference) | Find control indexes and default keys |
| [Scaleform Functions](/docs/tools/scaleform-reference) | Look up scaleform movies and their functions |
| [Player Stats List](/docs/tools/player-stats) | Find stat names and types |
| [Parachutes & Smoke Trails](/docs/tools/parachutes) | Get parachute tints and smoke trail colours |
| [Game Damage Events](/docs/tools/damage-events) | Detect kills, deaths and vehicle damage |

## Community

| Guide | Use it to |
| --- | --- |
| [Giveaways](/docs/tools/giveaways) | Enter giveaways with your Discord account |

_Last updated: 2026-09-23_

---

## Generators

URL: https://fivemad.com/docs/tools/generators

How to use the four fivemad generators: roleplay characters, server names with hostname lines, gangs with framework exports and script ideas.

The Generators page holds four random generators behind one set of tabs: **Character**, **Server name**, **Gang** and **Script idea**. They are for server owners who need names, lore or a starting point fast, and for developers looking for the next resource to build.

## What it is for

- Writing a backstory for a new roleplay character, or handing staff a batch of NPC personas for an event.
- Naming a new server and getting working `sv_hostname` and `sv_projectName` lines with FiveM colour codes.
- Filling a gang whitelist with an organisation that has ranks, turf, rivals and a history, then pasting the grades into QBCore, Qbox or ESX.
- Picking a script to build that is not already released ten times on forum.cfx.re.

## Tabs and links

The open tab is kept in the address bar as `?g=`, so you can share or bookmark a direct link:

| Tab | Link |
| --- | --- |
| Character | `/tools/generators?g=character` |
| Server name | `/tools/generators?g=server-name` |
| Gang | `/tools/generators?g=gang` |
| Script idea | `/tools/generators?g=script-idea` |

Without `?g=` (or with an unknown value) the page opens on **Character**.

## Character

Rolls a full roleplay character: name, nickname, age and date of birth, birthplace, occupation, appearance (height, build, hair, eyes, notable features, usual clothes), personality tags, skills, flaws, backstory, goals, fears, relationships, story hooks and a starter inventory.

### Options

| Option | Choices | Default |
| --- | --- | --- |
| Gender | Random, Male, Female | Random |
| Age range | Any age, 18 to 25, 26 to 35, 36 to 50, 51 to 70 | Any age |
| Archetype | Random, Civilian, Criminal, Police, EMS, Mechanic, Lawyer, Businessman, Journalist, Street racer, Trucker, Hacker, Farmer / Rancher, Nightlife | Random |
| Origin | Random, Los Santos native, Blaine County, Liberty City, Vice City, Out of state, Abroad | Random |
| Tone | Grounded, Gritty, Dramatic, Lighthearted | Grounded |

### Locking and re-rolling

Every block (Name, Nickname, Age / DOB, Birthplace, Occupation, Appearance, Personality, Skills, Flaws, Backstory, Goals, Fears, Relationships, Story hooks, Starter inventory) has a lock and a re-roll arrow. A locked block is kept when you press **Generate**; the arrow re-rolls just that one block. **Unlock all** appears once something is locked.

## Server name

Generates 24 server names per press, each with a tagline and a coloured hostname.

### Options

| Option | What it does | Default |
| --- | --- | --- |
| Theme | Serious RP, Casual RP, Gang / Street, Police / Emergency, Racing, Drift, Economy, Zombie / Survival, Freeroam, Whitelisted, Blaine County RP, Turkish community | Serious RP |
| Style | Mixed, Short / brandable, City RP, Acronym, X Roleplay, Phrase + tagline | Mixed |
| Keyword (optional) | A word worked into some names, up to 24 characters. <kbd>Enter</kbd> generates. | empty |
| Hostname accent | The colour code used for the accent parts of the hostname: **Auto** (theme colour) or `^1` to `^6`, `^8`, `^9` | Auto |

Each card has a star (favourite), **Hostname** (copies the full `sv_hostname` line), **Name** and **server.cfg**. Clicking a card shows a server list preview with the colours rendered and a `server.cfg` block:

```cfg title="server.cfg"
sv_hostname "^5Nova City RP ^7| Immersion first, always"
sets sv_projectName "Nova City RP"
sets sv_projectDesc "Immersion first, always"
sets tags "roleplay, serious, economy, custom, jobs, english"
sets locale "en-US"
```

That is a Serious RP example, whose auto accent is `^5`. The `tags` and `locale` lines come from the chosen theme (the Turkish theme uses `tr-TR`). The accent only swaps `^1` to `^6` and `^8`; the neutral `^7`, `^9` and `^0` parts stay as they are. Favourites (up to 50) are kept in this browser.

## Gang

Builds a criminal organisation: name and motto, colours with hex values, territory in real Los Santos areas, headquarters, symbol and graffiti tag, ranks (low to high, the top one marked boss), history with a founding year, rackets, rules, rivals and allies, vehicle spawn names, weapons and notable members with their rank.

### Options

| Option | Choices | Default |
| --- | --- | --- |
| Organisation type | Random, Street gang, Cartel, Motorcycle club, Mafia family, Triad, Yakuza, Bratva, Hacker collective, Heist crew | Random |
| Size | Small (8 to 15), Medium (15 to 40), Large (40 to 100), Empire (100+) | Medium |
| Alignment | Code of honour, Business first, Ruthless, Chaotic, Neighbourhood protectors | Business first |

Size changes how many territories, rackets, rivals and members you get, and small crews get a shorter rank ladder. Locks work like the character tab, with one catch: locked fields only survive **Generate** while the organisation type stays the same, and locking the name also locks the type. Colours that match GTA V lore gangs (purple Ballas, green Families, yellow Vagos) carry a warning note.

### Framework export

Under the card, **Framework export** has three tabs:

- **QBCore**: a `QBShared.Gangs['key']` entry for `qb-core/shared/gangs.lua`, top grade with `isboss = true`.
- **Qbox**: an entry to add inside the table returned by `qbx_core/shared/gangs.lua`, top grade with `isboss = true, bankAuth = true`.
- **ESX (SQL)**: `INSERT` rows for `jobs` and `job_grades`, because ESX has no separate gang system and most servers register gangs as whitelisted jobs.

```lua title="gangs.lua"
QBShared.Gangs['los_santos_kings'] = {
    label = 'Los Santos Kings',
    grades = {
        ['0'] = { name = 'Recruit' },
        ['1'] = { name = 'Soldier' },
        ['2'] = { name = 'Boss', isboss = true },
    },
}
```

The key is a slug of the gang name.

## Script idea

Picks one of the hand-written resource ideas and builds a plan around it: title, resource name, pitch, player loop, market context, feature tiers (MVP, v1, Premium), positioning (pricing model and why), dependencies and items, client side and server side notes, net events, natives, NUI, anti-exploit checks and an effort estimate.

### Options

| Option | What it does | Default |
| --- | --- | --- |
| Category | Any category or one of 12 (Legal jobs, Crime & heists, Economy & business, Police, EMS & government, Vehicles, Phones & devices, UI & HUD, Admin, dev tools & creators, Social & lifestyle, Minigames & activities, PvP & survival, Housing & property). Each shows its release count and saturation. | Any category |
| Open niches only | Only ideas with little or no competition in the sample | off |
| Trending | Only ideas that ride a rising topic | off |
| Framework | QBCore, Qbox, ESX Legacy, ox_core, Standalone | QBCore |
| Complexity | Beginner, Intermediate, Advanced | Intermediate |

Press **New idea** to roll. The panel tells you how many ideas match your filters. If none match every filter in a category, one filter is relaxed and a notice says so. Switching **Framework** or **Complexity** rebuilds the plan for the idea you are looking at instead of rolling a new one.

### Market snapshot

The market data comes from the latest 250 releases on forum.cfx.re (10 to 18 September 2026): script vs non-script counts, paid vs free, the multi-framework share, releases per category (crowded is 20+, open is under 8), framework support shares, and rising and crowded topics.

### Code tabs

Below the idea: **Structure** (folder tree), **fxmanifest** (`fxmanifest.lua`), **config.lua**, **bridge.lua** and, when the idea needs a database, **SQL** (`install.sql`). These are a starting skeleton for the chosen framework, not a finished resource.

## Copying and history

Every generator has **Copy text** and **Copy Markdown** for the whole result, and a **History** list with the last 10 results you can reopen, remove or clear.

## Limitations

- Everything is generated in your browser. Nothing is sent to a server.
- History and favourites live in this browser's local storage, so they do not follow you to another device.
- The script idea market numbers are a snapshot, not live data.
- Generated names are random; check that a server name is not already taken before you build a brand on it.

## Related tools

- [server.cfg Generator](/docs/tools/server-cfg-generator) for the rest of your config around the hostname lines.
- [fxmanifest Generator](/docs/tools/fxmanifest-generator) to turn a script idea into a real resource manifest.
- [Inventory Icons](/docs/tools/inventory-icons) for the items a new script needs.
- [Script Thumbnail Creator](/docs/tools/script-thumbnail-creator) when the script is ready to release.

_Last updated: 2026-09-22_

---

## Inventory Icons

URL: https://fivemad.com/docs/tools/inventory-icons

Make trimmed, transparent inventory icons from game prop pictures or your own images and export a zip with items.lua for ox_inventory, qb-inventory and more.

Inventory Icons turns prop pictures from the game, or your own PNG, JPG and WebP files, into a clean icon pack: background removed, empty edges trimmed, every item padded and sized the same way. You fill in the item data once and download a zip with the icons in the right folder plus the item list for your inventory.

## What it is for

Adding items to a server usually means two chores that never match up: finding or cutting a picture for each item, and writing the item entry with the exact same name as the file. This tool does both in one pass. The item name is also the file name, so `water_bottle.png` and `['water_bottle']` can never drift apart.

Supported targets: **ox_inventory**, **qb-inventory**, **ps-inventory**, **qs-inventory**, **codem-inventory** and **ESX (items table)**.

## Quick start

1. On **Game props**, search the prop pictures (name, label or tag), narrow them with the category dropdown, and click as many as you want. Then press **Add N props**.
2. Or switch to **Your images** and press **Choose images**, or drop files anywhere on the page.
3. In **Every icon**, pick the **Icon size**, **Format**, **Padding** and the rest. The big preview shows the selected icon.
4. Fix anything odd on a single icon with its own background, tolerance and padding.
5. Fill in the **Items** table: item name, label, weight, stack and so on. Use the bulk bar for many rows at once.
6. Under **Export**, pick your **Inventory**, then **Download zip** or copy the Lua / SQL.

## Adding pictures

### Game props

The picker loads about 29,000 prop pictures (160 px transparent WebP, the same ones as in the [Objects List](/docs/tools/objects-list)). Every search word has to match. The grid shows 60 results at a time with **Show more**, and **Select the N shown** picks everything visible. You can pick up to 500 props before you have to add them. Props already in the pack are marked **In pack** and are not added twice.

Items made from props get a name from the prop label (for example `Water Bottle` becomes `water_bottle`) and keep the prop model, which qs-inventory uses as `object`.

### Your images

Only PNG, JPG and WebP are read; other files in a drop are skipped with a notice. The file name becomes the item name and label: `Water Bottle.png` turns into the name `water_bottle` and the label `Water Bottle`.
If you want sharper art than a 160 px prop picture, [Item Icons](https://items.rainmad.com) has 18,000 item images for FiveM inventories. Download the ones you need and drop them here to trim, resize and name them.

## Every icon (pack settings)

| Setting | What it does | Default |
| --- | --- | --- |
| Icon size | Output square: 100, 128, 256 or 512 px | 128 |
| Format | PNG or WebP | PNG |
| Align | **Center**, or **Bottom** (object sits on the bottom padding line) | Center |
| Padding | Empty border on each side, 0-30 % of the icon size | 6 % |
| Trim empty edges | Crops transparent space so every item fills the icon the same way | on |
| Background removal | Auto, Off, Remove from the edges, Remove one colour everywhere | Auto |
| Tolerance | How far a colour may be from the background colour and still be removed, 1-60 | 18 |
| Background colour | Colour picker for removal. Empty means it is read from the picture corners; **Use the corners** clears it | empty |
| Soft drop shadow | A soft dark shadow under the object | off |
| Outline | Outline width 0-8 px with its own colour | 0 px, white |

**Reset settings** puts everything back to these defaults. The pack settings and the chosen inventory are remembered in this browser.

### Background removal modes

- **Auto (only pictures without transparency)** runs the edge fill only on pictures whose border is solid, like photos and screenshots. Prop pictures and cut out PNGs are left alone.
- **Off** keeps the picture as it is.
- **Remove from the edges** flood fills from the border using the corner colours (or the colour you picked). White parts inside the object stay, as long as they do not touch the background.
- **Remove one colour everywhere** is a chroma key. Good for green screen shots, but it also removes that colour inside the object.

> [!TIP]
> Raise the tolerance when a halo stays around the object, lower it when parts of the object disappear. Busy or textured backgrounds need a real cut out in an image editor.

## The selected icon

Click a tile to open it in the preview. You can switch the preview backdrop between checker, dark and light to see edges on both. The panel shows:

- **Object**: the size of the visible object after trimming, in source pixels.
- **Scale**: how much it was scaled. Above 1.25x it turns amber and the tile shows a badge like `1.6x`, because upscaled icons look soft.
- **Background**: `kept`, or the share of pixels removed.
- **File**: the size of the rendered icon.

Per icon you can override **Background for this icon**, **Tolerance for this icon** and **Padding for this icon**. **Back to the settings of every icon** drops the overrides. **Icon** downloads just that one file, and the bin removes it from the pack.

## Items table

| Column | Meaning | Default |
| --- | --- | --- |
| Item name | Item key and file name. Lowercase letters, digits and underscores only, max 50 characters, unique | from label or file name |
| Label | Display name | from prop label or file name |
| Weight (g) | Grams | 100 |
| Stack | Stackable | on |
| Usable | Shown for qb, ps, qs and codem | on |
| Close | Close the inventory on use | on |
| Rarity | None, Common, Epic, Legendary. Shown for qs-inventory and ESX | None |
| Description | Free text | empty |

Names with a problem are marked red with the reason (empty, bad characters, too long, duplicate), and export is blocked until they are fixed.

Check rows to use the bulk bar: set **Weight**, **Stacking...**, **On use...** (usable, not usable, close or keep open), **Rarity...**, a description for all checked, **Auto label** (labels back to the prop label or file name), **Name from label**, or **Remove**. The table shows 100 rows and grows with **Show more rows**.

## Export

The zip is called `inventory-icons-<target>.zip` and contains the icons in the target folder, the item snippet and a `README.txt` with the steps.

| Inventory | Icons folder in the zip | Snippet file | Paste into |
| --- | --- | --- | --- |
| ox_inventory | `ox_inventory/web/images/` | `items.ox_inventory.lua` | `ox_inventory/data/items.lua` |
| qb-inventory | `qb-inventory/html/images/` | `items.qb-core.lua` | `qb-core/shared/items.lua` |
| ps-inventory | `ps-inventory/html/images/` | `items.qb-core.lua` | `qb-core/shared/items.lua` |
| qs-inventory | `qs-inventory/html/images/` | `items.qs-inventory.lua` | `qs-inventory/shared/items.lua` |
| codem-inventory | `codem-inventory/html/itemimages/` | `items.codem-inventory.lua` | `codem-inventory/config/itemlist.lua` |
| ESX (items table) | `images/` | `items.esx.sql` | the `items` table in your database |

Icons that failed to load or came out empty after background removal are left out, and the status line tells you how many.

### ox_inventory

Paste the entries inside the `return { ... }` table. ox_inventory builds the picture path as `web/images/<name>.png` on its own, so for WebP exports every item gets a `client.image` line:

```lua title="ox_inventory/data/items.lua"
	['water_bottle'] = {
		label = 'Water Bottle',
		weight = 100,
		stack = true,
		close = true,
		client = {
			image = 'water_bottle.webp',
		},
	},
```

### qb-inventory and ps-inventory

Both read the qb-core item list. One line per item, pasted inside `QBCore.Shared.Items = { ... }`. Stack maps to `unique = not stack`:

```lua title="qb-core/shared/items.lua"
    water_bottle = { name = 'water_bottle', label = 'Water Bottle', weight = 100, type = 'item', image = 'water_bottle.png', unique = false, useable = true, shouldClose = true, description = '' },
```

codem-inventory uses the same fields with a `['name']` key.

### qs-inventory

Same fields as qb, plus `rare` when you set a rarity and `object` (the prop model) for items made from props.

### ESX

```sql title="items.esx.sql"
INSERT IGNORE INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`) VALUES
	('water_bottle', 'Water Bottle', 1, 0, 1);
```

ESX weights are whole numbers in the unit of `Config.MaxWeight` (kg by default), so grams are rounded to kg with a minimum of 1. `rare` is 1 for Epic and Legendary, 0 for Common or no rarity. ESX core has no icon folder: put the pictures wherever your inventory UI loads item images from. If you run ox_inventory on ESX, pick ox_inventory instead.

After pasting, restart the inventory, and for qb-core based inventories restart qb-core too (or the whole server).

## Sizes

The stock icons of ox_inventory and qb-inventory are 100x100 PNG, and the inventory scales them to the slot. 128 is a good default and keeps prop pictures sharp. 256 looks crisper on 1440p and 4K screens, but prop pictures are only 160 px, so 256 and 512 upscale them (the settings panel warns you). Keep an eye on the pack size shown next to the icon count: the inventory UI loads every icon, and a few hundred 512 px PNGs add up.

## Limitations

- Everything runs in your browser and nothing is uploaded. On some older browsers the page notes that icons render one at a time, which is slower for big packs.
- The pack itself is not saved. Reloading the page empties it, only the settings are remembered.
- What happens when an item is used is still up to your scripts; the tool only writes the definition.
- The codem-inventory folder and file follow CodeM's mInventory Remake docs. Check them against your version.

## Related tools

- [Item Icons](/docs/tools/item-icons) for high resolution item art to drop in here.
- [Objects List](/docs/tools/objects-list) to find the prop model behind a picture.
- [Generators](/docs/tools/generators) when you need ideas for the items a new script uses.

_Last updated: 2026-09-22_

---

## Script Thumbnail Creator

URL: https://fivemad.com/docs/tools/script-thumbnail-creator

Make release thumbnails for forum.cfx.re, YouTube, Discord, Tebex and GitHub from your screenshots: nine templates, eight sizes, PNG or JPG export.

The Script Thumbnail Creator builds preview images for a script release from your own in-game screenshots. You type the name, a one-liner, frameworks and price once, pick one of nine templates, and export the image for the forum.cfx.re releases page, a YouTube video, a Discord post, a Tebex package or a GitHub repo, one size at a time or all eight in a zip.

## What it is for

A release topic, a store page and a showcase video all want a different image size, and redoing the layout in an image editor for each one is slow. Here the layout is rebuilt for every size from the same project, so the square post is as tidy as the 16:9 one. It is meant for script developers who want a clean, readable thumbnail without opening Photoshop.

## Quick start

1. Drop one to four in-game screenshots anywhere on the editor, or paste one with <kbd>Ctrl</kbd> + <kbd>V</kbd>. The sample pictures of Los Santos are replaced by your own.
2. On the **Text** tab, type the **Script name**, the **One-liner**, pick the **Frameworks** and set the **Price**.
3. Pick a size in the row above the preview (Forum, Link preview, YouTube and so on) and a template under **Templates**.
4. Drag a screenshot in the preview to move it. Click the preview once, then scroll over a screenshot to zoom.
5. Open **Export** and press **Download PNG**, **Copy**, or **All sizes** for a zip.

Click any text in the preview to jump to its field. <kbd>Ctrl</kbd> + <kbd>Z</kbd> undoes, <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Z</kbd> (or <kbd>Ctrl</kbd> + <kbd>Y</kbd>) redoes.

## Sizes

The size row sets the output. Each size shows a short note under the preview about where it is used, and **Safe zones** (on by default) draws what the platform covers or crops. Safe zones only show in the preview, never in the export.

| Button | Name | Size | What to know |
| --- | --- | --- | --- |
| Forum | Cfx.re forum post | 1920 x 1080 | The first image of a release topic becomes its preview on the releases page. Posts show it at 690 px wide, the composer shrinks wider images to 1920 px and recompresses files over 512 KB. Upload limit 15 MB. |
| Link preview | Link preview (Open Graph) | 1200 x 630 | The `og:image` for your store, docs or GitHub Pages site. Compact cards crop the middle square. X rejects card images over 5 MB. |
| YouTube | YouTube thumbnail | 1280 x 720 | Seen at about 360 px on phones. The length badge covers the bottom right corner and the progress bar runs along the bottom. 2 MB limit. |
| Discord | Discord post image | 1600 x 900 | Shown at about 550 px wide with rounded corners. Free upload limit 10 MB. |
| Server banner | Discord server banner | 960 x 540 | Needs Boost level 2. The server name is drawn over the top quarter. |
| Tebex | Tebex package image | 1280 x 720 | What most FiveM store themes use for package cards. Grid cards may trim the edges; some older templates cap the height at 165 px. |
| GitHub | GitHub social preview | 1280 x 640 | Set it under Settings, Social preview. Must be under 1 MB. |
| Square | Square post | 1080 x 1080 | Instagram, X and store grids. Instagram profile grids crop to 3:4. |

## Templates

Every template is drawn with your current content in the gallery, so you can compare them before picking one.

| Template | Layout | Screenshots used |
| --- | --- | --- |
| Showcase | Screenshot full bleed, title on a dark fade | 1 |
| Split | Text column, tilted screenshots on the right | 2 |
| Collage | Two to four screenshots with a title card | 4 |
| Spotlight | One UI screenshot framed on a blur of itself | 1 |
| Type | Big type, spec row, screenshot as a strip | 1 |
| Panel | Tall crop for phone, tablet and menu NUIs | 1 |
| Bold | YouTube style: huge words, hard contrast | 1 |
| Announcement | Discord release card with a header row | 1 |
| Changelog | Update post: version up front, changes listed | 1 |

Not every template shows every field. When a field is not used by the current template, its label says **Not shown in** followed by the template name. For example, only Split, Panel and Changelog draw the **Features** list, and Bold only uses the title, frameworks, price, author and logo.

## Text tab

| Field | What it does | Limit |
| --- | --- | --- |
| Script name | The title. Wrap a word in `*stars*` to colour it with the accent. <kbd>Enter</kbd> starts a new line. Titles shrink to fit. | 120 characters |
| One-liner | What the script does, in one sentence | 200 |
| Label | A small tag like "New release" or "Update" | 40 |
| Version | For example `v1.0.0` | 20 |
| Frameworks | Toggle QBCore, Qbox, ESX, ox_lib, ox_inventory, Standalone, vRP, ND Core. Type another one (like RSG Core) and press **Add**. Chips show in the order you click them; chips that do not fit are left out. | 24 per custom chip |
| Features | Up to four short lines | 60 each |
| Price | **Hidden**, **Free**, **Paid** (with a price field such as `$19.99`) or **Open source** | 16 for the price |
| Author or brand | Your studio name | 40 |
| Logo | **Upload** a PNG, JPG, WebP or SVG. A transparent PNG works best. | |

Framework names are plain text on purpose: the logos of QBCore, ESX and the others belong to those projects, so do not paste them in unless you have permission.

## Images tab

Up to four screenshot slots. Each slot shows the file name, its size and whether the current template uses it. Per slot you get:

- **Zoom** from 1x to 4x.
- **Left, right** and **Up, down** to move the crop.
- **Replace** to swap the picture, **Reset crop** to go back to 1x centred.
- Arrows to reorder and a bin to remove. In Collage the first screenshot gets the big tile.

**Add screenshots** adds more while there is room, and an empty slot has **Choose image**. You can also drop a file on the editor at any time.

In the preview, with a screenshot selected, the arrow keys move it (hold <kbd>Shift</kbd> for bigger steps) and <kbd>+</kbd> / <kbd>-</kbd> zoom.

## Style tab

| Setting | What it does | Default |
| --- | --- | --- |
| Palette | Eight presets: Signal orange, Lime, Cobalt, Crimson, Amber, Mint, Hot pink, Mono | Signal orange |
| Accent / Background | Your own hex colours; editing them switches the palette to custom | from the palette |
| Background | **Blurred screenshot**, **Gradient** or **Solid**. Templates with a full-bleed screenshot ignore it. | Blurred screenshot |
| Darken | How much the screenshot is darkened behind text | 55 % |
| Vignette | Darker corners | 35 % |
| Film grain | A fine noise layer that hides banding in dark gradients after JPG compression | on |
| Font | Geist, Inter Tight, Space Grotesk, Bricolage Grotesque, Archivo, Unbounded, Oswald, Anton | Geist |
| Title size | 60-140 %. Titles already shrink to fit; this sets the largest size they may grow to. | 100 % |
| Alignment | Left or Center, used by Showcase and Spotlight | Left |
| Uppercase title | Uppercase the title. Oswald and Anton switch it on when picked. | off |

## Export tab

| Control | What it does |
| --- | --- |
| Format | **PNG** keeps text crisp. **JPG** is 5 to 10 times smaller; use it when a limit bites. |
| JPG quality | 60-100, shown only for JPG. Default 90. |
| Size box | The current size with its live file size and a check against the platform limit: fine, close to the limit, or over it. It also warns when a screenshot slot the template uses is still empty. |
| Download PNG / JPG | Saves the current size. |
| Copy | Copies the current size to the clipboard as PNG, ready to paste into Discord or the forum composer. |
| All sizes | Renders all eight sizes into one zip. |

### File names

| Export | Name |
| --- | --- |
| One image | `<script-name>-<size>-<w>x<h>.png` or `.jpg`, for example `dockside-jobs-forum-1920x1080.png` or `dockside-jobs-discord-banner-960x540.jpg` |
| All sizes | `<script-name>-thumbnails.zip` |
| Project | `<script-name>.thumbnail.json` |

### Projects

Your work is saved in this browser as you go, and the **Project** box tells you how: in full, with smaller copies of your screenshots, text and settings only (when the screenshots are too big for browser storage), or not at all when the browser blocks storage.

- **Save file** writes a `.thumbnail.json` project with your text, settings and screenshots at full quality. Hand it to whoever makes the next update post.
- **Open file** loads one again. You can also drop the `.json` on the editor.
- **Start empty** clears the content but keeps the size and style.
- **Load sample** brings back the sample project.

## Tips

- Capture at 1920 x 1080 or higher, with the HUD, chat and other scripts' UI hidden.
- Crop to what your script adds. A readable menu at 70 % zoom beats the whole screen.
- For phone, tablet and menu NUIs use **Panel** and zoom into the UI. **Spotlight** suits a wide dashboard.
- Keep the name to 2-4 words. Framework, version and price are what people scan for on the releases page; "Ultimate" and "Advanced" take space and add nothing.
- Upload the forum image to the forum directly, not as an external link. The composer recompresses files over 512 KB, so exporting a JPG at 90 yourself keeps the quality in your hands.

> [!TIP]
> Watch the tile in the gallery at its small size: that is roughly how big your thumbnail looks on a phone or in the releases list.

## Limitations

- Everything is drawn in your browser. Screenshots never leave your computer.
- Up to four screenshots per project, and only Collage uses all four (Split uses two).
- **Copy** needs a browser that can write images to the clipboard. If it is blocked, click the page once and try again, or use **Download**.
- Fonts come from Google Fonts and are all under the SIL Open Font License, so the images you export are yours to use anywhere.

## Related tools

- [Generators](/docs/tools/generators) for a script idea or a server name to put on the thumbnail.
- [fxmanifest Generator](/docs/tools/fxmanifest-generator) to finish the resource before release.
- [Inventory Icons](/docs/tools/inventory-icons) for the item pictures your script ships with.

_Last updated: 2026-09-22_

---

## Item Icons

URL: https://fivemad.com/docs/tools/item-icons

What Item Icons is: fivemad's sister site with 18,000+ FiveM and RedM item pictures, and how to use them with the Inventory Icons tool.

[Item Icons](https://items.rainmad.com) is the sister site of fivemad: a FiveM and RedM image gallery for inventory items and resources, with more than 18,000 item pictures ready for your inventory resource. It is linked in the fivemad header, the footer and the bar at the top of the page.

## What it is for

Every new item on a server needs a picture, and a blurry screenshot or a random web image stands out in an otherwise tidy inventory. Item Icons is where you browse for a picture of water, a burger, a phone, a lockpick, a bandage, a radio, an ID card and thousands of other items, and download the ones you want.

## Using the pictures on your server

1. Open [Item Icons](https://items.rainmad.com) and browse for the items you need.
2. Download the pictures.
3. Rename each file to your item name, or let the [Inventory Icons](/docs/tools/inventory-icons) tool do it for you (next section).
4. Put the files in your inventory's image folder, for example `ox_inventory/web/images/` or `qb-inventory/html/images/`, and add the matching item entries.

## Making your own pack with Inventory Icons

The [Inventory Icons](/tools/inventory-icons) tool on fivemad works well together with Item Icons:

- Drop the downloaded pictures on its **Your images** tab. File names become item names, so `Water Bottle.png` turns into `water_bottle`.
- It trims empty edges, pads and resizes every picture to the same icon size (100, 128, 256 or 512 px) and can export PNG or WebP.
- It writes the item list for ox_inventory, qb-inventory, ps-inventory, qs-inventory, codem-inventory or an ESX items table, and packs everything into one zip.

Item Icons pictures are a good choice when you want 256 or 512 px icons: the game prop pictures in Inventory Icons are only 160 px and look soft when upscaled, and the tool warns you about that.

> [!NOTE]
> Item Icons is a separate site. Questions about its pictures belong there or in the community Discord linked in the fivemad header, which is the same server Item Icons links to.

## Related tools

- [Inventory Icons](/docs/tools/inventory-icons) to trim, size and name pictures and export the item list.
- [Objects List](/docs/tools/objects-list) to find a game prop when you would rather use its picture.

_Last updated: 2026-09-22_

---

## Snaily Creator

URL: https://fivemad.com/docs/tools/snaily-creator

Dress up Snaily, the fivemad mascot: colours, moods, hats, shades, chains, outfits, shell stickers, props and backdrops, exported as PNG or SVG.

The Snaily Creator is a character builder for Snaily, our snail mascot. Set the colours, pick a mood, put a hat, shades, a chain and an outfit on it, stick something on the shell, give it something to hold, then export a transparent PNG or an SVG. Everything is drawn and rendered in your browser.

## What it is for

Server avatars, Discord profile pictures and emoji, forum signatures, release thumbnails, staff badges, stickers for your shop. Anywhere you want a small friendly character that is yours, without opening a drawing program.

## Quick start

1. Pick a starting point under the snail (**Street**, **Patrol**, **Late night dev** and so on), or leave the default snaily.
2. Open **Look** and set the colours, or press one of the colour presets.
3. Open **Face** and pick a mood. Happy, angry, bored, dead inside, dizzy, in love: fifteen of them.
4. Open **Wear** and click the parts you want. Click a part again to take it off.
5. Open **Export**, pick a size and press **Download PNG**.

Press **Surprise me** at any time for a complete random snail, and <kbd>Ctrl</kbd> + <kbd>Z</kbd> to undo it if the roll was bad.

## The tabs

| Tab | What it holds |
| --- | --- |
| Look | Body, spots, shell, swirl, eye white, pupil and mouth colours, eight colour presets, and the body spots switch. |
| Face | Fifteen moods, plus eyes, brows and mouth as separate pickers so you can mix your own, and the face extras (moustache, beard, cigarette, blush, sweat drop, angry mark, tear, freckles, plaster, scar). |
| Wear | Head, eyes, neck, outfit, shell and holding. Around seventy parts in total. |
| Scene | A backdrop behind the snail: sunburst, dots, stripes, spotlight, grid, confetti, blobs, speed lines or a plain colour. |
| Layers | Everything you added, in paint order. Move, hide, duplicate, recolour, remove. |
| Export | PNG, SVG, project file. |

## Working with layers

Click a hat, chain or sticker on the snail itself to select that layer, or pick it from the **Layers** list. A selected layer gets its own controls:

- **Left and right**, **Up and down** nudge it off its anchor point.
- **Size** scales it between 0.3x and 2.2x, **Rotation** spins it.
- The flip button mirrors it, the copy button duplicates it so you can wear two of the same part.
- **Colours** are per layer, so a cap can have a brim in a different colour than the crown.
- **Reset layer** puts it back where it started with its original colours.

The arrows on each row move a part in front of or behind the others. Shell stickers are trimmed to the shell and outfits are trimmed to the body, so you can push them around without them floating off the character.

## Export

| Output | Good for |
| --- | --- |
| PNG 512 | Discord emoji and server icons, forum avatars, small badges. |
| PNG 1024 | Discord profile pictures, stickers, Tebex and forum images. |
| PNG 2048 | Print, shirts, banners, anything you will scale down later. |
| SVG | Stays sharp at any size and stays editable in Figma, Illustrator or Inkscape. |
| Project file | A small `.json` you can load back here later or hand to someone else. |

Transparent is the default background. Switch to a solid colour when the place you are uploading to needs one, for example a Discord server icon. A backdrop layer paints over the background either way. **Copy image** puts the PNG straight on your clipboard, ready to paste into Discord.

## Tips

- Roll **Surprise me** a few times and keep the one you like, then fix the details in the Layers tab.
- A small rotation, five to ten degrees, makes a hat look worn instead of placed.
- Dark parts like a top hat or sunglasses disappear on a dark background. Recolour them or add a backdrop if the snail will sit on something dark.
- For a Discord emoji, export at 512 with a transparent background and pick parts that are still readable small: big shapes, strong colours, no thin details.
- Your snail is saved in this browser as you work. Save a project file if you want to keep more than one.

## Artwork

Every shape in this tool is original vector art drawn for fivemad, in the same flat cartoon spirit as our mascot. It is not taken from any art pack. What you export is yours to use for your server, your Discord, your release images or your merch.

## Privacy

The whole editor runs in your browser. Nothing is uploaded, the images are rendered on your own machine, and the autosave lives in this browser's local storage.

_Last updated: 2026-09-23_

---

## Crosshair Generator

URL: https://fivemad.com/docs/tools/crosshair-generator

Design a FiveM crosshair and export it as a NUI overlay resource, a transparent PNG, an SVG or the real cl_crosshair console settings.

The Crosshair Generator draws a crosshair in your browser and gives you four ways to use it: a complete NUI overlay resource, a transparent PNG, an SVG, and the FiveM console settings that come closest to it. Everything is rendered on your own machine and nothing is uploaded.

## Quick start

1. Pick a shape at the top of the controls, or a preset under the preview.
2. Set length, thickness, gap, colour, opacity and outline in the sections on the right.
3. Switch the preview background between the dark scene, the light scene and the two Los Santos views to check that it still reads.
4. Open **Output**, choose **NUI overlay**, and copy or download the three files.

Press **Surprise me** for a random crosshair, <kbd>Ctrl</kbd> + <kbd>Z</kbd> to undo it.

## The parts

Each section can be switched on or off on its own, so you can mix them freely. A ring around a T shape with a red dot is a normal thing to build here.

| Part | Controls |
| --- | --- |
| Lines | Length, thickness, gap, colour and opacity, which of the four arms are drawn, rounded ends, outline. |
| Centre dot | Size, colour and opacity, square or round, outline. |
| Circle | Radius, thickness, a cut out in degrees that breaks the ring into four arcs, colour and opacity, outline. |
| Brackets | Leg length, distance from the centre, thickness, colour and opacity, rounded ends, outline. |
| Chevrons | Width, distance from the centre, thickness, which of the four directions are drawn, rounded ends, outline. |
| Outline | One width, colour and opacity for the whole crosshair. Each part chooses whether it uses it. |

**Gap** is the distance from the centre of the screen to the inner end of each arm, in pixels. **Length** is the arm itself, so the outer tip sits at gap plus length.

## Shapes and presets

The shape buttons switch parts on and off, they do not throw your settings away. Pick **Circle** to add the ring to what you already have, pick **Cross** to go back.

| Preset | What it is |
| --- | --- |
| Minimal dot | A single small white dot with an outline. |
| Classic | The four line cross with a gap in the middle. |
| Classic and dot | The same cross with a centre dot. |
| Sniper | Long thin lines, a one pixel red dot and a wide broken ring. |
| Shotgun | A wide ring with short stubby arms. |
| Roleplay HUD | Soft white corner brackets and a small dot. |
| T shape | No top arm, so nothing covers the head of what you are aiming at. |
| Chevrons | Two arrows pointing at the centre. |

## Preview

- The **zoom** buttons (1x, 2x, 4x) only change the preview. Check the crosshair at 1x before you export it, that is the size it will be in game.
- The **spread** buttons show the crosshair while standing still, while moving and while firing. This is a preview of your **Spread** values, the game never does this by itself. The exported overlay can do it if you switch it on.
- The two Los Santos backgrounds are there to catch the usual mistake: a crosshair that looks great on a dark panel and disappears over concrete.

## Sharing and saving

Your crosshair is written into the address bar as you work, so **Copy share link** gives someone the exact crosshair you are looking at. It is also saved in this browser, so closing the tab does not lose it.

## The NUI overlay

The overlay is the output that works for everyone on your server, on any build, without touching anyone's settings.

Options:

- **Resource name**: the folder name, also what you put after `ensure` in your server.cfg.
- **Show it**: always, only while aiming, or only while armed.
- **Hide it in a vehicle**.
- **Hide the game reticule**: adds a loop that hides the game's own reticule while the resource runs. It does not change the player's settings.
- **Open it up while moving and firing**: adds a Lua loop that reads the player's speed and whether they are shooting and pushes the spread to the page.

You get three files:

```text
crosshair/
  fxmanifest.lua
  client.lua
  ui/
    index.html
```

Drop the folder in your `resources`, add `ensure crosshair` to your server.cfg (or whatever you named it) and restart. The page loads nothing from the internet: no fonts, no images, no scripts. It never takes mouse focus, so it cannot block anything.

> [!TIP]
> If you already have a HUD resource, you do not need a second one. Copy the `<div id="crosshair">` block and its styles out of the generated `index.html` into your own NUI page.

## PNG and SVG

- **PNG** exports at 128, 256 or 512 px with transparency. By default the crosshair is drawn at its real pixel size and centred, which is what you want when you are dropping it into an overlay or a HUD. Turn on the scale option when you want it to fill the image, for example for a release post.
- **SVG** is the same drawing as vectors. Use it in your own HTML, or open it in Figma or Inkscape.
- **Copy PNG** puts the image straight on the clipboard where the browser allows it.

## Console settings

GTA V has no crosshair commands. It has two options in Settings, Display, which FiveM exposes as convars:

| Setting | What it is |
| --- | --- |
| `profile_reticule` | Weapon Target. `0` is the simple dot, `1` is the complex crosshair that changes per weapon. |
| `profile_reticuleSize` | Simple Reticule Size. Values below zero shrink the simple dot until it is gone, and `-10` is what most people use to get rid of it. |

On top of that, the FiveM client draws a crosshair of its own behind `cl_customCrosshair`. It copies the Counter-Strike crosshair, so it can do four bars, a square centre dot, a black outline, one colour and one opacity. It has no circles, no brackets, no chevrons, no rounded ends and no second colour.

The **Console settings** tab maps your design onto those convars as closely as they go, lists everything that is lost on the way, and draws what the client will really produce next to your design so you can compare them.

Three things to know about them:

- They are a client setting, saved with the player's own FiveM settings. You cannot ship them to your players, and they stay set on every other server until the player changes them.
- The bar length and thickness are scaled by the player's vertical resolution, so pick your resolution in the tab before you copy the lines.
- The only one a server can control is `setr cl_customCrosshair false` in your server.cfg, which switches the built in crosshair off for everyone while they are on your server. Use it together with the overlay so players do not end up with two crosshairs.

> [!NOTE]
> Styles 0, 1 and 3 draw the same crosshair today, because the spread the dynamic styles react to is fixed in the client. Style 2 splits every bar into two pieces and pulls the inner pair into the centre. Style 4 is the one whose gap does not change with resolution, so it is the safest choice.

## Tips

- Keep a 1 px black outline. It is the difference between a crosshair you can see on a white car and one you cannot.
- Below 2 px thick, a line mostly disappears at 1080p.
- A large gap reads better for roleplay, where you are not shooting most of the time, and it keeps the middle of the screen clear.
- Green and cyan hold up almost everywhere on the map. Red disappears on brick and on brake lights.
- If you build a crosshair for a weapon shop or a minigame, export the PNG and use it as an image in your own NUI instead of shipping a second overlay resource.

_Last updated: 2026-09-23_

---

## server.cfg Generator

URL: https://fivemad.com/docs/tools/server-cfg-generator

Build a working FiveM server.cfg from a form: endpoints, OneSync, game build, keys, oxmysql, pma-voice, resource load order and ACE permissions.

The server.cfg Generator turns a form into a clean, commented `server.cfg` for FXServer. It covers networking, server list identity, OneSync, the enforced game build, security convars, keys, the oxmysql connection string, pma-voice convars, the `ensure` order for Standalone, QBCore, Qbox or ESX, and ACE permissions for your admins.

## What it is for

Most broken servers fail on something small in `server.cfg`: a resource started before its library, a missing license key, an admin line with the wrong identifier prefix, or a database password with an `@` in it. The generator writes the file in a fixed, readable order and shows warnings next to the output while you fill in the form, so you catch those before you start FXServer.

Use it when you set up a new server, when you move a server to a new framework, or when you want a clean reference file to compare your old one against.

## Quick start

1. Pick a **Framework** at the top: **Standalone**, **QBCore**, **Qbox** or **ESX Legacy**. This fills the **Resources** list and the tags, and adds the permission lines that framework needs. Any framework other than Standalone also turns on the **Database** and **Voice (pma-voice)** panels.
2. In **Server identity**, set `sv_hostname`, **Project name**, **Project description**, **Locale** and **Tags**.
3. In **Slots, network & game**, set `sv_maxclients`, **OneSync**, **Bind IP**, **Port** and `sv_enforceGameBuild`.
4. In **Keys & branding**, paste your `sv_licenseKey` from [portal.cfx.re](https://portal.cfx.re).
5. Under **Permissions (ACE)**, add yourself in **Admins** with your license, Discord or other identifier.
6. Read the amber warnings above the output, fix what applies, then use the download button on the `server.cfg` code block and save the file in your server-data folder, next to the `resources` folder.

> [!NOTE]
> Everything runs in your browser. The license key, Tebex secret and database password never leave your machine. The form is saved in this browser's local storage so you can come back to it. **Reset** puts every field back to the defaults.

## Options

### Framework presets

| Preset | Resources it fills | Tags | Admin group |
| --- | --- | --- | --- |
| Standalone | `mapmanager`, `chat`, `spawnmanager`, `sessionmanager`, `basic-gamemode`, `hardcap`, `baseevents` | `default` | `group.admin` |
| QBCore | the cfx defaults, then `oxmysql`, `ox_lib`, `qb-core`, `[qb]`, `[standalone]`, `[voice]`, `[defaultmaps]` | `roleplay, qbcore, qb-core` | `qbcore.god` |
| Qbox | `chat`, `hardcap`, `oxmysql`, `ox_lib`, `qbx_core`, `[ox]`, `[qbx]`, `[standalone]`, `[voice]` | `roleplay, qbox, ox` | `group.admin` |
| ESX Legacy | `chat`, `spawnmanager`, `sessionmanager`, `hardcap`, `oxmysql`, `ox_lib`, `es_extended`, `[core]`, `[standalone]`, `pma-voice` | `roleplay, esx` | `group.admin` |

Switching the framework replaces the **Resources** text and the tags. Admin rows that use a preset admin group are moved to the new framework's group; rows with a custom group are left alone.

### Server identity

| Field | Output | Notes |
| --- | --- | --- |
| `sv_hostname` | `sv_hostname "..."` | Shown in the server list. `^1` to `^9` are colour codes. Over 100 characters gets a warning. |
| Project name | `sets sv_projectName "..."` | Skipped when empty. |
| Project description | `sets sv_projectDesc "..."` | Skipped when empty. |
| Locale | `sets locale "en-US"` | 25 locales, including `root-AQ`. |
| Tags | `sets tags "..."` | Comma separated, trimmed and re-joined. |

### Slots, network and game

| Field | Output | Default |
| --- | --- | --- |
| `sv_maxclients` | `sv_maxclients 48` | 48 (slider and box, 1 to 2048) |
| OneSync | `set onesync on` | `on`. Also `legacy` or `off`. |
| Bind IP / Port | `endpoint_add_tcp` and `endpoint_add_udp` with `"0.0.0.0:30120"` | `0.0.0.0` and `30120` |
| `sv_enforceGameBuild` | `set sv_enforceGameBuild 3258` plus the DLC name as a comment | 3258 (Bottom Dollar Bounties). "Default (not enforced)" leaves the line out. |

The build list runs from 1604 (Arena War) to 3570 (Money Fronts). Setting a build unlocks the DLC vehicles, maps and clothing up to that update.

### Keys and branding

| Field | Output |
| --- | --- |
| `sv_licenseKey` | `sv_licenseKey "..."`, always written. Defaults to `changeme` with a comment pointing at portal.cfx.re. |
| `steam_webApiKey` | `set steam_webApiKey "none"` when empty. Only needed if you use Steam identifiers. |
| Server icon file | `load_server_icon logo.png`. A 96x96 PNG in the server-data folder. |
| Discord | `sets Discord "..."` |
| `banner_detail` URL | `sets banner_detail "..."` (1920x200 image on the server detail page) |
| `banner_connecting` URL | `sets banner_connecting "..."` (shown while connecting) |
| `sv_tebexSecret` | `sv_tebexSecret "..."`, only when filled in. |
| Extra sets variables | **Add variable** adds a key and value pair, written as `sets Key "value"`. Spaces in the key become underscores. |

### Security

| Option | Output | Default |
| --- | --- | --- |
| Running under txAdmin | Adds a txAdmin note at the top and leaves `rcon_password` out | On |
| `sv_endpointprivacy` | `sv_endpointprivacy true` (hides player IPs from other players) | On |
| `sv_scriptHookAllowed` | `sv_scriptHookAllowed 0` or `1` | Off |
| Private server | `sv_master1 ""` so the server is not listed in the server browser | Off |
| `sv_pureLevel` | Not set, `1` (blocks modified game files, allows audio and graphics mods) or `2` (blocks all modified files) | `1` |
| `sv_entityLockdown` | Not set, `relaxed` (blocks client created entities, allows script ones) or `strict` (only the server creates entities) | Not set |
| `rcon_password` | Only shown with txAdmin off. Empty writes a commented out line. | Empty |

### Database

The **Database** panel has an **Enabled** / **Off** switch. When on, it writes one line for oxmysql built from **Host**, **Port**, **User**, **Password** and **Database**. The user, password and database name are URL-encoded for you, and `charset=utf8mb4` is appended.

### Voice (pma-voice)

When enabled, it writes `setr` convars for pma-voice:

| Field | Convar |
| --- | --- |
| Audio mode | `voice_useNativeAudio true`, `voice_use2dAudio true`, or nothing for "pma-voice default" |
| Sending range only | `voice_useSendingRangeOnly` (default true) |
| Built-in UI | `voice_enableUi` (default 0) |
| Radio animation | `voice_enableRadioAnim` (default 1) |
| Range key / Radio key | `voice_defaultCycle "F11"` and `voice_defaultRadio "LMENU"` |

If voice is on but your resource list has neither `pma-voice` nor `[voice]`, the generator adds `ensure pma-voice` at the end of the resources.

### Resources

One entry per line. Plain names become `ensure name`. A `[folder]` name starts every resource in that folder. Lines starting with `#` stay as comments, and lines that already start with `ensure`, `start`, `stop`, `restart`, `exec`, `set`, `setr` or `sets` are kept as written. When `ox_lib` or `[ox]` is in the list, the generator adds `setr ox:locale "en"` above the resources and the ACE lines ox_lib needs.

### Permissions (ACE)

**Admins** rows take an identifier type (`license`, `license2`, `fivem`, `discord`, `steam`, `xbl`, `live`, `ip`), the identifier value, a group and an optional note. The `license:` style prefix in the value is optional; the tool strips it and writes the full `identifier.license:...` principal. **Custom rules** (toggle with **Show custom rules**) adds free `add_ace` rows with an allow/deny switch and `add_principal` rows.

## Output

The file is written in this order: header, Networking, Server identity, Slots and game, Security, Keys, Database, Voice, ox_lib, Resources, Permissions. With the default Standalone settings it looks like this:

```cfg title="server.cfg"
## Networking
endpoint_add_tcp "0.0.0.0:30120"
endpoint_add_udp "0.0.0.0:30120"

## Server identity
sv_hostname "^5My Server ^7| Serious RP | Discord: example"
sets sv_projectName "My Server"
sets sv_projectDesc "Serious roleplay with custom jobs and an active staff team"
sets locale "en-US"
sets tags "default"

## Slots and game
sv_maxclients 48
set onesync on
set sv_enforceGameBuild 3258      # Bottom Dollar Bounties

## Security
sv_scriptHookAllowed 0
sv_pureLevel 1                 # blocks modified game files, allows audio and graphics mods
sv_endpointprivacy true

## Keys
set steam_webApiKey "none"   # https://steamcommunity.com/dev/apikey
sv_licenseKey "changeme"   # https://portal.cfx.re

## Resources (load order matters)
# Default cfx resources
ensure mapmanager
ensure chat
ensure spawnmanager
ensure sessionmanager
ensure basic-gamemode
ensure hardcap
ensure baseevents

## Permissions
add_ace group.admin command allow            # all commands
add_ace group.admin command.quit deny        # but not quit
# add_principal identifier.license:xxxxxxxx group.admin   # add yourself here
```

With QBCore picked and an admin added, the extra sections look like this:

```cfg
## Database (oxmysql)
set mysql_connection_string "mysql://root:p%40ss@localhost:3306/fivem?charset=utf8mb4"

## Voice (pma-voice)
setr voice_useNativeAudio true
setr voice_useSendingRangeOnly true
setr voice_enableUi 0
setr voice_enableRadioAnim 1
setr voice_defaultCycle "F11"
setr voice_defaultRadio "LMENU"

## ox_lib
setr ox:locale "en"

## Permissions
add_ace group.admin command allow            # all commands
add_ace group.admin command.quit deny        # but not quit
add_ace resource.qb-core command allow
add_ace qbcore.god command allow
add_principal qbcore.god group.admin
add_principal qbcore.god qbcore.admin
add_principal qbcore.admin qbcore.mod
add_ace resource.ox_lib command.add_ace allow
add_ace resource.ox_lib command.remove_ace allow
add_ace resource.ox_lib command.add_principal allow
add_ace resource.ox_lib command.remove_principal allow

add_principal identifier.license:1a2b3c4d5e6f qbcore.god   # owner
```

### Starting the server

With txAdmin, point the deployer (or Settings, then FXServer) at this file. Without txAdmin, start FXServer from the server-data folder:

```bash
# Windows
C:\FXServer\server\FXServer.exe +exec server.cfg

# Linux
bash ~/FXServer/server/run.sh +exec server.cfg
```

## Warnings the tool shows

- `sv_licenseKey` is empty or still `changeme`.
- More than 32 slots with OneSync `off`.
- More than 48 slots: that needs an Element Club subscription linked to the license key.
- OneSync `legacy` is deprecated.
- A framework is picked but the database section is off.
- `sv_scriptHookAllowed 1` lets players run ScriptHook mod menus.
- The hostname is longer than 100 characters.
- The database has no password (fine for local testing only).
- No admin identifier is set.

## Tips

- Load order matters. Libraries such as `oxmysql` and `ox_lib` go before the framework core, and the core (`qb-core`, `qbx_core`, `es_extended`) goes before any script that uses it. `ensure [folder]` starts everything inside a bracketed folder in an order you do not control, so ensure dependencies by name before the folder.
- Check a permission in Lua with `IsPlayerAceAllowed(source, 'command.kick')`. After you change ACE lines you can paste them into the server console to apply them without a restart.
- Find identifiers in txAdmin (Players, then a player) or with `GetPlayerIdentifiers(source)`.
- `setr` convars are replicated to clients, `sets` convars are shown publicly in the server list, plain `set` stays on the server.

> [!WARNING] Keep secrets out of git
> `server.cfg` holds your license key and database password. Do not commit it to a public repo. Move secrets to a separate file and load it with `exec secrets.cfg`.

## Common mistakes

- **Starting FXServer with `+exec` while using txAdmin.** txAdmin starts the server itself. It still reads the port from the `endpoint_add_*` lines, so keep them.
- **Only opening TCP or only UDP.** The port needs both.
- **Changing `sv_enforceGameBuild` while players are on.** Clients download the matching game build on their next connect, so set it before launch.
- **Special characters in the database password.** They must be URL-encoded in `mysql_connection_string`. The generator does that, so do not encode them a second time.

## Limitations

The generator does not check that the resources you list exist in your `resources` folder, and it does not validate identifiers or keys. The framework presets are a starting point: rename folders to match your own server. The game build list stops at 3570.

## Related tools

- [fxmanifest.lua Generator](/docs/tools/fxmanifest-generator)
- [Server Status Checker](/docs/tools/server-status-checker)
- [Cfx Blacklist Checker](/docs/tools/cfx-blacklist-checker)
- [Artifacts](/docs/tools/artifacts)

_Last updated: 2026-09-22_

---

## fxmanifest.lua Generator

URL: https://fivemad.com/docs/tools/fxmanifest-generator

Generate a valid fxmanifest.lua: fx_version, game, lua54, shared, client and server scripts, NUI page, files, data_file lines, dependencies and exports.

The fxmanifest.lua Generator builds the manifest every FiveM or RedM resource needs. You fill in scripts, NUI page, files, `data_file` entries, dependencies and exports, and it writes a clean `fxmanifest.lua` with warnings for the mistakes that stop a resource from loading.

## What it is for

A manifest is short, but one wrong line costs you an hour: an NUI page that is not in `files`, a vehicle meta with a `data_file` line but no `files` entry. Use the generator when you start a new resource, when you turn a loose folder of add-on cars into a pack, or when you want to check an old `__resource.lua` style resource against a clean modern manifest.

## Quick start

1. Under **Start from**, pick **Basic script**, **NUI resource** or **Vehicle pack**. The preset keeps your **Name** and **Author** and fills the rest.
2. In **Resource**, set `fx_version`, the **Game** chips, **Name**, **Author**, **Version**, **Repository** and **Description**.
3. Add scripts in the **Scripts** panel. Type a path and press <kbd>Enter</kbd> or the plus button, or click one of the small `+ ...` shortcut buttons under each list.
4. For NUI, fill in `ui_page` and your web files under **NUI & files**.
5. Add `data_file` lines for meta files, and list **dependencies** and exports if you need them.
6. Fix anything in the amber warnings box, then download `fxmanifest.lua` from the code block and put it in the root of your resource folder.

Your manifest is saved in this browser, so you can come back and tweak it. **Clear** empties every field (it keeps `game 'gta5'`, `lua54 'yes'` and version `1.0.0`).

## Presets

| Preset | What it sets |
| --- | --- |
| Basic script | `shared_scripts` `config.lua`, `client_scripts` `client/*.lua`, `server_scripts` `server/*.lua` |
| NUI resource | `@ox_lib/init.lua` and `config.lua` in shared, client and server globs, `ui_page` `web/build/index.html`, files `web/build/index.html` and `web/build/**/*`, dependency `ox_lib` |
| Vehicle pack | `lua54` off, client script `vehicle_names.lua`, and six `data_file` lines for handling, vehicles, carcols, carvariations, vehiclelayouts and dlctext metas under `data/**/` |

## Options

### Resource

| Option | Output | Default |
| --- | --- | --- |
| `fx_version` | `fx_version 'cerulean'` | `cerulean (current)`. `bodacious` and `adamant` are there for old resources and trigger a warning. |
| Game | `game 'gta5'` for one game, `games { 'gta5', 'rdr3' }` for several | `gta5`. Picking `rdr3` also adds the required `rdr3_warning` line. `common` is for resources that run on any game. |
| Name, Author, Description, Version, Repository | `name '...'`, `author '...'` and so on | Version `1.0.0`. Empty fields are left out. |
| `lua54 'yes'` | `lua54 'yes'` | On. Lua 5.4 has been the default since mid 2025, so the line is optional on current servers, but keeping it does no harm and helps older artifacts. |
| `use_experimental_fxv2_oal` | `use_experimental_fxv2_oal 'yes'` | Off. Experimental faster native calls for Lua 5.4. Test before you ship. |

### Scripts

Three lists: `shared_scripts`, `client_scripts` and `server_scripts`. Each row can be edited in place, moved up with the arrow button or removed. Globs like `client/*.lua` work. The shortcut buttons add common entries:

| List | Shortcuts |
| --- | --- |
| shared_scripts | `@ox_lib/init.lua`, `@qbx_core/modules/lib.lua`, `@es_extended/imports.lua`, `@es_extended/locale.lua`, `config.lua`, `shared/*.lua`, `locales/*.lua` |
| client_scripts | `client/*.lua`, `@qbx_core/modules/playerdata.lua`, `client/main.lua` |
| server_scripts | `@oxmysql/lib/MySQL.lua`, `server/*.lua`, `server/main.lua` |

Order matters: scripts load in the order listed, and on each side `shared_scripts` load before the client or server scripts. Put `@ox_lib/init.lua` or `@qbx_core/modules/lib.lua` at the top of shared, and `config.lua` before any file that reads `Config`. Paths starting with `@` point into another resource.

### NUI and files

| Option | What it does |
| --- | --- |
| `ui_page` | Path inside the resource, or an `http(s)` URL for a dev server. |
| `files` | Files sent to clients. Globs like `**` work. Shortcuts: `html/**/*`, `web/build/**/*`, `stream/**/*.ytyp`, `locales/*.json`. |
| Add ui_page and data_file paths to files automatically | On by default. Copies the `ui_page` path (unless it is a URL) and every `data_file` path into `files { }`, because clients never download anything that is not listed there. |

### data_file

**Add data_file** adds a row with a type and a path. The type box suggests `HANDLING_FILE`, `VEHICLE_METADATA_FILE`, `CARCOLS_FILE`, `VEHICLE_VARIATION_FILE`, `VEHICLE_LAYOUTS_FILE`, `DLCTEXT_FILE`, `CONTENT_UNLOCKING_META_FILE`, `PED_METADATA_FILE`, `WEAPONINFO_FILE`, `WEAPON_ANIMATIONS_FILE`, `WEAPONCOMPONENTSINFO_FILE`, `LOADOUTS_FILE`, `AUDIO_GAMEDATA`, `AUDIO_SOUNDDATA`, `AUDIO_SYNTHDATA`, `AUDIO_WAVEPACK`, `DLC_ITYP_REQUEST` and `TIMECYCLEMOD_FILE`, but you can type any type. **+ Vehicle metas** adds the six vehicle meta lines that are not already there.

### Dependencies and exports

| Option | What it does |
| --- | --- |
| dependencies | Resources that must start first. Shortcuts: `oxmysql`, `ox_lib`, `ox_target`, `ox_inventory`, `qbx_core`, `qb-core`, `es_extended`, `/onesync`, `/gameBuild:3095`. Entries like `/onesync`, `/server:<artifact>` and `/gameBuild:<build>` set server requirements. |
| provide | Lets this resource stand in for another one, for example a `mysql-async` replacement. |
| exports (client) / server_exports | Old style export lists. `exports('name', fn)` in Lua works without them. |
| escrow_ignore | Files left readable when the resource goes through the Cfx.re asset escrow. Shortcuts: `config.lua`, `locales/*.lua`, `client/open.lua`, `server/open.lua`. |

## Output

The file comes out in this order: version and game lines, metadata, script blocks, `ui_page`, `files`, `data_file` lines, dependencies, `provide`, exports, `escrow_ignore`. The **Basic script** preset produces:

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'
lua54 'yes'

name 'my_script'
description 'Basic client/server script'
version '1.0.0'

shared_scripts {
    'config.lua',
}

client_scripts {
    'client/*.lua',
}

server_scripts {
    'server/*.lua',
}
```

A typical Qbox / ox_lib job resource:

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'
lua54 'yes'

name 'my_job'
version '1.0.0'

shared_scripts {
    '@ox_lib/init.lua',
    '@qbx_core/modules/lib.lua',
    'config.lua',
}

client_scripts {
    '@qbx_core/modules/playerdata.lua',
    'client/*.lua',
}

server_scripts {
    '@oxmysql/lib/MySQL.lua',
    'server/*.lua',
}

dependencies {
    'ox_lib',
    'qbx_core',
    'oxmysql',
}
```

The **Vehicle pack** preset, with automatic files on:

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

name 'my_vehicles'
description 'Add-on vehicle pack'
version '1.0.0'

client_scripts {
    'vehicle_names.lua',
}

files {
    'data/**/handling.meta',
    'data/**/vehicles.meta',
    'data/**/carcols.meta',
    'data/**/carvariations.meta',
    'data/**/vehiclelayouts.meta',
    'data/**/dlctext.meta',
}

data_file 'HANDLING_FILE' 'data/**/handling.meta'
data_file 'VEHICLE_METADATA_FILE' 'data/**/vehicles.meta'
data_file 'CARCOLS_FILE' 'data/**/carcols.meta'
data_file 'VEHICLE_VARIATION_FILE' 'data/**/carvariations.meta'
data_file 'VEHICLE_LAYOUTS_FILE' 'data/**/vehiclelayouts.meta'
data_file 'DLCTEXT_FILE' 'data/**/dlctext.meta'
```

For a vehicle pack, put models (`.yft`, `.ytd`) in a `stream` folder, they are streamed automatically. The `data/**/` globs let you keep one folder per car. Then add the resource to `server.cfg`:

```cfg
ensure my_vehicles
```

## Warnings the tool shows

- `@ox_lib/init.lua` is loaded but `lua54` is off.
- You load `@ox_lib/...` files but `ox_lib` is not in dependencies.
- You load `@oxmysql/lib/MySQL.lua` but `oxmysql` is not in dependencies.
- You load `@qbx_core/...` files in shared scripts but `qbx_core` is not in dependencies.
- `common` is combined with `gta5` or `rdr3`.
- `ui_page` is not in `files` (only when automatic files is off).
- `data_file` lines exist while automatic files is off: every path must also be in `files { }`.
- `fx_version` is not `cerulean`.
- The name contains spaces. The folder name is what counts for `ensure`.

## Common mistakes

- **Blank NUI frame.** `ui_page` must also be in `files`. Leave the automatic option on.
- **Shipping both manifests.** `fxmanifest.lua` replaced `__resource.lua`. Do not ship both in one resource.
- **RedM without the warning line.** `game 'rdr3'` needs the exact `rdr3_warning` text. The generator adds it for you.
- **Editing the manifest on a running server.** Run `refresh` and then `ensure your_resource` in the server console, or the old manifest stays in use.
- **Relying on `[folder]` order.** If your resource needs another one to start first, list it in dependencies instead of hoping the folder order is right.

> [!TIP]
> Keep the resource name and folder name the same, lowercase, with no spaces. `ensure` uses the folder name, and `name` in the manifest is only metadata.

## Limitations

The generator does not look at your resource folder, so it cannot tell whether the files and globs you list exist. It writes one manifest at a time. Everything happens in your browser.

## Related tools

- [server.cfg Generator](/docs/tools/server-cfg-generator)
- [Vehicle Handling Editor](/docs/tools/vehicle-handling-editor)
- [Vehicle Pack Validator](/docs/tools/vehicle-pack-validator)
- [Weapons Meta Editor](/docs/tools/weapons-meta-editor)
- [Vehicle Sirens Editor](/docs/tools/vehicle-sirens)

_Last updated: 2026-09-22_

---

## Vehicle Handling Editor

URL: https://fivemad.com/docs/tools/vehicle-handling-editor

Tune CHandlingData with sliders, import an existing handling.meta, toggle flag bits, and export handling.meta, runtime Lua or a carcols.meta mod kit.

The Vehicle Handling Editor lets you tune a vehicle's `CHandlingData` block with sliders and a one line explanation per field. You can start from a template or import your own `handling.meta`, flip handling, model and damage flag bits, and export a clean `handling.meta`, a runtime Lua script for live testing, or a `carcols.meta` mod kit for add-on cars.

## What it is for

Handling work is a loop: change a value, restart the resource, respawn the car, drive, repeat. The editor shortens that loop. You see every field with its unit and meaning, you see what you changed against the loaded values, and you can copy a Lua snippet that applies the new values to the car you are sitting in without a restart. When the car feels right, you download the final `handling.meta`.

It is also the quickest way to give an add-on car a mod kit, so it can take engine, brake, gearbox, suspension and armour upgrades.

## Quick start

1. Pick a template under **Start from template**, or click **Import handling.meta** and paste the file (or use **Open file**), then **Parse**.
2. Set **handlingName** so it matches `<handlingId>` in the car's `vehicles.meta`.
3. On the **Physics** tab, tune the values. A field you changed gets an amber dot and a **Reset** link that puts that one field back.
4. Switch to **Flags** for handling, model and damage flags, and to **Mod kit** if the car needs a `carcols.meta` kit.
5. Watch the **Driving profile** tiles on the right to see what the change does to top speed, drivetrain and grip.
6. Pick an output tab (**handling.meta**, **Lua** or **carcols.meta**), then copy or download it.

**Undo N changes** in the top bar puts every field back to the loaded template or import. Your work is saved in this browser.

## Templates

The templates are generic, hand-tuned starting points, not copies of base game cars.

| Template | Drive | Notes |
| --- | --- | --- |
| Sports car (RWD) | RWD | 1400 kg, 6 gears, drive force 0.30, flat vel 150 |
| Supercar (AWD) | AWD 30/70 | 1500 kg, 7 gears, drive force 0.36, flat vel 160, more grip |
| Compact (FWD) | FWD | 1100 kg, 5 gears, drive force 0.20, softer brakes and grip, AI `AVERAGE` |
| Sedan (RWD) | RWD | 1600 kg, 5 gears, soft suspension, AI `AVERAGE` |
| Muscle (RWD) | RWD | 1600 kg, drive force 0.32, extra wheelspin at launch, weak brakes |
| Off-road SUV (AWD) | AWD 50/50 | 2200 kg, long suspension travel, low off-road grip loss, off-road handling flag |
| Drift setup (RWD) | RWD | Sports car base with 55 degree steering lock, lower grip, stronger handbrake |

Loading a template keeps your current **handlingName**.

## Importing a handling.meta

Paste a whole `handling.meta` or a single `<Item type="CHandlingData">` block. If the file holds several vehicles, the editor lists them as chips ("N vehicles found, pick one") and you choose which one to load. Fields the editor does not have sliders for (for example `fDownforceModifier`) and the `SubHandlingData` block are kept and written back on export, so bikes, boats and planes keep their `CBikeHandlingData`, `CBoatHandlingData` or `CFlyingHandlingData` item untouched.

If you want to start from a real game vehicle, copy its `<Item type="CHandlingData">` block from the game's handling.meta and import that.

## Fields

The **Physics** tab has section chips (**All**, **Body & mass**, **Engine & gearbox**, **Brakes & steering**, **Traction**, **Suspension**, **Damage & fluids**, **Seat, value & AI**). Each field has a slider and a number box. The number box accepts values outside the slider range, which matters for imports that go past it.

### Body and mass

| Field | What it does | Slider range |
| --- | --- | --- |
| `fMass` | Weight in kg. Affects collisions and how much force is needed to move the car. | 50 to 30000 |
| `fInitialDragCoeff` | Air drag. Higher lowers the real top speed and slows the car when coasting. | 0 to 50 |
| `fPercentSubmerged` | How far it sinks in water before it floats, percent of height. | 0 to 100 |
| `vecCentreOfMassOffset` | x = right, y = forward, z = up, in metres. Negative z makes it harder to roll. | -2 to 2 per axis |
| `vecInertiaMultiplier` | Rotational inertia per axis. Higher is slower to pitch, roll or yaw. | 0 to 5 per axis |

### Engine and gearbox

| Field | What it does | Slider range |
| --- | --- | --- |
| `fDriveBiasFront` | 0.0 is RWD, 1.0 is FWD, anything between is AWD with that share at the front. | 0 to 1 |
| `nInitialDriveGears` | Number of forward gears. | 1 to 10 |
| `fInitialDriveForce` | Engine power at the wheels. The main acceleration value. | 0.01 to 2 |
| `fDriveInertia` | How fast the engine revs up. | 0.01 to 2 |
| `fClutchChangeRateScaleUpShift` | Up-shift speed. Higher shifts faster. | 0.1 to 15 |
| `fClutchChangeRateScaleDownShift` | Down-shift speed. | 0.1 to 15 |
| `fInitialDriveMaxFlatVel` | Gearing top speed on flat ground, roughly km/h. Drag decides the real top speed. | 0 to 500 |

### Brakes and steering

| Field | What it does | Slider range |
| --- | --- | --- |
| `fBrakeForce` | Brake strength. Around 1.0 is a strong sports car brake. | 0.01 to 5 |
| `fBrakeBiasFront` | Share of brake force on the front axle. 0.5 is even. | 0 to 1 |
| `fHandBrakeForce` | Handbrake strength. Higher locks the rear quicker. | 0 to 5 |
| `fSteeringLock` | Maximum steering angle in degrees. | 1 to 90 |

### Traction

| Field | What it does | Slider range |
| --- | --- | --- |
| `fTractionCurveMax` | Peak cornering grip. The main grip value. | 0 to 5 |
| `fTractionCurveMin` | Grip when sliding. Lower than max makes the car easier to break loose. | 0 to 5 |
| `fTractionCurveLateral` | Slip angle in degrees where peak grip is reached. | 0 to 45 |
| `fTractionSpringDeltaMax` | How far the tyre can flex before it loses grip, in metres. | 0 to 1 |
| `fLowSpeedTractionLossMult` | Wheelspin at launch. 0 is none. | 0 to 3 |
| `fCamberStiffnesss` | Grip from body roll when cornering, usually 0. | -1 to 1 |
| `fTractionBiasFront` | Grip distribution. Below 0.5 gives the rear more grip. | 0 to 1 |
| `fTractionLossMult` | Grip loss on dirt and grass. Lower keeps road grip off-road. | 0 to 3 |

### Suspension

| Field | What it does | Slider range |
| --- | --- | --- |
| `fSuspensionForce` | Spring stiffness. | 0 to 10 |
| `fSuspensionCompDamp` | Damping when the spring compresses. | 0 to 5 |
| `fSuspensionReboundDamp` | Damping when the spring extends. | 0 to 5 |
| `fSuspensionUpperLimit` | How far the wheel moves up from rest, metres. | -0.5 to 0.5 |
| `fSuspensionLowerLimit` | How far the wheel drops from rest, negative values. | -0.5 to 0.5 |
| `fSuspensionRaise` | Ride height offset. Negative lowers the car. | -0.3 to 0.3 |
| `fSuspensionBiasFront` | Spring force distribution. Above 0.5 is stiffer at the front. | 0 to 1 |
| `fAntiRollBarForce` | Anti-roll bar strength. Higher reduces body roll. | 0 to 3 |
| `fAntiRollBarBiasFront` | Anti-roll bar distribution. | 0 to 1 |
| `fRollCentreHeightFront` / `fRollCentreHeightRear` | Roll centre heights. Higher reduces roll but can tip the car. | -0.5 to 1 |

### Damage and fluids

| Field | What it does | Slider range |
| --- | --- | --- |
| `fCollisionDamageMult` | Damage from collisions. | 0 to 5 |
| `fWeaponDamageMult` | Damage from weapons. | 0 to 5 |
| `fDeformationDamageMult` | Visual body deformation. 0 keeps the body straight. | 0 to 5 |
| `fEngineDamageMult` | Engine damage from hits. | 0 to 5 |
| `fPetrolTankVolume` | Tank size in litres. Fuel scripts often read it. | 0 to 200 |
| `fOilVolume` | Oil volume. Affects how long the engine smokes before it dies. | 0 to 20 |

### Seat, value and AI

`fSeatOffsetDistX`, `fSeatOffsetDistY` and `fSeatOffsetDistZ` move the driver seat position (-1 to 1 m). `nMonetaryValue` is the base value used for things like insurance and sell price. **AIHandling** picks how AI drivers handle the car: `AVERAGE`, `SPORTS_CAR`, `TRUCK` or `CRAP` (an imported value that is not in this list is kept as an extra option).

## Flags

The **Flags** tab has three panels: **Handling flags** (`strHandlingFlags`), **Model flags** (`strModelFlags`) and **Damage flags** (`strDamageFlags`). Click a bit to toggle it, or type the hex value in the box at the top right of the panel. Each bit shows its name, a short description and its hex mask.

Some common ones:

| Flag | Mask | What it does |
| --- | --- | --- |
| `HF_HAS_RALLY_TYRES` | `0x8` | Better grip on loose surfaces |
| `HF_NO_HANDBRAKE` | `0x10` | Handbrake disabled |
| `HF_CVT` | `0x1000` | No gear shifts |
| `HF_OFFROAD_ABILITIES` | `0x100000` | Better off-road grip |
| `HF_FORCE_NO_TC_OR_SC` | `0x2000000` | Disables traction and stability control |
| `MF_ABS_STD` | `0x10` | ABS fitted as standard |
| `MF_NO_WHEEL_BURST` | `0x2000000` | Bulletproof tyres |
| `DF_BONNET` | `0x10` | Bonnet cannot break off |

Model flag changes usually need the vehicle to be respawned.

## Mod kit

The **Mod kit** tab builds a `carcols.meta` with one kit. An add-on vehicle needs a kit before it can take performance upgrades or show up properly in tuning menus.

| Option | What it does | Default |
| --- | --- | --- |
| Kit id | Must be unique across every vehicle on the server. | 1450 |
| Kit type | `MKT_STANDARD`, `MKT_SPECIAL`, `MKT_SPORT` or `MKT_SUV` | `MKT_STANDARD` |
| Kit name | Empty uses `<id>_<handlingname>_modkit`, for example `1450_mycar_modkit`. | Empty |
| Stat mods | A toggle per upgrade with comma separated modifier values, one per level. | Engine `25, 50, 75, 100`, Brakes `25, 50, 100`, Transmission `25, 50, 100`, Suspension `25, 50, 75, 100`, Armour `20, 40, 60, 80, 100` |

Picking the **Mod kit** tab switches the output to **carcols.meta**.

## Driving profile

The tiles on the right are estimates from the current values:

| Tile | What it shows |
| --- | --- |
| Top speed (est.) | Gearing limit from `fInitialDriveMaxFlatVel`, in km/h and mph. Drag and power decide where the car really tops out. |
| Drivetrain | RWD, FWD or AWD with the front/rear split, plus the gear count. |
| Force per tonne | Drive force relative to mass, for comparing cars. |
| Weight | Mass and drag. |
| Brake bias | Front brake share and brake force. |
| Grip | Max and min traction, plus the front grip bias. |

## Output

### handling.meta

The **handling.meta** tab gives a complete file with one item. Floats are written with six decimals and flags as hex without `0x`. If the loaded handling had no `SubHandlingData`, three `NULL` items are added.

```xml title="handling.meta"
<?xml version="1.0" encoding="UTF-8"?>
<CHandlingDataMgr>
  <HandlingData>
    <Item type="CHandlingData">
      <handlingName>MYCAR</handlingName>
      <fMass value="1400.000000" />
      <fInitialDragCoeff value="8.000000" />
      <fPercentSubmerged value="85.000000" />
      <vecCentreOfMassOffset x="0.000000" y="0.000000" z="0.000000" />
      <vecInertiaMultiplier x="1.000000" y="1.000000" z="1.000000" />
      <fDriveBiasFront value="0.000000" />
      <nInitialDriveGears value="6" />
      <fInitialDriveForce value="0.300000" />
      <!-- ...every other field in the same style... -->
      <nMonetaryValue value="100000" />
      <strModelFlags>440010</strModelFlags>
      <strHandlingFlags>20000</strHandlingFlags>
      <strDamageFlags>0</strDamageFlags>
      <AIHandling>SPORTS_CAR</AIHandling>
      <SubHandlingData>
        <Item type="NULL" />
        <Item type="NULL" />
        <Item type="NULL" />
      </SubHandlingData>
    </Item>
  </HandlingData>
</CHandlingDataMgr>
```

Load it in a resource like this:

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

files {
    'data/handling.meta',
}

data_file 'HANDLING_FILE' 'data/handling.meta'
```

Restart the resource and respawn the vehicle. Handling is read when the vehicle is created, so a car that was already out keeps the old values.

### Lua

The **Lua** tab writes a client script that applies the values with `SetVehicleHandlingFloat`, `SetVehicleHandlingInt` and `SetVehicleHandlingVector` on the `'CHandlingData'` class, then calls `ModifyVehicleTopSpeed(vehicle, 1.0)` so drive force and top speed changes apply right away.

| Option | What it does |
| --- | --- |
| Command / Function | **Command** adds a `RegisterCommand` that applies the handling to the vehicle you sit in. The box next to it sets the command name (default `handling`). **Function** returns just the `ApplyHandling(vehicle)` function. |
| Only changed fields | Emit natives only for values that differ from the loaded template or import. |

With **Only changed fields** on and two values changed:

```lua title="handling.lua"
-- Runtime handling for MYCAR (client side).
-- Values use handling.meta units: FiveM converts km/h, degrees and bias values itself.
-- Changes apply to this vehicle only and are lost when it is deleted or respawned.
local function ApplyHandling(vehicle)
    SetVehicleHandlingFloat(vehicle, 'CHandlingData', 'fInitialDriveForce', 0.35)
    SetVehicleHandlingFloat(vehicle, 'CHandlingData', 'fInitialDriveMaxFlatVel', 165.0)
    -- Commonly needed so drive force and top speed changes take effect right away.
    ModifyVehicleTopSpeed(vehicle, 1.0)
end

RegisterCommand('handling', function()
    local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
    if vehicle == 0 then
        print('You need to be in a vehicle')
        return
    end
    ApplyHandling(vehicle)
    print('Applied MYCAR handling')
end, false)
```

Run it on the client that owns the vehicle. You pass the same numbers you would write in handling.meta, FiveM converts them to the game's internal units. Floats always carry a decimal point (`165.0`, not `165`). The Lua output does not include `AIHandling`.

### carcols.meta

```xml title="carcols.meta"
<?xml version="1.0" encoding="UTF-8"?>
<CVehicleModelInfoVarGlobal>
  <Kits>
    <Item>
      <kitName>1450_mycar_modkit</kitName>
      <id value="1450" />
      <kitType>MKT_STANDARD</kitType>
      <visibleMods />
      <linkMods />
      <statMods>
        <Item>
          <identifier />
          <modifier value="25" />
          <audioApply value="1.000000" />
          <weight value="20" />
          <type>VMT_ENGINE</type>
        </Item>
        <!-- one Item per level and upgrade -->
      </statMods>
      <slotNames />
      <liveryNames />
    </Item>
  </Kits>
  <Lights />
</CVehicleModelInfoVarGlobal>
```

Then reference the kit in the car's `vehicles.meta` item and register the file:

```xml title="vehicles.meta"
<kits>
  <Item>1450_mycar_modkit</Item>
</kits>
```

```lua title="fxmanifest.lua"
data_file 'CARCOLS_FILE' 'data/carcols.meta'
```

## Common mistakes

- **handlingName does not match.** The value must equal `<handlingId>` in `vehicles.meta`, or the car keeps its old handling.
- **Fixing the spelling of `fCamberStiffnesss`.** It really has three s's. Spelling it "correctly" means the game ignores it.
- **Testing on a car that was already spawned.** Respawn after restarting the resource.
- **Flags with `0x`.** In handling.meta flags are hex without a prefix, for example `<strModelFlags>440010</strModelFlags>`.
- **Duplicate mod kit ids.** Two cars with the same kit id make tuning menus show the wrong parts.
- **Shipping only the Lua.** Runtime changes only affect that one vehicle and are gone when it is deleted. Ship the final values in handling.meta.

> [!TIP]
> Tune with the Lua command first: sit in the car, change a slider, copy the Lua, run it, drive. When it feels right, download handling.meta once.

## Limitations

The editor has sliders for 45 common `CHandlingData` fields plus the three flag sets and `AIHandling`. Other fields from an import are kept as they are but cannot be edited here. The driving profile numbers are estimates, not a physics simulation. Everything runs in your browser and nothing is uploaded.

## Related tools

- [fxmanifest.lua Generator](/docs/tools/fxmanifest-generator)
- [Vehicle Pack Validator](/docs/tools/vehicle-pack-validator)
- [Vehicle Sirens Editor](/docs/tools/vehicle-sirens)
- [Model Hash Browser](/docs/tools/model-hash-browser)

_Last updated: 2026-09-22_

---

## Clothing Designer

URL: https://fivemad.com/docs/tools/clothing-designer

How to open a clothing .ydd or .ydr with its .ytd files, paint on the 3D model or the UV layout with layers, and export ready to stream .ytd textures.

The Clothing Designer is a texture editor for FiveM clothing that shows your work on the real model. You open a drawable (`.ydd` or `.ydr`) with its `.ytd` texture files, or start from a game template, paint on the model or on the flat texture with layers, and export new `.ytd` files named the way the game expects. It is meant for server owners and clothing makers who want a new colourway, a logo on a top or a whole set of variations without a Photoshop and OpenIV round trip.

## What it is for

A typical job: you have a hoodie in your clothing pack and want a police, EMS and gang version of it. Normally you export the diffuse from the `.ytd`, paint it blind in an image editor while guessing where the UV islands land, convert it back to DDS and import it again. Here you paint straight on the 3D model (strokes go through the UVs into the texture), see the result live, add one texture slot per variation, and export every `.ytd` in one zip.

Everything runs in your browser. The files you drop are read locally and nothing is uploaded.

> [!NOTE]
> The editor needs a screen at least 1024 px wide. On a phone or small tablet the page only shows a 3D viewer for the game templates, with a note to open it on a PC to edit and export.

## Quick start

1. Open the [tool](/tools/clothing-designer). The start screen has **Choose files**, **Choose folder** and a row of game templates.
2. Drop the drawable and its textures, for example `jbib_004_u.ydd` with `jbib_diff_004_a_uni.ytd`, `jbib_diff_004_b_uni.ytd` and so on. A whole stream folder works too. If the folder holds several drawables you get a list (**Pick the drawable to edit**) showing vertex and texture counts; the textures are matched to the one you pick by name.
3. No files at hand? Click a template on the start screen or in the **Templates** tab.
4. Pick the **Brush** (<kbd>B</kbd>), choose a colour in the tool rail on the left and paint on the model or on the texture panel.
5. Press **Save** (<kbd>Ctrl</kbd> + <kbd>S</kbd>) to keep the project in this browser.
6. Press **Export**, set the drawable number and gender, and click **Export all (.zip)**.
7. Copy the `stream/` files from the zip into your clothing resource.

## Supported files

| Input | Notes |
| --- | --- |
| `.ydd` | Drawable dictionary, how the game and most packs ship clothing. A `.ydd` can hold several drawables, each shows up in the picker. |
| `.ydr` | Single drawable. |
| `.ydd.xml`, `.ydr.xml` | CodeWalker XML export, with its DDS folder. |
| `.ytd` | Texture dictionaries. Readable formats: DXT1, DXT3, DXT5, BC4 (ATI1), BC5 (ATI2), BC7 and A8R8G8B8. |
| PNG, JPG, WebP, GIF, DDS | Images for image layers. |
| TTF, OTF, WOFF, WOFF2 | Custom fonts for text layers. |
| `.fmcloth` | A project file saved by this tool. |

Binary files must be the legacy RSC7 resources FiveM uses. The highest LOD of the drawable is shown. Textures embedded in the drawable itself (common for props) are found too; if the diffuse is embedded, the export writes it as a separate `.ytd` and a warning under **Drawable details** says so.

Addon names with a collection prefix, like `mp_m_freemode_01_mypack^jbib_004_u.ydd`, work the same as plain names. Files that do not follow the freemode naming at all open as **Other drawable** and keep their own file and texture names on export.

> [!WARNING]
> Dropping only `.ytd` files does not work: the tool needs the model for the UV layout and the 3D preview. Drop the `.ydd` or `.ydr` together with its textures. If no diffuse texture is found, you paint on a blank grey texture and a warning tells you so.

## The workspace

The header shows the project name (click it to rename), the gender, and the item code like `jbib_004`. **Unsaved** appears when you have changes that are not saved. On the right: undo, redo, the keyboard shortcut list, full screen (<kbd>Esc</kbd> leaves it), **Save** and **Export**.

Below the header is the options bar for the active tool, the tool rail on the left, the two view panels in the middle and the sidebar on the right. The status bar at the bottom shows the cursor position in texture pixels, the UV island under the pointer, and vertex, triangle, geometry and UV island counts.

### 3D preview

The model with your texture as it is right now. Drag on the model to paint (with a painting tool active), drag the background to orbit, right drag to pan.

| Control | What it does |
| --- | --- |
| **Lit** / **Flat** | Lit uses preview shading. Flat is unlit and shows the texture colours as they are. |
| Wireframe | Draws the mesh edges on top. |
| Background | Cycles dark, mid and light. |
| **View** | Jumps to front, back, left or right. |
| Reset view | Back to the start camera. |

Ped clothing is shown in its bind pose without the body. Hats and glasses are turned upright for the preview only. The shading is a preview, not the game's ped shader.

### Texture panel

The texture at full size with the model's UV layout on top, so you see which part of the image lands where. Hover the model or the texture to highlight a UV island.

| Control | What it does | Default |
| --- | --- | --- |
| UV overlay | Shows or hides the UV wireframe. | On |
| **UV style** | Colour and opacity of the UV lines. | White, 35% |
| Pixel grid | Grid when zoomed in far. | On |
| Zoom out, zoom in, percentage | The percentage button fits the texture (<kbd>F</kbd>). | Fit |

Pan with <kbd>Space</kbd> + drag, <kbd>Alt</kbd> + drag (move tool) or the middle or right mouse button. The wheel zooms. Drag the divider between the panels to give one more room (25% to 75%), or hide a panel with its minimize button and bring it back from the thin bar at the side.

## Tools

The tool rail holds the tools and the primary and secondary colour (defaults `#d9463b` and white). <kbd>X</kbd> swaps them. Each tool has its settings in the options bar.

| Tool | Key | Options |
| --- | --- | --- |
| Move and transform | <kbd>V</kbd> | For image, text and shape layers: X, Y, W, H, Angle, flip horizontally, flip vertically, centre on the texture. Drag a paint layer to shift its pixels. |
| Brush | <kbd>B</kbd> | Colour, Size (1 to 600 px, default 32), Hardness (default 70%), Opacity, Pen pressure, Stay inside the UV island. |
| Eraser | <kbd>E</kbd> | Size (default 48), Hardness (default 80%), Opacity, Pen pressure, Stay inside the UV island. |
| Fill | <kbd>G</kbd> | Colour, mode (**Similar colour**, **UV island**, **Whole layer**), Tolerance (0 to 255, default 32) and sample **All layers** or **This layer** for similar colour, Opacity. |
| Gradient | <kbd>D</kbd> | Start and end colour, **Linear** or **Radial**, **Fade to transparent**. Each drag makes a new gradient layer. |
| Colour picker | <kbd>I</kbd> | Click to pick the primary colour, <kbd>Shift</kbd> + click for the secondary. <kbd>Alt</kbd> + click works with the brush too. |
| Text | <kbd>T</kbd> | Text colour. Click the texture or the model to place text; font, outline and curve are in the layer panel. |
| Shapes | <kbd>U</kbd> | Rectangle, ellipse, line, polygon, star. Fill and outline with their colours, outline width (1 to 200 px). <kbd>Shift</kbd> keeps the shape square (or snaps a line to 15 degrees), <kbd>Alt</kbd> draws from the centre. |
| Image | <kbd>P</kbd> | Opens a file picker. You can also paste an image with <kbd>Ctrl</kbd> + <kbd>V</kbd> or drop it on the texture. |

<kbd>[</kbd> and <kbd>]</kbd> change the brush or eraser size. **Stay inside the UV island** keeps a stroke on the island where it started, which is handy along seams.

Painting on the model stops at UV seams: a stroke that crosses a seam continues on the other island without joining up, so touch up seams in the texture view.

## Sidebar

The sidebar has three tabs: **Layers**, **Templates** and **Saved**.

### Slots

A slot is one texture variation of the drawable: `a`, `b`, `c`... Every slot has its own layer stack and becomes its own `.ytd`. **Add slot** offers **Copy of slot a** (the current one), **Base texture only** and **Solid primary colour**. Below the thumbnails you can change the letter of the active slot and see the texture name it will get on export, for example `jbib_diff_004_b_uni`. The trash button deletes the slot (the last one can not be deleted).

> [!IMPORTANT]
> The game reads texture variations in order from `a`. A gap (a, b, d) means missing textures in game. The export dialog warns about this and has a **Make a, b, c** button that renumbers the slots.

### Layers

The original texture is the bottom layer (**Base texture**), with an empty **Paint** layer above it. Paint on the layer above the base so the eraser always brings the original back.

Each row has visibility and lock toggles; double click a name to rename it, drag rows to reorder. The buttons below the list: move up, move down, **Duplicate** (<kbd>Ctrl</kbd> + <kbd>J</kbd>), **Merge down** (<kbd>Ctrl</kbd> + <kbd>E</kbd>), flip horizontally, flip vertically and **Delete layer**. The plus button adds a paint layer, the image button adds an image layer. <kbd>Ctrl</kbd> + <kbd>C</kbd> and <kbd>Ctrl</kbd> + <kbd>V</kbd> copy and paste a layer.

### Layer properties

Every layer has **Opacity** and **Blend**: Normal, Multiply, Screen, Overlay, Soft light, Hard light, Darken, Lighten, Color dodge, Color burn, Difference, Exclusion, Hue, Saturation, Color, Luminosity.

- **Text layers**: the text itself (multi line), font, **Size**, **Weight** (300 to 900), colour, alignment (Left, Centre, Right), **Italic**, outline colour and width, **Spacing**, **Curve** (minus 360 to 360 degrees, bends the text over an arc) and **Line height** for multi line text without curve. Built in fonts are Arial, Arial Black, Impact, Verdana, Tahoma, Trebuchet MS, Georgia, Times New Roman, Courier New, Comic Sans MS, Geist and Geist Mono. The upload button next to the font list adds your own `.ttf`, `.otf` or `.woff`; it is stored with the project. Double click a text layer on the texture to jump to its text box.
- **Shape layers**: **Width**, **Height**, **Radius** for rectangles, **Points** (3 to 48) for polygons and stars, fill and outline on or off with colours and outline width.
- **Gradient layers**: Linear or Radial, start and end colour, each with its own alpha. Drag the two dots on the texture to move the gradient.
- **Image layers**: show the source size. Drag the corner handles to scale (<kbd>Shift</kbd> frees the ratio), the round handle to rotate (<kbd>Shift</kbd> snaps to 15 degrees).

**Limit to UV islands** switches to island picking: click islands on the texture or the model to add or remove them, then press **Done**. The layer then only shows inside those islands, for example only the sleeves. **Clear** removes the limit. **Rasterize** turns a text, shape, gradient or image layer into plain pixels so you can paint on it.

**Drawable details** at the bottom lists the file, type, LOD shown, shaders, embedded textures, textures from the original `.ytd` that are kept as they are (normal and spec maps), and any load warnings.

### Templates

Freemode clothing from the base game, with the real UV layout and textures. Filter by **Male** or **Female**, by category (JBIB, LOWR, FEET, ACCS, TEEF, BERD, TASK, HAND, HATS) or search by name. A template opens with one slot per texture variation. Templates do not include the drawable file itself, see the Output section below.

### Saved

**Save** keeps the whole project (layers, fonts and your original files) in this browser's storage, with a 3D thumbnail. The Saved tab lists every project with **Continue**, rename, **Download project file** and delete, plus **Import file** to open a `.fmcloth` and **Delete all saved projects**. Saved projects stay in this browser only; download a `.fmcloth` to back one up or move it to another PC.

The page warns before you close it with unsaved changes. Undo keeps the last 80 steps.

## Export

**Export** opens a dialog with two columns.

### Drawable

| Field | What it does |
| --- | --- |
| **Number** | The drawable number, 0 to 999. Change it to place the item after your existing ones. |
| **Male** / **Female** | Picks `mp_m_freemode_01` or `mp_f_freemode_01` for the prefix and the zip name. |
| Drawable **_u** / **_r** | Universal or race specific drawable suffix (components only, not props). |
| **Texture race** | The race suffix on texture names: `uni`, `whi`, `bla`, `chi`, `lat`, `ara`, `bal`, `jam`, `kor`, `ita`, `pak`. |
| **Addon names with a collection prefix** | Adds `mp_m_freemode_01_<collection>^` (props: `mp_m_freemode_01_p_<collection>^`). On by default when your files had a prefix or you started from a template. |
| **Collection** | The collection name, default `my_clothes`. Lower case letters, digits and underscores only. |

For an **Other drawable** these fields are hidden and every file keeps its original name.

### Texture format

| Choice | Result |
| --- | --- |
| **Auto** (default) | DXT1 when the texture has no transparency, DXT5 otherwise. |
| **DXT1** | Always DXT1. |
| **DXT5** | Always DXT5. |
| **Uncompressed** | A8R8G8B8, 4x bigger. |

Every texture gets a full mip chain. Normal and spec maps that were inside your original `.ytd` files are copied as they were. Big textures (2048 px) take a few seconds to encode.

### Buttons

- **Export all (.zip)**: every slot as its own `.ytd`, the drawable renamed to your number and prefix, and a `README.txt`.
- **.ytd**, **PNG**, **DDS**: only the active slot, as a single file.
- **Project file (.fmcloth) with all layers**: the editable project.

## Output

The zip is named `<component>_<number>_<gender>.zip`, for example `jbib_004_male.zip`. With a collection prefix it contains:

```bash
stream/mp_m_freemode_01_my_clothes^jbib_004_u.ydd
stream/mp_m_freemode_01_my_clothes^jbib_diff_004_a_uni.ytd
stream/mp_m_freemode_01_my_clothes^jbib_diff_004_b_uni.ytd
README.txt
```

Props follow the prop naming: `p_head_000.ydd` and `p_head_diff_000_a.ytd`, without race suffix. The drawable is your original file, byte for byte, only renamed. Each `.ytd` holds the edited diffuse under the slot's texture name plus any other textures that were in the original `.ytd` for that variation.

When you started from a template the drawable is not in the zip. The README names the game file to copy (for base game items from `x64v.rpf/models/cdimages/streamedpeds_mp.rpf/mp_m_freemode_01/`, or `streamedpedprops.rpf` for props) and what to rename it to. Extract it with CodeWalker or OpenIV.

## Getting it into FiveM

1. Create a resource folder, for example `resources/[clothes]/my_clothes/`, with a `stream/` folder inside.
2. Copy everything from the zip's `stream/` folder into it. The drawable and its `.ytd` files must keep matching names: same component, same number, texture letters in order.
3. Addon clothing (with the collection prefix) also needs the ped variation file (`.ymt`) and usually a shop meta so the item shows up in clothing menus. Build them with the [YMT Creator](/docs/tools/ymt-creator), which reads the file names this tool writes.
4. Add the resource to `server.cfg` and restart.

A minimal manifest for an addon pack with a shop meta:

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

files {
  'mp_m_freemode_01_my_clothes.meta',
}

data_file 'SHOP_PED_APPAREL_META_FILE' 'mp_m_freemode_01_my_clothes.meta'
```

```cfg title="server.cfg"
ensure my_clothes
```

FiveM streams everything in `stream/` on its own, so the `.ydd` and `.ytd` files need no `files` entry.

> [!TIP]
> Only changed the textures of an item that is already in your pack? Keep the prefix and number the pack uses, export, and overwrite just the `.ytd` files. The `.ymt` does not change as long as the number of texture variations stays the same.

## Keyboard shortcuts

| Keys | Action |
| --- | --- |
| <kbd>V</kbd>, <kbd>B</kbd>, <kbd>E</kbd>, <kbd>G</kbd>, <kbd>D</kbd>, <kbd>I</kbd>, <kbd>T</kbd>, <kbd>U</kbd>, <kbd>P</kbd> | Move, brush, eraser, fill, gradient, picker, text, shapes, image |
| <kbd>[</kbd> and <kbd>]</kbd> | Brush size |
| <kbd>X</kbd> | Swap colours |
| <kbd>Ctrl</kbd> + <kbd>Z</kbd> | Undo |
| <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Z</kbd>, <kbd>Ctrl</kbd> + <kbd>Y</kbd> | Redo |
| <kbd>Ctrl</kbd> + <kbd>C</kbd> / <kbd>Ctrl</kbd> + <kbd>V</kbd> | Copy / paste layer (paste also takes images) |
| <kbd>Ctrl</kbd> + <kbd>J</kbd> / <kbd>Ctrl</kbd> + <kbd>E</kbd> | Duplicate layer / merge down |
| <kbd>Delete</kbd> | Delete layer (move tool) |
| Arrows | Nudge 1 px, with <kbd>Shift</kbd> 10 px (move tool) |
| <kbd>F</kbd> | Fit the texture |
| <kbd>Ctrl</kbd> + <kbd>S</kbd> | Save in this browser |

Shortcuts only work while the pointer is over the editor or it has focus, so the rest of the page keeps normal keys.

## Common mistakes

- **Gaps in texture letters.** Deleting slot `b` leaves `a, c`. Use **Make a, b, c** in the export dialog.
- **Mismatched numbers.** If you change **Number**, all files get the new number. Do not mix old and new files in `stream/`.
- **Soft alpha in DXT1.** With **Auto**, any pixel below full opacity makes the slot DXT5. If you forced DXT1, soft edges become hard cutouts.
- **Forgetting the drawable for templates.** A template export only has `.ytd` files. Copy the drawable from the game as the README says.

## Limitations

- Only the highest LOD is shown and painted. The drawable file is exported unchanged, so you can not edit geometry here.
- The 3D view is a preview, not the game's ped shader. Check the final look in game.
- Only the diffuse texture of each slot is edited. Normal and spec maps are passed through.
- Gen9 (Enhanced) resources are not read, only the legacy format FiveM uses.

## Related tools

- [YMT Creator](/docs/tools/ymt-creator) builds the `.ymt` and shop meta for addon clothing.
- [Texture Editor](/docs/tools/texture-editor) for any `.ytd`, with format and mip control.
- [YTD Optimizer](/docs/tools/ytd-optimizer) to shrink big clothing packs.
- [3D Tattoo Editor](/docs/tools/tattoo-editor) for tattoo overlays on the freemode ped.
- [Drawable Studio](/docs/tools/drawable-studio) for materials, lights and painting on CodeWalker XML exports.

_Last updated: 2026-09-22_

---

## 3D Tattoo Editor

URL: https://fivemad.com/docs/tools/tattoo-editor

How to place a tattoo on the freemode ped in 3D by zone, tune its uvPos, scale and rotation, and get the overlay XML or a Durty Cloth Tool project out of it.

The 3D Tattoo Editor lets you upload a tattoo image, pick a body zone and position it on `mp_m_freemode_01` or `mp_f_freemode_01` in 3D. You click the body to place it, fine tune the numbers, then copy the overlay XML or hand everything to Durty Cloth Tool. It is for anyone making addon tattoos who is tired of guessing `uvPos` values and restarting the game to check them.

## What it is for

GTA V tattoos are overlays: each one sits in a body zone (head, torso, each arm, each leg) and is placed by three values in the overlay XML:

| Value | Meaning |
| --- | --- |
| `uvPos` | Centre of the tattoo inside the zone, `x` and `y` from 0 to 1. |
| `scale` | Size, `x` and `y` from 0 to 1. |
| `rotation` | Angle in degrees. |

These numbers are hard to guess by hand. The editor shows the tattoo on the real freemode body while you move it, and what you see is where the game puts it.

## Quick start

1. Open the [tool](/tools/tattoo-editor). The male ped loads in the viewer.
2. Under **Tattoo image**, click **Upload tattoo image** or drop a PNG, JPG or WebP on it. No image yet? Click **No image at hand? Try a sample** for a test design with an arrow that shows which way is up.
3. Pick **Male** or **Female** and the **Zone**.
4. Click the body where the tattoo should go. The zone switches to the part you clicked and the position jumps there.
5. Fine tune with the **UV X**, **UV Y**, **Scale** and **Rotation (deg)** sliders, or type the numbers.
6. Set the **Overlay name** and **Collection**, then **Copy overlay XML** or press **Create in Durty Cloth Tool**.

## The viewer

Drag to orbit, scroll to zoom, click the body to place the tattoo there (a click only counts when you did not drag). The label in the top left shows the ped model and the current zone. The buttons in the top right:

| Button | What it does |
| --- | --- |
| Background colour | Colour picker for the viewer background (default near black). |
| Focus zone | Moves the camera to the current zone. The camera also moves there when you change zone. |
| Save screenshot | Downloads the current view as a PNG named `<overlay name>_<zone>.png`, for example `my_tattoo_zone_torso.png`. |

## Panels

### Tattoo image

Accepts PNG, JPG and WebP. A PNG with a transparent background works best, because everything that is not transparent shows on the skin.

Tattoo textures are square in GTA. When your image is not square, a dialog asks what to do:

- **Crop centre** cuts the largest centred square out of the image.
- **Fit with padding** keeps the whole image and pads the short side with transparency.

After loading you see a thumbnail with the file name and size, **Change** to pick another file, and the X to remove it. Uploading a file also fills the **Overlay name** from the file name (lower case, anything but letters, digits and underscores turned into `_`).

### Placement

| Control | What it does | Default |
| --- | --- | --- |
| **Male** / **Female** | Switches between `mp_m_freemode_01` and `mp_f_freemode_01`. | Male |
| **Skin tone** | Pale, Light, Medium, Tan, Brown, Dark. Preview only, it does not change the export. | Light |
| **Zone** | Head, Torso, Left arm, Right arm, Left leg, Right leg. | Torso |
| **Quick spots** | Preset positions for the current zone (see below). | |
| **UV X**, **UV Y** | The `uvPos` centre, 0 to 1 in steps of 0.001. | 0.5, 0.5 |
| **Scale** | One slider for both axes while **X + Y linked** is on. Click the lock to switch to **X and Y separate** and get **Scale X** and **Scale Y**. | 0.2, linked |
| **Rotation (deg)** | Minus 360 to 360. | 0 |
| **Show tattoo** | Hides the tattoo to compare with bare skin. | On |
| **Wrap around** | Continues the tattoo past the edge of the zone, the way the game does around limbs. | On |
| **Reset placement** | Back to the defaults above. | |

Each slider has a number box, so you can paste exact values from an existing overlay file.

### Quick spots

| Zone | Spots |
| --- | --- |
| Torso | Chest, Stomach, Upper back, Lower back, Right ribs, Left ribs |
| Head | Forehead, Left cheek, Right cheek, Left temple, Right temple |
| Left arm, Right arm | Shoulder, Upper arm, Forearm, Wrist, Hand |
| Left leg, Right leg | Thigh front, Thigh back, Shin, Calf, Ankle |

A quick spot only sets **UV X** and **UV Y**, scale and rotation stay as they are.

### How the zone coordinates run

Knowing this saves a lot of trial and error when you type values:

- `y` runs from bottom (0) to top (1): waist to neck on the torso, hand to shoulder on arms, ankle to hip on legs.
- On the torso, `x` wraps around the body: about 0.25 is the back, 0.5 the right side, 0.75 the chest, and both 0 and 1 are the left side.
- Arms and legs are mirrored on `x`, so the same values on the left and the right limb land on matching spots.

### Export

| Field | What it does | Default |
| --- | --- | --- |
| **Overlay name** | Written to `nameHash`, `txdHash` and `txtHash` in the XML, and used in the Lua snippet. | `my_tattoo` |
| **Collection** | Only used in the Lua snippet, as the collection argument. | `mpfivemad_overlays` |

Buttons:

- **Copy overlay XML** copies the `<Item>` block shown below the editor.
- **Create in Durty Cloth Tool** opens Durty Cloth Tool (v3.1 or newer must be installed) with the zone, gender and placement filled in. The tattoo image is passed through your clipboard, so allow clipboard access when the browser asks.
- **Copy share link** copies the page URL with the current gender, zone, skin tone and placement.

## Output

Below the panels you get two code blocks: the overlay item and a Lua snippet. With the defaults and an image named `dragon.png` on the torso:

```xml title="dragon_overlay.xml"
<Item>
  <uvPos x="0.500000" y="0.500000" />
  <scale x="0.200000" y="0.200000" />
  <rotation value="0.000000" />
  <nameHash>dragon</nameHash>
  <txdHash>dragon</txdHash>
  <txtHash>dragon</txtHash>
  <zone>ZONE_TORSO</zone>
  <type>TYPE_TATTOO</type>
  <faction>FM</faction>
  <garment>All</garment>
  <gender>GENDER_MALE</gender>
  <award />
  <awardLevel />
</Item>
```

```lua title="client.lua"
-- Apply the tattoo to the local player (collection = your overlay .ymt / dlc name)
local ped = PlayerPedId()
AddPedDecorationFromHashes(ped, `mpfivemad_overlays`, `dragon`)

-- Remove all tattoos
-- ClearPedDecorations(ped)
```

The tool does not make the `.ytd` itself. Durty Cloth Tool builds the `.ytd`, the overlay file and the stream folder for you; by hand you need to do those steps yourself.

## Getting it into FiveM

### With Durty Cloth Tool

Press **Create in Durty Cloth Tool** and follow its steps. Its [tattoo guide](https://docs.gta.clothing/getting-started/first-addon-tattoo) covers the resource it creates.

### By hand

1. Put your tattoo texture in a `.ytd` whose name matches `txdHash` (here `dragon.ytd`), with a texture inside named like `txtHash`. The [Texture Editor](/docs/tools/texture-editor) can build that dictionary from a PNG.
2. Add the copied `<Item>` to the `<presets>` list of your collection's overlay XML (the file name, without extension, is the collection name you pass to the natives).
3. Stream the `.ytd` and register the overlay file in your manifest.
4. Apply the tattoo in a script with `AddPedDecorationFromHashes` (or `AddPedDecorationFromHashesInCorona` in character creators).

A sketch of the resource:

```bash
my_tattoos/
  fxmanifest.lua
  overlays/mpfivemad_overlays.xml
  stream/dragon.ytd
```

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

files {
  'overlays/mpfivemad_overlays.xml',
}

data_file 'PED_OVERLAY_FILE' 'overlays/mpfivemad_overlays.xml'
```

> [!TIP]
> Tattoo shops read a separate shop list (`shop_tattoo.meta`) for prices and names. If you only apply tattoos from your own scripts, the overlay file and the `.ytd` are enough.

## Tips

- The URL always holds the current gender, zone, skin tone and placement (`?gender=MALE&zone=ZONE_TORSO&uvx=...`). Bookmark it or send it to a teammate to pick up where you left off. The image and the **Wrap around** setting are not part of the link.
- Keep **Wrap around** on for bands around arms and legs. Turn it off to see exactly where the tattoo gets cut at the zone edge.
- Make one version per gender. Female and male bodies differ, so place the tattoo on each and copy both items; the XML says `GENDER_MALE` or `GENDER_FEMALE`.
- Use **Save screenshot** for your store page or changelog.

## Common mistakes

- **Tattoo upside down or mirrored.** Use the sample image first: its arrow shows which way is up for each zone. Then flip or rotate your artwork, or use **Rotation (deg)**.
- **Scale too big.** A scale of 1 fills the whole zone. Most tattoos sit between 0.1 and 0.4.
- **Names that do not match.** `txdHash` must match the `.ytd` name and `txtHash` the texture inside it. Changing **Overlay name** changes all three.
- **Clipboard blocked.** If Durty Cloth Tool opens without the image, the browser did not allow clipboard access. Allow it and try again.

## Limitations

- Placement only. The tool does not write `.ytd` files or a complete overlay file.
- **Skin tone** tints the preview skin, it is not the game's skin shader.
- Everything runs in your browser. The image is not uploaded anywhere; for Durty Cloth Tool it goes through your own clipboard.

## Related tools

- [Clothing Designer](/docs/tools/clothing-designer) for painting clothing textures in 3D.
- [Texture Editor](/docs/tools/texture-editor) to build the tattoo `.ytd` from a PNG.
- [YMT Creator](/docs/tools/ymt-creator) for addon clothing files.
- [Hash Calculator](/docs/tools/hash-calculator) to get the joaat hash of an overlay or collection name.

_Last updated: 2026-09-22_

---

## Drawable Studio

URL: https://fivemad.com/docs/tools/drawable-studio

How to open a CodeWalker XML export (.ydr, .ydd, .yft) in 3D, check geometry and textures, edit shaders and lights, paint textures and export the result.

Drawable Studio opens a CodeWalker XML export of a model with its textures and shows it in 3D in your browser. You can check geometry, LODs and textures, change shader parameters and texture slots, add or move light effects, paint straight onto the model, and export the edited XML, the textures as DDS or PNG, or a GLB. It is for prop, vehicle and map makers who want to inspect or tweak a model without opening a 3D package.

## What it is for

- **Checking a model before you ship it.** Missing textures, empty LODs, wrong shader, a texture at 4096 that should be 1024: the Scene tab shows all of it at a glance.
- **Small material fixes.** Too shiny, normal map too strong, glow too weak: change `specularIntensityMult`, `bumpiness` or `emissiveMultiplier` and see it live.
- **Lamps on props.** Add a light to a streetlight or a sign, move it with a gizmo, set the hours it is on.
- **Quick texture touch ups.** Paint over a logo, fix a seam, recolour a part, then export the texture under its original name.

Everything is read in your browser. Nothing is uploaded.

## Export the model from CodeWalker

The tool reads CodeWalker's XML format, not the binary files.

1. Open CodeWalker's RPF Explorer (or the project window for your own files) and find the `.ydr`, `.ydd` or `.yft`.
2. Right click it and pick **Export XML**. CodeWalker writes `name.yft.xml` and a folder `name/` with the textures as DDS.
3. Vehicles and most props keep their textures in a separate `.ytd`. Export that one too; it gives you a `.ytd.xml` and the same kind of DDS folder.
4. Drop everything on the viewer together, or use **Choose folder**. Textures are matched to shaders by name, so the folder layout does not matter.

## Quick start

1. Open the [tool](/tools/drawable-studio).
2. Click **Choose folder** and pick the export folder, or drop it on the viewer. **Choose files** takes `.xml`, `.dds`, `.png`, `.jpg` and `.jpeg` files.
3. Wait for the progress bar (reading, parsing, decoding textures). A message tells you how many textures are missing, if any.
4. Look around, then switch between the **Scene**, **Materials**, **Lights** and **Paint** tabs on the right.
5. When you are done, press **Export XML**, **Package .zip** or **GLB** in the bar above the viewer.

> [!TIP]
> Forgot the texture folder? Drop the DDS files (or the folder) on the viewer while the model is open. They are added to the current model and the toast says how many missing textures they filled in.

## Inputs

| File | Used for |
| --- | --- |
| `.ydr.xml`, `.ydd.xml`, `.yft.xml` | The model. If a drop holds several model XML files, one model is opened. |
| `.ytd.xml` | Format info for textures that live in a separate dictionary. |
| `.dds` | Textures: DXT1, DXT3, DXT5, BC4, BC5, A8R8G8B8 and other uncompressed formats. |
| `.png`, `.jpg` | Textures too, matched by file name. |

BC7 textures are not supported yet; they show as unsupported in the texture list.

## The viewport

Drag to orbit, right drag to pan, the wheel zooms. Click a mesh to select it; its shader is selected in the Materials tab too.

Top left is the LOD switcher: **High**, **Med**, **Low**, **VLow**. LODs the file does not have are greyed out. Top right:

| Button | What it does |
| --- | --- |
| Background colour | Colour picker for the viewer background. |
| Wireframe | Draws the mesh edges. |
| Night preview | Dark sky, so lights and emissive shaders stand out. |
| Frame model | Moves the camera to fit the model. |
| Save screenshot (PNG) | Downloads the current view as `<model>.png`. |

The bottom bar shows vertices, triangles, shaders and textures for the current LOD, plus how many textures are missing.

The model is shown the way the game places it: rigid parts on their bones, vehicle wheels on every wheel bone. Skinned meshes (peds, most vehicle bodies) are shown in their bind pose. Missing textures render as a pink checker.

The bar above the viewport shows the file name, a counter of your changes, the export buttons and an X to close the file. Opening another file or closing with unsaved changes asks first.

## Scene tab

### Model

File name, type (Drawable, Drawable dictionary or Fragment), number of drawables, bones, lights and shaders, and how long the file took to read. Warnings from reading the file show here too.

### Display

| Option | What it does |
| --- | --- |
| **Textured**, **Clay**, **Normals**, **UV checker**, **Vertex colour** | View modes. Clay hides textures to judge the shape, UV checker shows stretching, Vertex colour shows the painted vertex data. |
| **Wireframe overlay** | Same as the viewport button. |
| **Ground grid** | On by default. |
| **Night preview** | Same as the viewport button. |
| **Paint colour** | Only for models with `vehicle_paint` shaders. Preview only: in game the colour comes from the vehicle's paint. |

### Geometry

Every geometry of the current LOD, grouped by drawable, with shader name and index, vertex and triangle count and the bone it sits on. The eye hides or shows a geometry, **Show all** and **Hide all** do it for the whole list, and **Solo** (in `.ydd` files) shows only one drawable. Click a row to select it in the viewport.

### Textures

A grid of every texture the shaders use, with format and size. The dot is green when the texture is fine, amber when you edited it, red when it is missing or could not be read. Click a texture to open the texture window:

- **Color**, **RGB** and **Alpha** channel views.
- **Used by**: which shader slots point at it.
- **File**: where it was loaded from.
- **PNG** and **DDS for CodeWalker** downloads.
- **Replace with image** (PNG, JPG or WebP) and **Revert changes**.

## Materials tab

Click a shader (or a mesh in the viewport) to expand it. Each shader row shows its index, name, `.sps` file, render bucket (opaque, alpha, decal, cutout and so on) and how many meshes use it. Pills tell you the alpha mode, glass, emissive (or emissive at night) and vehicle paint.

Inside you get every parameter:

- **Texture slots**: the texture name in a text field with suggestions from the loaded textures. Type another name to point the slot at a different texture. The image button replaces the texture's pixels with a PNG, JPG or WebP (the name stays the same). A download button appears once the texture is edited. The line below says the format and size, or `file not dropped`, or `unknown texture, add it to a .ytd`.
- **Vectors**: a single number for scalar values, with an **xyzw** button to edit all four components.
- **Arrays**: listed and kept as they are.

Parameters marked **live** change the preview: the diffuse, normal and spec maps, `bumpiness`, `specularIntensityMult`, `specularFalloffMult` and `emissiveMultiplier`. Every other change is written to the exported XML only. Hover a parameter name for a short hint (for example `specularFalloffMult`: specular tightness, higher is glossier). Each changed value has a reset button, and **Reset shader** undoes all changes of one shader.

**Textures for your .ytd** lists every texture you painted or replaced, with **DDS** and **PNG** downloads and where it belongs: embedded in the model, replace in the `.ytd`, or add to a `.ytd`. New texture names you typed into a slot that have no file show up as `needs a texture`.

The preview is an approximation, not the game's shaders. Check the final look in game.

## Lights tab

Shows the `<Lights>` block of the model as real lights in the scene. With several drawables that have lights, a **Drawable** selector picks which one you edit.

- **Add light** creates a point light above the model, sized to it.
- Each light row shows its colour, type, bone, intensity and range, with duplicate and delete buttons.
- **Night preview** dims the sky, **Light gizmos** shows or hides the light helpers.

Pick a light in the list or click it in the viewport. Move it with the gizmo (switch between move and rotate with the two buttons in the light's header) or type values.

| Section | Fields |
| --- | --- |
| Light | **Type** (Point, Spot, Capsule), **Colour**, **Intensity**, **Bone**, **Position**, **Direction**, **Tangent**. Spot lights add **Cone inner (deg)** and **Cone outer (deg)**, capsules add **Extent**. |
| On hours (TimeFlags) | 24 buttons, one per hour. **Always** and **Night 20 to 6** presets. |
| Falloff | **Range (m)**, **Falloff exponent**, **Flashiness** |
| Corona | **Size**, **Intensity**, **Z bias** |
| Volume | **Intensity**, **Size scale**, **Outer intensity**, **Outer exponent**, **Outer colour** |
| Shadows | **Blur**, **Near clip** |
| Fade distances | **Light**, **Shadow**, **Specular**, **Volumetric** |
| Advanced | **Flags**, **Light hash**, **Group id**, **Time flags**, **Projected texture**, plus any other fields the file has |

Positions and directions are relative to the bone in `BoneId`, the same as in the file. Light brightness in the viewer is an estimate.

## Paint tab

| Control | What it does | Default |
| --- | --- | --- |
| **Texture** | Which texture you paint on. Diffuse textures are listed first, others are marked `non-diffuse`. When you open the tab the largest diffuse is picked. | |
| **Pick on model** | Click a mesh in the viewport to paint its diffuse texture. | |
| Brush (<kbd>B</kbd>) | Paints the colour. | |
| Eraser (<kbd>E</kbd>) | Paints the original texture back. | |
| Fill (<kbd>G</kbd>) | Flood fill with **Tolerance** (0 to 128). | 24 |
| Eyedropper (<kbd>I</kbd>) | Picks a colour and switches back to the brush. | |
| Colour | Brush colour. | `#e23b3b` |
| **Size** | Brush size in texture pixels, up to half the texture size (max 512). | 48 |
| **Hardness** | Edge softness. | 0.6 |
| **Opacity** | Stroke opacity. | 1 |
| **Mirror X** | Paints the other side of a symmetric model too (3D view only). | Off |

Left drag on the model paints, right drag orbits, middle drag pans, the wheel zooms. **Texture view** shows the flat texture with an optional **UV wireframe**; you can paint there too. Below it: download `<texture>.png`, **DDS**, and **Revert to the original texture**.

Keys in the Paint tab: <kbd>Ctrl</kbd> + <kbd>Z</kbd> undo, <kbd>Ctrl</kbd> + <kbd>Y</kbd> or <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Z</kbd> redo, <kbd>[</kbd> and <kbd>]</kbd> brush size.

## Output

| Button | File | What is inside |
| --- | --- | --- |
| **Export XML** | Same name as the XML you opened, for example `prop_streetlight_01.ydr.xml` | The original file with only the values you changed rewritten. Everything else stays byte for byte, so diffs stay small. |
| **Package .zip** | `<model>_edited.zip` | The edited XML plus `<model>/<texture>.dds` for every texture you painted or replaced. |
| **GLB** | `<model>_<lod>.glb`, for example `adder_high.glb` | The current LOD with textures, for Blender or other tools. One way only. |

Exported DDS files keep the texture name and the format family of the original (DXT1, DXT5 or A8R8G8B8) and get a full mip chain. A DXT1 texture you painted with transparency becomes DXT5. When you replace a texture with an image of a different size, the XML export updates the size of embedded textures.

## Getting your edits back into the game

1. Extract **Package .zip** over your CodeWalker export folder, so the XML and the `<model>/` texture folder get replaced.
2. In CodeWalker, use **Import XML** and pick the `.ydr.xml`, `.ydd.xml` or `.yft.xml`. It builds the binary file again.
3. Textures that live in a separate `.ytd` are not part of the model. Open that `.ytd` in CodeWalker or OpenIV and replace the texture with the PNG or DDS of the same name, or use the [Texture Editor](/docs/tools/texture-editor). The Materials tab lists which textures need this.
4. Copy the rebuilt files into your resource's `stream/` folder and restart the resource.

```bash
my_props/
  fxmanifest.lua
  stream/
    prop_my_lamp.ydr
    prop_my_lamp.ytd
    my_props.ytyp
```

FiveM streams everything in `stream/` automatically. A new prop (not a replacement of a game model) also needs an archetype in a `.ytyp`, loaded from the manifest:

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

data_file 'DLC_ITYP_REQUEST' 'stream/my_props.ytyp'
```

The [YTYP Creator](/docs/tools/ytyp-creator) builds that file.

## Tips

- Drop the whole export folder, not single files. That way every texture, including the separate `.ytd` ones, is found in one go.
- Use **Clay** and **UV checker** to spot bad normals and stretched UVs before you blame the texture.
- For lights, turn on **Night preview** and set the hours with **Night 20 to 6** so street lamps do not burn at noon.
- **Solo** in a `.ydd` is the fastest way to check one drawable of a clothing or ped dictionary.

## Common mistakes

- **Only the XML dropped.** Every texture shows as a pink checker. Drop the texture folder on the open model.
- **Edited `.ytd` textures forgotten.** Painting a texture that lives in a separate `.ytd` does not change the model file. Export the DDS or PNG and put it into the `.ytd`.
- **Renamed texture that does not exist.** Typing a new name into a slot only changes the reference. Add a texture with that name to a `.ytd`, or the game draws nothing.

## Limitations

- Reads CodeWalker XML exports only, not binary `.ydr`, `.ydd` or `.yft` files.
- BC7 textures are not supported yet.
- Geometry can not be edited. Skinned meshes are shown in their bind pose.
- The 3D preview and the light brightness are estimates of the in game look.
- Everything runs in your browser and nothing is uploaded.

## Related tools

- [Texture Editor](/docs/tools/texture-editor) for editing the `.ytd` dictionaries that go with the model.
- [YTYP Creator](/docs/tools/ytyp-creator) for the archetype of a new prop.
- [Clothing Designer](/docs/tools/clothing-designer) for painting clothing with layers from binary `.ydd` files.
- [YTD Optimizer](/docs/tools/ytd-optimizer) to shrink texture memory.
- [Objects List](/docs/tools/objects-list) to find game props with pictures and 3D previews.

_Last updated: 2026-09-22_

---

## Weapons Meta Editor

URL: https://fivemad.com/docs/tools/weapons-meta-editor

Edit weapons.meta from the game's default values: damage, fire rate, range, falloff, clip size, recoil and flags, then export the meta files and fxmanifest.

The Weapons Meta Editor starts from the real default `weapons.meta` block of every base game and DLC weapon, lets you change damage, fire rate, range, reload, clip size, accuracy, recoil and flags with an explanation per field, compares everything against the game default, and exports a `weapons.meta`, a `weaponcomponents.meta`, an `fxmanifest.lua` and an optional runtime Lua script.

## What it is for

Weapon balancing on a FiveM server usually means copying a 200 line `<Item type="CWeaponInfo">` block, changing three numbers and hoping nothing else broke. This editor keeps the whole game block for you and only rewrites the fields you touch, so an edited weapon exports as the complete block with your changes in it. You see the default next to every value, derived stats like shots to down a player, and a list of every change you made across all weapons.

Typical jobs: lowering PvP damage on rifles, giving pistols less range, making a sniper semi auto, raising a magazine size, removing recoil shake, or checking what an old weapons.meta from a pack actually changes.

## Quick start

1. Pick a weapon in the list on the left. Use the search box or the **Weapons**, **Vehicle**, **Other** and **Edited** chips.
2. Change values with the slider or type a number. Changed fields turn amber, show a **changed** badge and a **Reset** link, and the game default is always shown next to the field name.
3. For magazine size, go to **Ammo & reload** and edit the clip under **Magazines (weaponcomponents.meta)**.
4. Edit as many weapons as you like. They all end up in one export.
5. On the right, open the **weapons.meta** tab (and **components** if you changed a clip), then download the files and copy the **fxmanifest** tab into your resource.
6. `ensure` the resource in `server.cfg`. Players need to reconnect to pick up the changes.

Your edits are saved in this browser. **Reset everything** in the top bar puts every weapon and clip back to the game defaults after a confirmation.

> [!TIP]
> You can link straight to a weapon with `?w=WEAPON_NAME`, for example `/tools/weapons-meta-editor?w=WEAPON_CARBINERIFLE`.

## The weapon list

The top bar shows the game build the defaults come from (build 3889) and how many weapons and clips you have edited.

| Chip | What it lists |
| --- | --- |
| Weapons | Hand weapons, grouped by weapon group (pistols, SMGs, rifles, MGs, shotguns, snipers, heavy, thrown, melee, stun gun). Custom weapons from an import show up here under **Imported**. |
| Vehicle | Vehicle weapons, grouped by the DLC they came with. |
| Other | Everything else in the game files that is not a hand or vehicle weapon. |
| Edited | Only the weapons that will be exported. The count is on the chip. |

Search matches the weapon name, label, group and DLC. Edited weapons carry an **edited** badge in the list.

## The editor

The header shows the weapon picture, label, internal name and which DLC and file the default comes from. **Reset weapon (N)** puts that one weapon back to default. For a custom imported weapon the button is **Remove** instead.

### Sections

The section chips filter the fields: **All**, **Damage**, **Fire**, **Range**, **Ammo & reload**, **Accuracy & recoil**, **Movement & misc**, and **Changed N**, which shows only the fields you changed on this weapon.

Melee and special weapons hide gun only fields like recoil and falloff. **Show every field** turns them on, and also adds an **Other fields** panel with every other single value field in the weapon's block (no descriptions there, change with care). Fields that identify the weapon (`Name`, `Model`, `Audio`, `Slot`, `Group`, `WheelSlot`, `StatName`, `HumanNameHash`, `PickupHash`, `MPPickupHash`) are never editable.

Numbers keep the game's style: a field that is a float in the game file stays a float with six decimals, an integer stays an integer. Sliders widen automatically when the default or your value is past the usual range.

### Damage

| Field | What it does |
| --- | --- |
| `Damage` | Base damage per bullet, or per hit for melee. A player goes down at 100 points of damage without armour. |
| `DamageType` | `BULLET`, `EXPLOSIVE`, `ELECTRIC`, `MELEE` and so on. |
| `NetworkPlayerDamageModifier` | Multiplier on Damage when the target is another player. The main PvP damage knob on a FiveM server. |
| `NetworkHeadShotPlayerDamageModifier` | Headshot multiplier against players. |
| `NetworkHitLimbsDamageModifier` | Arm and leg hit multiplier against players. |
| `NetworkPedDamageModifier` | Multiplier when a player hits an NPC in a network session. |
| `HeadShotDamageModifierPlayer`, `MaxHeadShotDistancePlayer` | Headshot multiplier against peds and the distance past which headshots count as body shots. |
| `HeadShotDamageModifierAI` | NPC headshot multiplier. The game default of 1000 makes NPC headshots near instant kills. |
| `HitLimbsDamageModifier`, `LightlyArmouredDamageModifier`, `VehicleDamageModifier` | Limb, light armour and vehicle damage multipliers. |
| `ArmouredVehicleGlassDamageOverride` | Damage to bulletproof glass per hit. -1 uses the per group value. |
| `MeleeDamageMultiplier` | Pistol whip or rifle butt damage. -1 keeps the default. |
| `Penetration` | How well bullets go through thin materials. |
| `Force`, `ForceHitPed`, `ForceHitVehicle`, `ForceHitFlyingHeli`, `FragImpulse`, `KillshotImpulseScale` | Physics push on objects, peds, vehicles, helicopters and breakables. |
| `KnockdownCount` | Hits needed to knock a ped over. -1 disables it. |
| `DamageTime` | Duration of damage over time effects, like the stun gun. |

### Fire

| Field | What it does |
| --- | --- |
| `FireType` | `INSTANT_HIT` for hitscan bullets, `PROJECTILE` for rockets and grenades, plus `MELEE`, `DELAYED_HIT`, `VOLUMETRIC_PARTICLE`, `NONE`. |
| `TimeBetweenShots` | Minimum time between shots in seconds. Lower fires faster. |
| `AlternateWaitTime` | Wait before the alternate fire (for example the double barrel's second shell). -1 is not used. |
| `BulletsInBatch`, `BatchSpread` | Pellets per shot and their spread. Each pellet deals the full Damage. |
| `Speed` | Bullet speed. Mostly affects tracers for hitscan weapons. |
| `SpinUpTime`, `SpinTime`, `SpinDownTime` | Minigun barrel timing. |

### Range

| Field | What it does |
| --- | --- |
| `WeaponRange` | Maximum distance a bullet can hit anything. |
| `LockOnRange` | Lock on distance (aim assist, homing launchers). |
| `DamageFallOffRangeMin` | Full damage up to this distance. |
| `DamageFallOffRangeMax` | Distance where damage reaches its lowest value. |
| `DamageFallOffModifier` | Damage multiplier at and past the max falloff range. 1.0 means no falloff. |
| `AiSoundRange` | How far NPCs hear the shot. -1 uses the group default. |

### Ammo and reload

| Field | What it does |
| --- | --- |
| `ClipSize` | Rounds per magazine, but only for weapons without a default clip component. |
| `AmmoInfo` | Ammo type the weapon uses and shares, picked from every ammo type in the game. |
| `ReloadTimeMP`, `ReloadTimeSP` | Reload time online and in single player. -1 lets the reload animation decide. |
| `AnimReloadRate` | Reload animation speed. Above 1.0 reloads faster. |
| `VehicleReloadTime` | Reload time when shooting from a vehicle. |
| `AmmoDiminishingRate` | Ammo drain for things like the jerry can and fire extinguisher. |

Under the fields, **Magazines (weaponcomponents.meta)** lists every clip component the weapon can attach, marks the default clip and shows each default size. Change a number there to change the real magazine size.

### Accuracy and recoil

`AccuracySpread`, `AccurateModeAccuracyModifier`, `RunAndGunAccuracyModifier`, `RunAndGunAccuracyMinOverride`, `RecoilAccuracyMax`, `RecoilErrorTime`, `RecoilRecoveryRate`, `RecoilShakeAmplitude` (camera shake strength), `RecoilShakeHash` and `RecoilShakeHashFirstPerson` (picked from the shakes the game uses), `MinTimeBetweenRecoilShakes` in ms, and `BulletDirectionOffsetInDegrees`.

### Movement and misc

`CameraFov`, `ZoomFactorForAccurateMode`, `FirstPersonScopeFov`, `ExpandPedCapsuleRadius`, and the weapon wheel bars `HudDamage`, `HudSpeed`, `HudCapacity`, `HudAccuracy` and `HudRange` (display only).

**WeaponFlags** also lives here. Current flags show as chips: click one to remove it. Flags you removed from the default stay visible crossed out, click to add them back. **Add a flag...** lists every flag the game uses, with a short description for the common ones:

| Flag | What it does |
| --- | --- |
| `Automatic` | Keeps firing while the trigger is held. |
| `OnlyFireOneShotPerTriggerPress` | Semi auto: one shot per press. |
| `Silenced` | Silent weapon, no gunshot events for AI. |
| `ArmourPenetrating` | Ignores body armour. |
| `IgnoreHelmets` | Headshots ignore helmets. |
| `NonLethal` | Does not kill (stun gun style). |
| `FirstPersonScope` | Scope overlay in first person. |
| `HiddenFromWeaponWheel` | Not shown in the weapon wheel. |

## Derived stats

The **Derived stats** panel shows estimates worked out from the meta values, with the old value under a tile when you changed it.

| Tile | Meaning |
| --- | --- |
| Damage per shot | Damage, times the pellet count for shotguns. |
| Fire rate | Rounds per minute. For semi auto weapons it is a cap, you cannot click faster. |
| Burst DPS | Every bullet hitting, no falloff, no armour. |
| Empty a clip | Time to fire the whole default magazine. |
| Reload | `ReloadTimeMP`, or "animation" when it is -1. With a real reload time you also get DPS including reloads. |
| Shots to down a player | Body shots with no armour, using `NetworkPlayerDamageModifier`, plus the headshot count. |
| Full damage to / Max range | Falloff start, the damage left at the falloff max, and `WeaponRange`. |

For guns a falloff chart shows damage over distance for the current values against the default. Melee weapons get **Damage per hit**, **Hits to down a player** and **Range** instead.

These numbers ignore scripts that change damage modifiers, armour, limb hits and animation timing, so treat them as a comparison tool, not the final truth.

## Importing an existing weapons.meta

Click **Import weapons.meta**, paste the file or use **Open file**, then **Parse**. You can paste a whole file or a single `<Item type="CWeaponInfo">` block, and a `weaponcomponents.meta` works too (clip sizes are picked up).

- Base game weapons are compared against their defaults, so you see exactly what the file changes. Their block becomes the new base for that weapon.
- Weapons that are not in the base game (add-on guns) are added as custom weapons under **Imported** and exported as they are.
- The result line tells you how many weapons were loaded, how many differ from the game default, how many are not in the base game, and how many clip components were read.

## Output

The right column has five tabs.

| Tab | What you get |
| --- | --- |
| weapons.meta | One file with only the weapons you changed, each as its complete block. |
| components | `weaponcomponents.meta` with the clip components you changed. |
| fxmanifest | A ready `fxmanifest.lua` for the files you have. |
| Lua | A client script for the runtime alternative (damage and recoil shake only). |
| Changes | Every edited weapon and clip, field by field, default next to the new value, with a reset per field or per weapon. |

### weapons.meta

Weapons are placed in the same slot of the `<Infos>` list they sit in inside the game file:

```xml title="weapons.meta"
<?xml version="1.0" encoding="UTF-8"?>
<CWeaponInfoBlob>
  <SlotNavigateOrder />
  <SlotBestOrder />
  <TintSpecValues />
  <FiringPatternAliases />
  <UpperBodyFixupExpressionData />
  <AimingInfos />
  <Infos>
    <Item>
      <Infos />
    </Item>
    <Item>
      <Infos>
        <Item type="CWeaponInfo">
          <Name>WEAPON_PISTOL</Name>
          <Model>W_PI_PISTOL</Model>
          <!-- ...the rest of the game block, unchanged... -->
          <Damage value="30.000000" />
          <!-- ... -->
          <TimeBetweenShots value="0.370000" />
          <!-- ... -->
        </Item>
      </Infos>
    </Item>
    <Item>
      <Infos />
    </Item>
    <Item>
      <Infos />
    </Item>
  </Infos>
  <VehicleWeaponInfos />
  <WeaponGroupDamageForArmouredVehicleGlass />
  <Name>fivemad weapons</Name>
</CWeaponInfoBlob>
```

### weaponcomponents.meta

```xml title="weaponcomponents.meta"
<?xml version="1.0" encoding="UTF-8"?>
<CWeaponComponentInfoBlob>
  <Data />
  <Infos>
    <Item type="CWeaponComponentClipInfo">
      <Name>COMPONENT_PISTOL_CLIP_01</Name>
      <Model>w_pi_pistol_mag1</Model>
      <!-- ... -->
      <ClipSize value="16" />
      <ReloadData ref="RELOAD_DEFAULT_WITH_EMPTIES" />
    </Item>
  </Infos>
  <InfoBlobName>fivemad weapon components</InfoBlobName>
</CWeaponComponentInfoBlob>
```

### fxmanifest.lua

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

files {
    'weapons.meta',
    'weaponcomponents.meta'
}

data_file 'WEAPONINFO_FILE_PATCH' 'weapons.meta'
data_file 'WEAPONCOMPONENTSINFO_FILE' 'weaponcomponents.meta'
```

Put the meta files next to this `fxmanifest.lua` in one resource folder. `WEAPONINFO_FILE_PATCH` is the type commonly used to override base game weapons. Items replace the game's weapon by `<Name>`, which is why the export always ships the whole block.

### Lua (runtime alternative)

Damage and recoil shake can also be changed from a client script, without a meta file. The **Lua** tab writes that script for your `Damage` and `RecoilShakeAmplitude` changes, and lists the weapons whose other changes still need the meta file:

```lua title="client.lua"
-- client.lua (client side, runs for every player)
-- Damage is worked out on the shooter's client, so every client needs this, not just the server.

-- SetWeaponDamageModifier (game native 0x4757F00BC6323CFE) multiplies the weapon's base damage.
-- It is not reset when the resource stops, the value stays until something sets it again.
local damageModifiers = {
    [`WEAPON_PISTOL`] = 1.1538, -- Damage 26 -> 30
}

-- SetWeaponRecoilShakeAmplitude is a FiveM native, it writes RecoilShakeAmplitude directly.
local recoilAmplitude = {
    -- no RecoilShakeAmplitude changes
}

CreateThread(function()
    for weapon, modifier in pairs(damageModifiers) do
        SetWeaponDamageModifier(weapon, modifier)
    end
    for weapon, amplitude in pairs(recoilAmplitude) do
        SetWeaponRecoilShakeAmplitude(weapon, amplitude)
    end
end)
```

- `SetWeaponDamageModifier(weaponHash, multiplier)` multiplies the weapon's base damage on the client that runs it. It does not need to run every frame and it is not reset when the resource stops.
- `SetWeaponRecoilShakeAmplitude(weaponHash, amplitude)` is a FiveM native that sets RecoilShakeAmplitude directly. `GetWeaponDamageModifier` and `GetWeaponRecoilShakeAmplitude` read them back.
- `SetPlayerWeaponDamageModifier(player, modifier)` and `SetPlayerWeaponDefenseModifier(player, modifier)` scale damage per player for every weapon, useful for buffs, safe zones or jobs.

Damage is worked out on the shooter's client, so a runtime modifier has to run on every client. Use natives when you want to tune damage live or per situation. Use weapons.meta for everything else (fire rate, range, falloff, reload, accuracy, flags) and for values that should be the same for everyone from the moment they join.

## Common mistakes

- **Changing `ClipSize` in weapons.meta for a normal gun.** Most guns have a default clip component, and the game uses its `ClipSize` instead. Edit the magazine under **Ammo & reload** and ship the `weaponcomponents.meta`.
- **Shipping only the changed lines.** A partial `<Item>` breaks the weapon. Ship the whole block, which the export does for you.
- **Two resources editing the same weapon.** The one loaded last wins. Keep all weapon edits in one resource.
- **Expecting a resource restart to be enough.** Players have to reconnect to pick up meta changes.
- **Running the runtime Lua on the server.** It is client side and has to run on every client.

> [!NOTE]
> Nobody outside Rockstar has an official description of every CWeaponInfo field. The one line explanations are the community's best understanding plus what the values in the game files show. Test big changes in game.

## Limitations

Only single value fields can be edited. Nested blocks such as `OverrideForces`, attach points and the explosion table are kept as they are (an import that changes them still exports them). The derived stats are estimates. Everything runs in your browser and nothing is uploaded.

## Related tools

- [Weapon Stats](/docs/tools/weapon-stats)
- [fxmanifest.lua Generator](/docs/tools/fxmanifest-generator)
- [Damage Events](/docs/tools/damage-events)
- [Hash Calculator](/docs/tools/hash-calculator)

_Last updated: 2026-09-22_

---

## YTYP Creator

URL: https://fivemad.com/docs/tools/ytyp-creator

Build a .ytyp archetype file for custom props: drop CodeWalker model XML, get measured bounds, pick flags and lodDist, then convert and stream it.

The YTYP Creator writes the `CMapTypes` XML that declares your custom props to the game (one `CBaseArchetypeDef` or `CTimeArchetypeDef` per model). Drop the CodeWalker XML exports of your `.ydr`, `.yft` or `.ydd` models and it measures the bounds, fills in the texture dictionary and checks everything against the 33,071 game prop archetypes. It is for map makers and anyone who streams their own props.

## What it is for

A model in `stream/` is not a spawnable prop on its own. The game needs an archetype for it: a name, a draw distance, a bounding box and sphere for culling, the texture and physics dictionaries and a set of flags. That archetype lives in a `.ytyp`. Without one you get the classic problems: `CreateObject` does nothing, `IsModelValid` returns false, the prop is invisible in your ymap, or it vanishes at the edges of the screen because the bounds are wrong.

Typical uses:

- You exported a prop from Blender (Sollumz) or ZModeler and need a ytyp for it.
- You have a pack of 200 props and do not want to type 200 bounding boxes by hand.
- You want to copy the settings of a game prop (a door, a bin, a bench) onto your own model.
- You got a ytyp from someone else and want to check it, rename things or fix flags.

## Quick start

1. In CodeWalker's RPF Explorer, right click your model (`.ydr`, `.yft` or `.ydd`) and choose **Export XML**. Do the same for its `.ytd`.
2. Set **Name** in the **Ytyp** panel. This is also the file name: `stream/<name>.ytyp`.
3. In **Add archetypes**, stay on the **Files** tab, pick **Flags for new archetypes** and **lodDist for new archetypes (m)**, then drop the `.ydr.xml` files together with the `.ytd.xml` files.
4. Each model becomes one row in **Archetypes**. Open a row with the arrow button (**Edit all fields**) to see the notes and every field.
5. Fix whatever the issue list in the right column points out. Click an issue to jump to the archetype it is about.
6. In **Export**, download `<name>.ytyp.xml` from the **XML** tab.
7. Convert it to a binary `.ytyp` in CodeWalker (steps in the **Convert** tab), put it in `stream/` and add the `data_file` line from the **Resource** tab.
8. `ensure` the resource and reconnect.

## Adding archetypes

The **Add archetypes** panel has three tabs.

### Files

Drop zone for CodeWalker model exports. Accepted files:

| File | What happens |
|---|---|
| `.ydr.xml` | One archetype, `assetType` `ASSET_TYPE_DRAWABLE`. |
| `.yft.xml` | One archetype, `assetType` `ASSET_TYPE_FRAGMENT`. |
| `.ydd.xml` | One archetype per drawable in the dictionary, `assetType` `ASSET_TYPE_DRAWABLEDICTIONARY`, `drawableDictionary` set to the `.ydd` name. |
| `.ytd.xml` | Not an archetype. The texture names are read so `textureDictionary` can be matched and checked. |
| `.ytyp.xml` | Opened for editing. It replaces the current list (Undo brings the old one back). |

Binary files (`.ydr`, `.yft`, `.ydd`, `.ytd`, `.ytyp` without `.xml`) are refused with a message telling you to export them to XML first. Everything is read in the browser, nothing is uploaded.

The archetype name is the file name, lowercased, without the extension. `my_bench.ydr.xml` becomes `my_bench`. For a `.ydd`, each entry uses its own drawable name.

**Bounds.** The bounding box is filled in from the model, in model space with GTA axes (Z up), the same way game archetypes store them. The bounding sphere follows the rule every game prop follows: centre of the box, radius half the box diagonal. Open the row to read a note on where the bounds came from. If the model export has no geometry and no stored bounds, the box stays at zero and you type it yourself.

**textureDictionary.** Drop the model's `.ytd.xml` together with the model and the field is set to that dictionary. HD companions (`name+hi.ytd`, `name+hidr.ytd`) count as the base `name.ytd`. If you drop exactly one `.ytd`, every model without a better match uses it. If no dropped `.ytd` fits and the model needs outside textures, the field is set to the model name and a note tells you to rename it if your textures live elsewhere. Models with only embedded textures get an empty field. Textures the model needs that are missing from the chosen `.ytd` are listed in the notes, because those would render white.

**physicsDictionary.** Models with embedded collision get the archetype name here (what Sollumz writes too). Models without collision, and `.ydd` entries, leave it empty.

The two fields under the drop zone set the defaults for dropped models and for **Add empty**:

| Field | What it does | Default |
|---|---|---|
| Flags for new archetypes | Flag preset given to new rows. | `32` (Static) |
| lodDist for new archetypes (m) | Draw distance given to new rows. | `100` |

Both are remembered in your browser. When `.ytd` files have been dropped, a line lists the texture dictionaries seen with a **forget** link to clear them.

### Game prop

Search the 33,071 game prop archetypes by name (type at least 2 characters, underscores and spaces are the same). Each result shows a picture, the source ytyp, lod, flags and the size in metres. **Add** copies all the values.

By default the copy is named `<name>_custom` with a note telling you to rename it to your model and point `textureDictionary` at your `.ytd`. Tick **Keep the game name** only when you really want to re-declare the game prop itself, for example to make it spawnable everywhere.

### Import

Open a `.ytyp.xml` (button **Open .ytyp.xml**) or paste the XML and press **Load pasted XML**. It replaces the list. What is kept:

- `CBaseArchetypeDef` and `CTimeArchetypeDef` items become editable rows.
- Interior (`CMloArchetypeDef`) archetypes and items of unknown types are kept as raw XML and written back unchanged. The Ytyp panel shows how many.
- Archetype `extensions` (particles, audio, spawn points, doors) are kept as raw XML on their row.
- Non empty root blocks (`extensions`, `dependencies`, `compositeEntityTypes`) are kept as they are.
- A bounding sphere that does not follow the box rule is kept exactly, and "Sphere from box" is turned off for that row.
- Unknown fields inside an archetype are dropped, with a warning naming them.

## Archetype fields

Each row shows the name, the asset type (`ydr`, `yft`, `ydd`), the size in metres, and quick inputs for **lodDist**, **txd** and **flags**. The buttons on the right are **Edit all fields**, **Duplicate** (adds `<name>_copy` right below) and **Delete**. The Ytyp panel has **Undo** (last add, delete or import, up to 40 steps) and **Clear** (removes every archetype, undo works). The whole document is saved in your browser, so a reload keeps your work.

The expanded row has these fields:

| Field | Meaning | Default |
|---|---|---|
| Type | `CBaseArchetypeDef` or `CTimeArchetypeDef`. Time archetypes only show during the hours you tick. | `CBaseArchetypeDef` |
| `assetType` | `ASSET_TYPE_DRAWABLE` (.ydr), `ASSET_TYPE_FRAGMENT` (.yft), `ASSET_TYPE_DRAWABLEDICTIONARY` (.ydd), `ASSET_TYPE_ASSETLESS` (no model, MLOs), `ASSET_TYPE_UNINITIALIZED`. | from the file |
| `assetName` | Leave empty and the name is written again, like every game prop. | empty |
| `drawableDictionary` | Only for `.ydd` models: the `.ydd` name without extension. | empty |
| `textureDictionary` | The `.ytd` with the textures, without extension. | see above |
| `physicsDictionary` | Game props point at a shared physics dictionary. For a custom model with its collision inside, use the archetype name or leave it empty. | see above |
| `clipDictionary` | The `.ycd` with the animation or UV animation. Needs flag 512 or 1024. | empty |
| `specialAttribute` | Marks doors, bushes, traffic lights and a few others. | `0` |
| lodDist (m) | How far away the model is drawn. A ymap entity can override it (`-1` there means use this value). | `100` |
| hdTextureDist (m) | Where `+hi.ytd` / `+hidr.ytd` HD textures load. Keep it at or below lodDist. | `5` |
| bbMin / bbMax | The box used for culling and returned by `GetModelDimensions`. 6 decimals. | measured |
| Sphere from box | On: `bsCentre` and `bsRadius` are calculated from the box. Off: type them yourself. | on |
| flags | Number input, preset dropdown and one checkbox per bit. | `32` |
| timeFlags | Only for time archetypes. | `32505919` |

### specialAttribute values

`0` None, `3` Traffic light, `4` Unknown 4, `5` Garage door, `6` MLO water level, `7` Normal door, `8` Sliding door, `9` Barrier door, `10` Sliding door vertical, `11` Noisy bush, `12` Rail crossing barrier, `13` Noisy deformable bush, `14` Single axis rotation, `15` Dynamic cover bound, `16` Rumble on vehicle collision, `17` Rail crossing light, `30` Clock, `32` Street light. `1`, `2` (ladder) and `31` (tree) are listed as deprecated.

### Flag presets

| Preset | Value | Used for |
|---|---|---|
| Static | `32` | Fixed prop that never moves. Simple and safe for custom props. |
| Vanilla static prop | `549584928` | Static, dynamic, no AI or player cover, ambient scale (`prop_wait_bench_01`). |
| Vanilla physics prop | `549584896` | Dynamic, no cover, ambient scale. Bins, cones, crates. |
| Dynamic + ambient scale | `537001984` | The most common non zero value in game ytyps. |
| Ambient scale only | `536870912` | Interior furniture and fixed decoration. |
| No flags | `0` | The most common value, mostly map furniture. |
| No shadows | `8192` | LOD models, emissive and light props. |
| Door | `604110848` | Door physics, dynamic, ambient scale. Pair with specialAttribute `7`. |
| UV animated | `1024` | Animated UVs from the clipDictionary (screens, water, scrolling signs). |

The bit checkboxes cover all 32 bits with CodeWalker's names, for example `2` Don't fade, `4` Draw last, `32` Static, `512` Has anim (YCD), `1024` UV anims (YCD), `2048` Shadow only, `8192` Don't cast shadows, `16384` Cast texture shadows, `65536` Double-sided rendering, `131072` Dynamic, `524288` Auto start anim, `4194304` No AI cover, `8388608` No player cover, `67108864` Enable door physics, `536870912` Use ambient scale.

### Time archetypes

Switch **Type** to `CTimeArchetypeDef` and a 24 hour grid appears. Bit 0 is 00:00 to 01:00, bit 23 is 23:00 to 24:00 (game time). Presets: **Night 19:00 to 06:00** (`33030207`), **Night 20:00 to 06:00** (`32505919`), **Day 06:00 to 20:00** (`1048512`), **Always** (`16777215`). The checkbox **16777216 Allow vanish whilst viewed** lets the model switch while it is on screen.

## Checks

The right column lists problems as you edit. Errors and warnings mark the row number in amber.

| Severity | Check |
|---|---|
| Error | Ytyp has no name; archetype without a name; duplicate archetype names; empty or invalid numbers; lodDist of 0 or less; negative hdTextureDist; bbMin larger than bbMax; zero size box (gets culled, invisible); file extension in a name or dictionary (`my_prop.ytd`); time archetype with no hours ticked. |
| Warning | Ytyp name with capitals or symbols (shows the sanitised name); ytyp name equal to a game ytyp; archetype name with characters other than lowercase a-z, 0-9, `_` and `-`; names over 63 characters; same name as a game prop; lodDist under 15 m; hdTextureDist larger than lodDist; manual sphere smaller than the box; no textureDictionary while the model needs outside textures; drawableDictionary and assetType disagree; assetName differs from name on a `.ydr`; animation flag without clipDictionary. |
| Info | textureDictionary not among the dropped `.ytd` files (and not a game txd); clipDictionary without an animation flag; door specialAttribute without flag `67108864`; embedded textures; lodDist above 1500 m; more than 3000 archetypes in one ytyp. |

Name clash checks run once the game archetype list has loaded.

## Output

### The XML

The **XML** tab shows `<name>.ytyp.xml` in the same layout CodeWalker exports. For a bench prop it looks like this:

```xml title="my_props.ytyp.xml"
<?xml version="1.0" encoding="UTF-8"?>
<CMapTypes>
 <extensions />
 <archetypes>
  <Item type="CBaseArchetypeDef">
   <lodDist value="60" />
   <flags value="32" />
   <specialAttribute value="0" />
   <bbMin x="-1.5877" y="-0.4547" z="0.0047" />
   <bbMax x="1.5877" y="0.4468" z="0.4543" />
   <bsCentre x="0" y="-0.00395" z="0.2295" />
   <bsRadius value="1.6656836" />
   <hdTextureDist value="5" />
   <name>my_bench</name>
   <textureDictionary>my_bench</textureDictionary>
   <clipDictionary />
   <drawableDictionary />
   <physicsDictionary>my_bench</physicsDictionary>
   <assetType>ASSET_TYPE_DRAWABLE</assetType>
   <assetName>my_bench</assetName>
   <extensions />
  </Item>
 </archetypes>
 <name>my_props</name>
 <dependencies />
 <compositeEntityTypes itemType="CCompositeEntityType" />
</CMapTypes>
```

If you type a hash instead of a name (`0x1234ABCD` or a plain number), it is written as `hash_1234ABCD`, the way CodeWalker writes unknown names. Time archetypes get a `<timeFlags value="..." />` line after `<extensions />`.

### Converting to binary

Browsers cannot write the binary ytyp format, so CodeWalker does the last step (also shown in the **Convert** tab):

1. Download `<name>.ytyp.xml` next to your models. Keep the double extension, CodeWalker reads the file type from it.
2. Open CodeWalker's **RPF Explorer**, then **File, Open Folder** on that folder.
3. Turn on **Edit mode**, then **Edit, Import XML** (or drag the file into the window).
4. CodeWalker writes `<name>.ytyp`. Put it in `stream/` and keep the `.xml` out of it.
5. Add the `data_file` line, `ensure` the resource and reconnect.

### Resource layout

The **Resource** tab builds a folder layout from your archetypes (model files by asset type, each `.ytd`, each `.ycd`) and this manifest:

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

name 'my_props'
description 'Custom props declared in my_props.ytyp'

-- Everything in stream/ (.ydr, .yft, .ydd, .ytd, .ytyp) is streamed on its own.
-- This line registers the archetypes when the resource starts, so the models
-- are valid everywhere (CreateObject, ymaps, map editors), not only near a ymap
-- that happens to depend on the ytyp.
data_file 'DLC_ITYP_REQUEST' 'stream/my_props.ytyp'
```

```text
my_props/
├── fxmanifest.lua
└── stream/
    ├── my_props.ytyp
    ├── my_bench.ydr
    └── my_bench.ytd
```

```cfg title="server.cfg"
ensure my_props
```

`DLC_ITYP_REQUEST` is the resource version of the game's `PERMANENT_ITYP_FILE`: the archetypes stay registered while the resource runs. Without it a ytyp only loads when a ymap that depends on it is loaded nearby.

## Examples

Check the archetype is registered and spawn the prop:

```lua title="client.lua"
local model = `my_bench`

RegisterCommand('bench', function()
    if not IsModelValid(model) then
        print('my_bench is not registered, check the data_file line and the ytyp name')
        return
    end
    RequestModel(model)
    while not HasModelLoaded(model) do Wait(0) end

    local ped = PlayerPedId()
    local pos = GetOffsetFromEntityInWorldCoords(ped, 0.0, 2.0, 0.0)
    local obj = CreateObject(model, pos.x, pos.y, pos.z, true, false, false)
    PlaceObjectOnGroundProperly(obj)
    FreezeEntityPosition(obj, true)
    SetModelAsNoLongerNeeded(model)
end)
```

`GetModelDimensions(model)` returns the `bbMin` and `bbMax` you set here, which is a quick way to confirm the right ytyp is loaded.

## Common mistakes

- **Prop is invisible.** The ytyp is still XML, the `data_file` line is missing, or the archetype name does not match the model file name. For a `.ydr` the game finds the model by the archetype name, not by assetName.
- **White or purple textures.** `textureDictionary` does not match the `.ytd` name, or the `.ytd` is not streamed.
- **Prop disappears at screen edges.** Bounds are too small. Drop the model XML again to measure them.
- **Same name as a game prop.** Your archetype replaces or duplicates the game one. Give custom props their own prefix.
- **Ytyp named like a game ytyp.** Two files with one name fight each other. Pick a unique name for the ytyp too.
- **Changes do not show.** Reconnect. Archetypes are registered when the resource starts.
- **Animated prop does not animate.** Set `clipDictionary` and flag `512` (skeletal) or `1024` (UV). Add `524288` Auto start anim to start the clip on spawn.

> [!TIP]
> Keep the model file, the archetype name and the name you spawn identical and lowercase. Almost every "prop does not load" report comes down to one of the three being different.

## Limitations

- It writes XML only. The binary `.ytyp` comes from CodeWalker.
- Interiors (MLO archetypes) are passed through untouched, not edited. Use CodeWalker for those.
- Archetype extensions are kept from imports but cannot be created or edited here.
- Bounds come from the high detail mesh. If your lower LODs are bigger than the high LOD, widen the box by hand.
- Everything runs in your browser. Model files are read locally, nothing is uploaded. Your list is saved in browser storage.

## Related tools

- [YMAP Builder](/docs/tools/ymap-builder) to place your new props in the world
- [Objects List](/docs/tools/objects-list) to look up game props and their sizes
- [Texture Editor](/docs/tools/texture-editor) for the `.ytd`
- [YTD Optimizer](/docs/tools/ytd-optimizer) to shrink oversized texture dictionaries
- [fxmanifest Generator](/docs/tools/fxmanifest-generator)
- [joaat Hash Calculator](/docs/tools/hash-calculator)

_Last updated: 2026-09-22_

---

## Texture Editor

URL: https://fivemad.com/docs/tools/texture-editor

How to open a .ytd or a CodeWalker .ytd.xml export, preview and replace textures, pick the compression and mips, and export a new .ytd for your stream folder.

The Texture Editor opens a texture dictionary (`.ytd`) and lets you preview, replace, rename, add and delete its textures. PNG, JPG and WebP images are resized to a power of two and compressed right in the page, with the format and mip chain you pick, and you export a new `.ytd` or a CodeWalker XML + DDS zip. It is for anyone who needs to swap a logo, fix a broken texture or cut the memory of a dictionary without OpenIV.

## What it is for

- **Replacing a texture.** New livery, new sign, new shop logo: drop a PNG on the texture and export.
- **Fixing problem textures.** Odd sizes, missing mips, uncompressed 4 MB normal maps, DXT5 with no alpha. Each texture gets a list of issues and the fix is one click.
- **Building a dictionary from scratch.** Drop loose PNG or DDS files and export them as a new `.ytd`.
- **Checking memory.** The toolbar shows the memory of the whole dictionary, each tile its own.

Everything is read and written in your browser. Nothing is uploaded.

## Quick start

1. Open the [tool](/tools/texture-editor).
2. Drop the `.ytd` from your resource's `stream` folder on the page, or use **Choose files** or **Choose folder**.
3. Click a texture tile. The big preview and the inspector below it show it.
4. Drop a PNG, JPG, WebP or DDS on the tile or on the preview, or press **Replace image**.
5. Check the result in the preview (it shows the compressed version, so what you see is what the game gets).
6. Press **Export .ytd** and put the file back into `stream/` with the exact same name.

## Opening files

| What you drop | What happens |
| --- | --- |
| One or more `.ytd` files | The first one opens. With several, a selector (**N dictionaries in this drop**) switches between them. |
| A folder | Searched for `.ytd` files and CodeWalker exports. |
| `name.ytd.xml` with its DDS folder | Opens the CodeWalker export. Drop the XML and the folder together, or pick the parent folder. |
| Loose DDS, PNG, JPG or WebP files | Start a new dictionary named after the folder (or `my_textures`). |
| Images or DDS while a dictionary is open | Added as new textures. A file with the same name as an existing texture replaces it. |

**Start empty** on the first screen opens an empty dictionary called `my_textures`.

Game files inside an `.rpf` have to be extracted first with CodeWalker or OpenIV. A `.ytd` that is encrypted, damaged or from GTA V Enhanced (gen9) is rejected with a message; FiveM uses the legacy format.

> [!TIP]
> Vehicles usually have two dictionaries: `name.ytd` and `name+hi.ytd` (the close up versions). Drop both and switch between them with the selector. Clothing has one `.ytd` per variation, like `jbib_diff_000_a_uni.ytd`.

## Toolbar

| Control | What it does |
| --- | --- |
| **Dictionary** | The dictionary name, used for the exported file names. |
| **Used for** | **Prop**, **Vehicle**, **Clothing / ped** or **Map / MLO**. Guessed from the name. Changes the size warnings: 2048 px is the soft limit, 4096 for maps and MLOs. |
| **Memory** | Total texture memory of the dictionary and the texture count. |
| **Open** | Open another dictionary folder. |
| **Add texture** | Add DDS, PNG, JPG or WebP files. |
| **XML + DDS zip** | Export for CodeWalker's Import XML. |
| **Export .ytd** | Export a new `.ytd`. |

Under the toolbar a line shows the facts of the opened `.ytd` (resource version, size on disk, memory pages) and after an export the same facts for the new file.

Messages appear below that: dictionary level issues (duplicate names, total size), how many textures have errors, files in the drop that are not part of the dictionary (with an **Add them** button), and **Undo** after a delete. Deleting can be undone until the next delete.

## Texture grid

**Filter textures** searches names and usages. Sort by **File order**, **Name**, **Memory** or **Pixels**.

Each tile shows a thumbnail, the name, size and format, the usage and the memory. A red or amber badge counts the errors and warnings (hover it to read them). Edited tiles show their state in green: **Replaced**, **Added**, **Re-encoded** or **Mips rebuilt**. A tile without a DDS says **No DDS**. Drop an image on any tile to replace that texture.

## Preview

| Control | What it does |
| --- | --- |
| **RGB** | Colour, alpha ignored. |
| **RGBA** | Colour over the backdrop using alpha. |
| **R**, **G**, **B**, **A** | Single channels. **A** is the fastest way to check a cutout or decal mask. |
| Backdrop | Checker, black, grey or white, used by the RGBA view. |
| Zoom | Mouse wheel, the zoom buttons, the percentage (click for 1:1) and fit to view. |
| Mip level | Shows each mip, for example `Mip 2: 256x256`, when the texture has more than one. |

You can drop an image on the preview to replace the selected texture.

## Inspector

The top row has the **Name** (rename it, two textures can not share a name), the **Usage** (DIFFUSE, NORMAL, SPECULAR, DETAIL, EMISSIVE, TINTPALETTE, DEFAULT, UNKNOWN), **Revert** (back to the file you opened) and **Delete**.

The facts: size, format, mips (for example `9 of 9`), memory, alpha (opaque, cutout, soft), flags, source file and encode time. Below them the issue list for this texture.

### Issues it checks

- Name has spaces.
- Size is not a power of two.
- Bigger than 4096 (error) or bigger than the limit for the **Used for** type (warning).
- Fewer mip levels than the game wants.
- Large uncompressed textures.
- Normal maps in DXT1 or ATI2 (notes), colour maps in ATI1 or ATI2 (warning).
- DXT5 with fully opaque alpha (DXT1 would halve the memory).
- Soft alpha stored as DXT1 (it becomes on or off).
- A DDS missing, truncated or in an unknown format.
- For XML exports: when the XML and the DDS file disagree on size, mips or format (the DDS wins).

Dictionary wide it warns about duplicate names and the total size: a note above 8 MB, a warning above 16 MiB (FXServer prints a memory warning) and an error above 48 MiB (FXServer calls the file oversized).

### Actions

- **Replace image** picks a new file for the selected texture.
- **Re-encode as ...** encodes the texture again with the settings below (for example to turn DXT5 into DXT1 or downsize it).
- **Build missing mips** appears when the texture has fewer mips than the game wants. The full size level stays exactly as it was.
- **DDS** and **PNG** download the selected texture.

### Encode settings

These apply when you replace, add or re-encode a texture.

| Setting | Options | Default |
| --- | --- | --- |
| **Format** | **Keep**, DXT1 (BC1), DXT5 (BC3), ATI2 (BC5), ATI1 (BC4), A8R8G8B8 | Keep |
| **Size** | **Same**, **Nearest power of two**, 4096, 2048, 1024, 512, 256, 128, 64 | Same |
| **Fit** | **Stretch**, **Fit (pad)** (pads with transparency), **Crop (fill)** | Stretch |
| **Max size** | 4096, 2048, 1024, 512, 256 | 2048 |
| **Mips** | **Game (to 4 px)**, **Full (to 1 px)**, **None** | Game |
| **Mip filter** | Kaiser, Box | Kaiser |
| **Quality** | High, Fast | High |

**Will cost** shows the memory and the size the texture will have with these settings.

How the settings play together:

- **Keep** reuses the format of the texture you replace. When that format can not be written (for example DXT3 or BC7), it picks DXT5 for normal maps and textures with soft alpha, DXT1 for the rest.
- **Same** keeps the size of the texture you replace, so UVs and the rest of the dictionary stay as they were. For brand new textures it falls back to the nearest power of two.
- The result is always a power of two and never bigger than **Max size**.
- A DDS you drop is used as it is, without re-encoding.
- Re-encoding a texture that is already compressed loses a little detail. Use the original artwork when you have it.

## Which format to pick

| Format | Memory | Use it for |
| --- | --- | --- |
| `DXT1` | 0.5 byte per pixel | Most diffuse, spec and normal maps without alpha. Cutout alpha (fences, leaves) works too, it is on or off. |
| `DXT5` | 1 byte per pixel | Soft alpha: glass, decals, hair, fades. Cleaner normal maps at twice the cost. |
| `ATI2` (BC5) | 1 byte per pixel | Two channel data. Stores only X and Y of a normal, test in game before you ship it. |
| `ATI1` (BC4) | 0.5 byte per pixel | One channel masks. |
| `A8R8G8B8` | 4 bytes per pixel | Only when compression artifacts are not acceptable, like small UI or script render targets. |

BC7 textures are shown and written back untouched. The editor does not encode BC7; re-encoding one turns it into one of the formats above.

## Output

| Button | File | Contents |
| --- | --- | --- |
| **Export .ytd** | `<dictionary>.ytd` | Every texture that has a DDS. Name, usage and flags you did not touch stay as they were. |
| **XML + DDS zip** | `<dictionary>.zip` | `<dictionary>.ytd.xml` and a folder `<dictionary>/` with one DDS per texture, the layout CodeWalker's **Import XML** wants. |
| **DDS**, **PNG** | `<texture>.dds`, `<texture>.png` | The selected texture only. |

Textures without a DDS are left out of both exports; the message lists them. Wait until every texture has finished encoding before you export, the tool tells you if some are still busy.

## Put it back into the game

1. **Export .ytd** and copy the file into your resource's `stream` folder with the exact same name as the one you replace.
2. Restart the resource (or the server). Players download the new file when they join.
3. Going through CodeWalker instead: extract the **XML + DDS zip**, then **Import XML** in the RPF Explorer and pick the `.ytd.xml`.

```bash
my_car/
  fxmanifest.lua
  stream/
    mycar.yft
    mycar.ytd        # the rebuilt dictionary
    mycar+hi.ytd
```

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'
```

FiveM streams everything in `stream/` automatically, so a `.ytd` needs no `files` or `data_file` entry. For clothing, keep the file names your addon pack uses.

> [!IMPORTANT]
> Texture names inside the dictionary are what shaders look up. If you rename a texture, the model will not find it any more unless its shader points at the new name too.

## Texture memory and server warnings

The memory numbers are the GPU size of the texture with its mips, the same number the game streams. A `.ytd` file on disk is smaller because resources are compressed, but in memory it is the full size. FXServer prints a memory warning for every streamed file above 16 MiB of physical memory and calls it oversized above 48 MiB, and players on weaker PCs get textures that pop in late or stay blurry. The usual fixes, biggest win first:

- Drop 4096 textures to 2048 and 2048 ones to 1024 where nobody looks closely. Each step cuts the memory by 4.
- Use DXT1 instead of DXT5 when the alpha is fully opaque (the inspector tells you when that is the case). Half the memory.
- Never ship A8R8G8B8 for normal textures, it is 8x DXT1.
- Keep full mip chains. Without mips the game always keeps the biggest level loaded and the texture shimmers at distance.
- Split a huge dictionary: shared textures in one `.ytd`, or move close up detail into the `+hi` dictionary for vehicles.

For many files at once, use the [YTD Optimizer](/docs/tools/ytd-optimizer).

## Common mistakes

- **Wrong file name.** The exported `.ytd` is named after the **Dictionary** field. Make sure it matches the file you replace, including `+hi`.
- **Soft alpha in DXT1.** Glass or decals turn hard edged. Pick DXT5, or leave **Format** on **Keep** when the original was DXT5.
- **Stretching a wide logo.** Set **Fit** to **Fit (pad)** or **Crop (fill)** when your image has a different aspect ratio than the texture.
- **Exporting while encoding.** Wait for the busy labels on the tiles to finish.

## Limitations

- Does not encode BC7 or DXT3. Those stay untouched unless you re-encode them into another format.
- Reads the legacy `.ytd` format FiveM uses, not GTA V Enhanced files.
- Encrypted files (for example escrow protected assets) can not be opened.
- Everything runs in your browser and nothing is uploaded.

## Related tools

- [YTD Optimizer](/docs/tools/ytd-optimizer) shrinks many `.ytd` files at once.
- [Clothing Designer](/docs/tools/clothing-designer) paints clothing textures on the 3D model.
- [Drawable Studio](/docs/tools/drawable-studio) edits materials and paints textures on CodeWalker model exports.
- [Script Thumbnail Creator](/docs/tools/script-thumbnail-creator) for store images.

_Last updated: 2026-09-22_

---

## Vehicle Sirens Editor

URL: https://fivemad.com/docs/tools/vehicle-sirens

Edit carcols.meta siren settings with a live preview and a 32 step pattern grid, export carcols.meta, and find free or clashing siren ids on your server.

The Vehicle Sirens Editor builds and tunes emergency lighting for GTA V vehicles. You edit every siren light's colour, direction, rotation, flash and 32 step pattern with a live preview on the real vehicle layout, set the timing, and export a `carcols.meta`. The **Siren ID check** tab reads all your carcols and carvariations files and shows which siren ids are taken, free or clashing.

## What it is for

Siren settings are hard to write by hand: each one has 20 lights, each light has two 32 bit patterns stored as big decimal numbers, and you cannot see the result without restarting and driving into the dark. The editor shows the pattern as a grid you paint with the mouse and plays it on the vehicle, so you can build a wig wag or a rotator bar in minutes.

The id checker solves the other common problem on emergency vehicle servers: two packs that use the same siren id, so one set of cars shows the wrong lights.

## How siren settings work

A siren setting is one `<Item>` in the `<Sirens>` block of a `carcols.meta`. It has an `id`, timing for the whole set (`sequencerBpm`, `timeMultiplier`), how the cast light behaves (falloff and cone angles), head and tail light patterns, and a list of exactly 20 lights. Light 1 is drawn at the model's `siren1` bone, light 20 at `siren20`. A light with no matching bone on the model is skipped, so the same setting looks different on different cars.

The vehicle picks its setting in `carvariations.meta` with `<sirenSettings value="ID" />`. That number must match the `id` in carcols.meta. 0 means no sirens.

Every light has a 32 bit `sequencer`: one bit per beat at `sequencerBpm`, 1 is on and 0 is off. The file stores it as an unsigned decimal. Step 1 in the grid is the leftmost (highest) bit. `4294967295` is always on, `2863311530` is 1010..., `1431655765` is 0101.... At 300 BPM a full 32 step pattern takes 6.4 seconds. Flashing lights use the `flashiness` sequencer, rotators (`rotate` true) the `rotation` one.

## Quick start

1. Pick a game setting on the left (search by id, name or vehicle model), or click **New setting**, or **Import carcols.meta**.
2. To build your own lights from a game setting, click **Copy to new id**. It copies the setting to the next free id from 100 up.
3. Press **Play** in the **Preview** panel and paint steps in the **Patterns** grid.
4. Click a lamp in the preview (or a light name in the grid) and edit it in the **Light** panel.
5. Set the timing and cone values in the **Setting** panel.
6. Open the **carcols.meta** tab under the editor and copy or download it. Use the **carvariations** tab to see where the id goes, and the **fxmanifest** tab for the resource manifest.

Your work is saved in this browser. Links like `?id=16` open a game setting, `?tab=ids` opens the id checker, and `?view=rear` starts the preview in the rear view.

## The setting list

The list has two groups:

- **Yours**: settings you edited, copied, created or imported, with a badge (**edited**, **new**, **import**) and where they came from ("copy of 1", "from carcols.meta").
- **Game**: the 21 game settings (ids 0 to 20, build 3889) from the base game and DLCs, with the vehicles that use each one. Id 0 is a placeholder that nothing uses.

Each row shows a strip of the first eight light colours.

### Editing a game setting vs copying it

You can edit a game setting in place. It then shows as **edited** and exports with its game id, which replaces that id for every vehicle that uses it (for example id 1 is `police/sheriff`). The id box is locked for game settings. For your own car, use **Copy to new id** instead.

**Reset (N)** puts the setting back to what it was loaded as (the game values, the import, or the state when you copied it). **Remove** drops your own settings from the list.

## Header and warnings

The **id** and **name** fields sit at the top. Ids above 255 or below 1 turn the box red. Amber warnings appear when:

- `lightInnerConeAngle` is not smaller than `lightOuterConeAngle`.
- The setting has more or fewer than 20 lights.
- `sequencerBpm` is 0 or below.
- The id is 0, or above 255.

## Preview

The preview draws the lights on a vehicle layout, seen from the **Top** or the **Rear**.

| Control | What it does |
| --- | --- |
| Model select | **Auto** uses a vehicle that uses this setting (or `police`), **Generic layout** uses a neutral layout, or pick any of the listed models. |
| Play / Pause | Plays the pattern at the setting's BPM. Starts paused if your system asks for reduced motion. |
| Step | Advances one sequencer step. |
| Restart | Back to step 1. |
| 0.25x, 0.5x, 1x | Playback speed. |

Click a lamp in the preview to select that light. If the model has no bone for some of the lights, a note under the preview tells you how many are not drawn (the game skips them too).

The timing, which lights are lit on which step, multiples, colours and lamp positions follow the setting. Glow size, beam length, brightness and rotator speed are approximations, so always check the result in game.

## Patterns

The **Patterns** panel shows one row of 32 steps per light. Click a cell to toggle it, or click and drag to paint. The current playback step is highlighted.

| Mode | What the grid edits |
| --- | --- |
| In use | The rotation pattern for rotators, the flash pattern for the rest. |
| Flash | Every light's `flashiness` sequencer. |
| Rotation | Every light's `rotation` sequencer. |

Below it, **Head and tail lights** has four rows (left and right head, left and right tail) for flashing the car's real lights, with a **useRealLights** switch. Guides advise at most 4 flashes in a row.

## Light

Pick a light with the numbered buttons or the `siren1` to `siren20` dropdown. The header says whether it is a rotator, flasher or not lit, and whether it casts a spot light, a round light or only a corona.

**Colour to all** gives every light this colour. **Settings to all** copies every field except the colour and the patterns to the other lights.

### Switches

| Switch | What it does |
| --- | --- |
| `rotate` | Spins the light (rotator). Uses the rotation pattern. |
| `flash` | Flashes the light. Uses the flash pattern. |
| `light` | Casts real light on the world, not only a corona. |
| `spotLight` | Cone shaped light instead of a round glow. Rotators need it to look like they spin. |
| `scale` | Corona grows with `scaleFactor` while lit. |
| `castShadows` | The cast light makes shadows. Costs performance; game files keep it off. |

### Colour

Use the colour picker, type `0xAARRGGBB` in the text box, or click a preset: Red `FFFF0300`, Blue `FF0019FF`, Amber `FFFFAA00`, White `FFFFFFFF`, Green `FF00FF0D`, Magenta `FFFF00FB`. Game lights use alpha `FF`; the tool tells you when yours is lower.

### Numbers

| Field | What it does | Range |
| --- | --- | --- |
| `intensity` | Brightness of the light cast on the world. | 0 to 10 |
| `scaleFactor` | Corona size while flashing when `scale` is on. | 0 to 255 |
| `lightGroup` | Lamp group. Game files use 0 to 3. | 0 to 255 |

### flashiness and rotation

Each has its own block, and the one in use is highlighted:

| Field | What it does |
| --- | --- |
| `sequencer` | The 32 step pattern. Pick from **Presets...** (Always on, Off, Alternate A/B, Pairs A/B, Quads A/B, Half A/B, Triple flash A/B), shift it one step left or right, invert it, or type it as decimal, `0x` hex, `-1` or a 32 character bit string. |
| Direction dial | Click a dot to point the light front, back, left, right or diagonal. The top of the dial is the front of the car. |
| `delta` | Facing in radians: 0 front, 1.5708 left, 3.1416 back, -1.5708 right. |
| `start` | Start angle, added to delta. |
| `speed` | Spin speed for rotators. |
| `multiples` | Flashes inside one lit beat. |
| `direction` | Flips the spin direction. |
| `syncToBpm` | Ties the timing to `sequencerBpm`. |

The light also shows its own warnings, for example rotate and flash both on, neither on, an empty pattern, or a rotator without `spotLight`.

### corona

`intensity` (0 hides the corona), `size` (0 hides it too), `pull` (pulls the corona towards the camera so it shows through the lamp glass) and `faceCamera`.

## Setting

| Field | What it does | Default for a new setting |
| --- | --- | --- |
| `sequencerBpm` | Beats per minute. Game lightbars use 150 to 300. | 300 |
| `timeMultiplier` | Scales the BPM. 2 plays the pattern twice as fast. | 1 |
| `lightFalloffMax` | How far the cast light reaches, metres. | 10 |
| `lightFalloffExponent` | How hard the light fades towards the max distance. | 10 |
| `lightInnerConeAngle` | Full brightness part of each spot cone, degrees. | 2.29061 |
| `lightOuterConeAngle` | Edge of each spot cone, degrees. | 70 |
| `lightOffset` | Offset of the cast light from the lamp. Game lightbars use 0. | 0 |
| `textureName` | Corona texture. Leave it at `VehicleLight_sirenlight`. | `VehicleLight_sirenlight` |

The four head and tail light sequencers also have their pattern tools here, each with a `...Multiples` value. If a setting has fewer than 20 lights, **Fill up to 20 lights** adds blank, unlit ones.

A **New setting** starts with 20 lights: red on odd lights, blue on even ones, flashing in turns.

## Importing

Click **Import carcols.meta**, paste a whole carcols.meta, its `<Sirens>` block or one siren `<Item>`, and press **Parse**, or use **Open files** to load several files at once. Kits and lights in the file are ignored. Signed sequencers like `-1` are read too. Missing or odd fields are filled with defaults and listed under **field warnings**. The message also tells you when an imported id is also a game id. Importing the same file again replaces its settings instead of adding copies.

## Output

The tabs under the editor:

| Tab | What you get |
| --- | --- |
| carcols.meta | A carcols.meta with every setting in your export: edited game settings, copies, new and imported ones. |
| carvariations | Where to put each id in your vehicle's carvariations.meta. |
| fxmanifest | A ready `fxmanifest.lua`. |
| Settings | Every exported setting with its changed fields, a **Copy Item** button (one setting to paste into an existing Sirens block) and a button to drop it from the export. |

### carcols.meta

```xml title="carcols.meta"
<?xml version="1.0" encoding="UTF-8"?>
<CVehicleModelInfoVarGlobal>
  <Sirens>
    <Item>
      <id value="100" />
      <name>my_sirens</name>
      <timeMultiplier value="1.000000" />
      <lightFalloffMax value="10.000000" />
      <lightFalloffExponent value="10.000000" />
      <lightInnerConeAngle value="2.290610" />
      <lightOuterConeAngle value="70.000000" />
      <lightOffset value="0.000000" />
      <textureName>VehicleLight_sirenlight</textureName>
      <sequencerBpm value="300" />
      <leftHeadLight>
        <sequencer value="0" />
      </leftHeadLight>
      <!-- rightHeadLight, leftTailLight, rightTailLight -->
      <leftHeadLightMultiples value="1" />
      <rightHeadLightMultiples value="1" />
      <leftTailLightMultiples value="1" />
      <rightTailLightMultiples value="1" />
      <useRealLights value="true" />
      <sirens>
        <Item> <!-- siren1 -->
          <rotation>
            <delta value="0.000000" />
            <start value="0.000000" />
            <speed value="3.000000" />
            <sequencer value="4294967295" />
            <multiples value="1" />
            <direction value="false" />
            <syncToBpm value="true" />
          </rotation>
          <flashiness>
            <delta value="0.000000" />
            <start value="0.000000" />
            <speed value="1.000000" />
            <sequencer value="2863311530" />
            <multiples value="1" />
            <direction value="true" />
            <syncToBpm value="true" />
          </flashiness>
          <corona>
            <intensity value="50.000000" />
            <size value="1.100000" />
            <pull value="0.200000" />
            <faceCamera value="false" />
          </corona>
          <color value="0xFFFF0300" />
          <intensity value="0.500000" />
          <lightGroup value="0" />
          <rotate value="false" />
          <scale value="true" />
          <scaleFactor value="2" />
          <flash value="true" />
          <light value="true" />
          <spotLight value="true" />
          <castShadows value="false" />
        </Item>
        <!-- siren2 to siren20 -->
      </sirens>
    </Item>
  </Sirens>
</CVehicleModelInfoVarGlobal>
```

A carcols.meta that only has a `<Sirens>` block is fine. If your vehicle resource already ships a carcols.meta, paste the setting's `<Item>` (use **Copy Item** on the **Settings** tab) into its Sirens block instead of adding a second file with the same id.

### carvariations.meta

```xml title="carvariations.meta"
<Item>
  <modelName>yourcar</modelName>
  <!-- colors, kits, plateProbabilities... stay as they are -->
  <sirenSettings value="100" />
</Item>
```

For a copy of a game setting, the tab fills in a vehicle that used the original id. Edited game settings need no carvariations change, their vehicles already point at that id.

### fxmanifest.lua

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

files {
  'data/carcols.meta',
  'data/carvariations.meta',
}

data_file 'CARCOLS_FILE' 'data/carcols.meta'
data_file 'VEHICLE_VARIATION_FILE' 'data/carvariations.meta'
```

Save the files in a `data` folder next to this manifest and `ensure` the resource. Leave out the carvariations lines if the vehicle resource already loads its own.

## Siren ID check

The **Siren ID check** tab reads files and tells you which ids are in use.

1. Drop `carcols.meta` and `carvariations.meta` files on the **Files** box (several at once, from every siren resource on your server), or paste the text of a file and click **Add**.
2. Leave **Include the game's ids** on to see clashes with game settings. Turn on **Include my editor settings** to check what you built in the editor.
3. Read the results.

| Result | What it shows |
| --- | --- |
| Id map 0 to 255 | A 16 by 16 grid: game ids, yours, warnings and clashes. Hover a cell for details. |
| Problems / Ids in your files / Free ids (1 to 254) | Counts. |
| Next free ids | Ids you can copy, from 100 up, then the gap above the game's ids. Plus the list of free ranges. |
| Vehicles with more than one id | A model pointed at different ids by different carvariations files. The last one loaded wins. |
| Ids table | Each id, where it is defined, which models use it, and its status. |

| Status | Meaning |
| --- | --- |
| Clash | Defined more than once. Only one definition wins. |
| Replaces game | Same id as a game setting. Every game vehicle on that id gets your lights. |
| Not defined | A carvariations entry points at an id no loaded carcols (or the game) defines. |
| Unused | Defined, but no loaded carvariations points at it. |
| Over 255 | Only works with the SirenSetting Limit Adjuster on every client. |
| OK | Defined once, no clash. |

Files over 20 MB are skipped. Nothing is uploaded.

## The 255 id limit

- The id is a single byte in both carcols and carvariations, so ids go up to 255. 0 means no sirens and the Limit Adjuster reserves 255, so 1 to 254 is the safe range.
- The game uses ids 1 to 20 at build 3889, and Rockstar adds more with DLCs, so start your own ids higher. The tool suggests ids from 100 up.
- FiveM does not raise the limit ([citizenfx/fivem#2612](https://github.com/citizenfx/fivem/issues/2612) is still open). The client side SirenSetting Limit Adjuster allows higher ids, but every player has to install it.

> [!WARNING]
> Two resources with the same siren id do not crash anything, which is why the problem goes unnoticed. Run every carcols.meta on your server through the Siren ID check before adding a new pack.

## Common mistakes

- **Id in carcols does not match carvariations.** Put the same number in `id` and `sirenSettings`.
- **Editing a game setting when you meant to make your own.** That changes every vehicle on that id. Use **Copy to new id**.
- **Rotate and flash both on.** The game handles one mode per light. Pick one.
- **Rotator without `spotLight`.** It becomes a round glow and the spin cannot be seen.
- **Fewer than 20 lights.** Use **Fill up to 20 lights** so the `<sirens>` list is complete.
- **A second carcols.meta with the same id** inside a pack that already has one. Merge the Item into the existing Sirens block.

## Limitations

The preview is a guide, not the game renderer: glow, beam length, brightness and rotator speed are approximate. The tool only reads and writes the `<Sirens>` part of carcols.meta; kits and lights are ignored on import and not written. Everything runs in your browser.

## Related tools

- [Vehicle Handling Editor](/docs/tools/vehicle-handling-editor)
- [Vehicle Pack Validator](/docs/tools/vehicle-pack-validator)
- [fxmanifest.lua Generator](/docs/tools/fxmanifest-generator)
- [Model Hash Browser](/docs/tools/model-hash-browser)

_Last updated: 2026-09-22_

---

## Vehicle Pack Validator

URL: https://fivemad.com/docs/tools/vehicle-pack-validator

Check a FiveM vehicle resource for broken links between metas, stream files and fxmanifest. Every check it runs, what it means and how to fix it.

The Vehicle Pack Validator reads an addon car resource (or a whole `[cars]` folder) and reports every broken link between `fxmanifest.lua`, the vehicle metas and the files in `stream/`. Each finding names the file and line and says what to change. It is for server owners installing car packs and for devs who build them.

## What it is for

A car that does not spawn, spawns without textures, has no tuning parts or flashes another car's light pattern is almost always a wiring problem, not a model problem: a `data_file` line with the wrong type, a meta missing from `files { }`, a `handlingId` with a typo, a kit id that another pack already uses. Finding those by hand across five metas and a manifest takes a long time, and it gets worse when you merge twenty car resources.

Drop the pack here before you put it on the server, or when a car misbehaves and you want to rule out the metas.

## Quick start

1. Open the tool and use **Choose a folder** (pick the resource folder, or the parent `[cars]` folder), **Open a .zip**, or drag the folder or zip onto the card.
2. Wait for the progress bar to finish reading the files.
3. Read the verdict at the top: **Ready to ship**, **Works, with problems** or **Broken**, with counts of errors, warnings, notes, vehicles, broken cars and resources.
4. Work through the **Findings** tab, errors first. Click a model name under a finding to jump to that car in the **Vehicles** tab.
5. Open the **fxmanifest** tab to compare your manifest with the one built from the files that are really in the folder.
6. Press **Report .md** to download the whole report as Markdown for a ticket or a Discord post.

No pack at hand? **Try a sample** loads a made up pack with invented names and placeholder model files, broken on purpose.

> [!NOTE]
> Everything is read in your browser, nothing is uploaded. Big model files are not opened in full, so even a large car folder checks quickly.

## Input

What you can drop:

- One resource folder (the one with `fxmanifest.lua` or `__resource.lua`).
- A folder holding many resources. Each folder with a manifest becomes its own resource, and conflicts between them are checked.
- A `.zip`. Normal and zip64 archives with store or deflate compression work. Password protected zips and 7z or rar archives must be extracted first. Files the zip reader skips are listed under the verdict.

Vehicle files that sit in no resource with a manifest are grouped by their top folder (the folder above `stream/`, `data/`, `meta/`, `metas/`, `audioconfig/` or `sfx/`), so a pack without a manifest is still checked and gets a "no fxmanifest" error.

Ignored: `__MACOSX/`, `.git/`, `.DS_Store`, `Thumbs.db`, `desktop.ini`.

What it looks at:

| Files | Used for |
|---|---|
| `*.meta` | The vehicle metas. You can name them anything: a meta is recognised by its root element (`CVehicleModelInfo__InitDataList` is vehicles.meta, `CHandlingDataMgr` handling, `CVehicleModelInfoVarGlobal` carcols, `CVehicleModelInfoVariation` carvariations, `CVehicleMetadataMgr` vehiclelayouts, plus dlctext, content unlocks and shop metas). |
| `.yft .ytd .ydr .ydd` | Presence, location, file type and memory size. |
| Other stream files (`.ybn .ycd .ymap .ytyp` ...) | Name and location. |
| `*.dat151.rel`, `*.dat54.rel`, `.awc` and other audio data | Engine sound checks and the audio `data_file` lines. |
| Client and shared `*.lua` | `AddTextEntry` calls for car display names. |
| `*.fxap` | Marks the resource as escrowed. |

## The report

### Verdict

- **Broken**: at least one error. The title says how many cars will not work as shipped.
- **Works, with problems**: no errors, some warnings.
- **Ready to ship**: no errors or warnings. Notes may remain, they are optional.

### Findings tab

Findings are grouped: fxmanifest and data_file, Stream files, vehicles.meta, handling.meta, Mod kits (carcols and carvariations), Sirens, Engine sound, Asset size, Conflicts between resources, File and folder names. The filter row switches between **All**, **Errors**, **Warnings** and **Notes**. Each finding has a title, evidence lines (`file:line` and what was found) and a fix. Model buttons under a finding open that car in the Vehicles tab.

### Vehicles tab

One row per `modelName`, worst status first. The chips show what the car links to:

| Chip | Meaning |
|---|---|
| `.yft` | The model file, with its path and memory size. Red when missing, amber when over 16 MiB. |
| `_hi` | The high detail model. Amber when missing. |
| `.ytd` | The texture dictionary from `txdName`. |
| `handling` | The matching `handlingName`, or "base game". |
| `variations` | The carvariations entry. |
| `kit` | Kits and their ids. |
| `siren` | `sirenSettings` id, only for cars that have one. |
| `sound` | `audioNameHash` and whether it is a base game sound, in this pack or not found. |

Open a row to see the meta file and line plus all findings for that car. With more than 6 vehicles a filter box appears (by model or resource).

### fxmanifest tab

A suggested manifest per resource, built from what is really in the folder. It says whether it **differs from the current manifest** or **matches** it. The rules:

- `fx_version 'cerulean'` and `game 'gta5'`, plus `lua54`, `name`, `author`, `description`, `version` if you had them.
- Your `shared_scripts`, `client_scripts` and `server_scripts` are kept.
- One `data_file` line per vehicle meta with the type that matches its root element, and one per sound file, in Rockstar's DLC order: `HANDLING_FILE`, `VEHICLE_LAYOUTS_FILE`, `VEHICLE_METADATA_FILE`, `CARCOLS_FILE`, `VEHICLE_VARIATION_FILE`, `CONTENT_UNLOCKING_META_FILE`, `VEHICLE_SHOP_DLC_FILE`, `TEXTFILE_METAFILE`, `AUDIO_SYNTHDATA`, `AUDIO_GAMEDATA`, `AUDIO_SOUNDDATA`, `AUDIO_WAVEPACK`.
- Other valid `data_file` lines you had (types this tool does not manage) are kept. `DLCTEXT_FILE` is dropped.
- `files { }` lists every data file target, the `.nametable` files, `<folder>/*.awc` for wave packs, and your own entries for other files (images, json).
- `escrow_ignore` is kept.

Compare it with yours before you replace anything.

## Every check

Severity: **Error** blocks loading (car does not spawn, meta not loaded, crash). **Warning** means it loads but looks, sounds or behaves wrong, or clashes with something. **Note** is information.

### fxmanifest and data_file

| Check | Severity | What it means | How to fix |
|---|---|---|---|
| No fxmanifest.lua | Error | A folder with metas or stream files has no manifest, so FiveM never starts it. | Add an `fxmanifest.lua` (the suggested one is a start) and `ensure` the folder. |
| Both manifests | Warning | `fxmanifest.lua` and `__resource.lua` exist. FiveM ignores `__resource.lua`. | Move what you need into fxmanifest.lua, delete `__resource.lua`. |
| Legacy manifest | Note | The resource still uses `__resource.lua`. | Rename to fxmanifest.lua, replace `resource_manifest_version` with `fx_version 'cerulean'` and `game 'gta5'`. |
| Lua syntax problem | Error | Unclosed string, unclosed `--[[` comment, unclosed `{`, a missing comma between table entries, or `data_file` without both a type and a path. Everything after the break is silently missing. | Fix the line shown. The server console shows the same error on start. |
| `fx_version` missing | Error | The resource does not start. | Add `fx_version 'cerulean'` at the top. |
| `game` missing | Warning | The server warns about manifests without a game. | Add `game 'gta5'`. |
| `this_is_a_map` in a vehicle resource | Note | Makes the client reload the map store on start. Cars do not need it. | Remove it unless the resource also streams map files. |
| files entry matches no file | Warning | A `files { }` path points at nothing. | Fix the path (relative to the resource folder) or remove it. |
| files entry only matches with different case | Warning | Works on Windows, finds nothing on Linux. | Make the path match the real file name exactly. |
| data_file loaded twice | Warning | The same type and path appear twice, so every entry is added twice. | Remove the duplicate line. |
| `DLCTEXT_FILE` | Note | Not a type FiveM has a loader for. It does nothing. | Delete the line. Car names come from `AddTextEntry`. |
| Unknown data_file type | Error | A misspelled type is ignored, so the file never loads. Close matches are suggested. | Use the exact type name, it is case sensitive. |
| Audio data_file uses a wildcard | Error | Audio data files cannot be globbed. | One line per sound pack with the exact path. |
| data_file points at a missing file | Error | Nothing matches the path. For audio types the path must be the file without the version suffix, for `AUDIO_WAVEPACK` the folder. | Fix the path. `audioconfig/mycar_game.dat151.rel` is written `audioconfig/mycar_game.dat`. |
| data_file not in files { } | Error | Clients only download what `files { }` lists, so the game never sees it. | Add the path to `files { }`. |
| Wrong data_file type for a meta | Error | A vehicles.meta loaded as `HANDLING_FILE` and so on. The type is checked against the root element. | Change the type to the one the finding names. |
| Meta never loaded | Error (core metas), Note (content unlocks, shop meta) | A vehicles, handling, carcols, carvariations or vehiclelayouts meta has no `data_file` line. | Add the `data_file` line and list the file in `files { }`. |
| CARCOLS or VARIATION before VEHICLE_METADATA | Note | Rockstar loads vehicles.meta, then carcols.meta, then carvariations.meta. FiveM only moves handling and layouts to the front. | Reorder the lines to rule it out. |
| Not a vehicle meta | Note | A meta with an unknown root element. Not checked. | Make sure it has the right `data_file` type if it belongs to the car. |
| Not valid XML | Error | The game skips or crashes on a meta it cannot parse. | Fix the tag at the line shown (VS Code highlights the break). |

Globs follow FiveM's rules: `*` and `?` stay inside one folder, `**` matches any number of folders.

### Stream files

| Check | Severity | What it means | How to fix |
|---|---|---|---|
| Files outside stream/ | Error | `.yft`, `.ytd`, `.ydr` or `.ydd` not under `stream/`. Listing them in `files { }` does not stream them. | Move them into `stream/` (subfolders are fine). |
| Stream folder spelled differently | Warning | `Stream/` or `STREAM/`. Linux hosts do not find it. | Rename to lowercase `stream`. |
| Exported XML or openFormats file | Error | `.yft.xml`, `.ytd.xml`, `.oft`, `.otd` and so on. The game only loads compiled files. | Import in CodeWalker (or OpenIV) and save the binary, delete the export. |
| Not a GTA V resource file | Error | Empty, damaged or renamed from another format (not checked for escrowed resources). | Re-export the file or get a fresh copy from the author. |
| Enhanced edition (RSC8) asset | Error | FiveM runs the Legacy game and cannot load RSC8. | Use the Legacy version or convert it with CodeWalker. |
| Wrong resource version | Warning | Expected `yft` 162, `ytd` 13, `ydr` 165, `ydd` 165. Usually a file renamed to the wrong extension. | Check the file really is what its extension says. |
| Same file twice in one resource | Warning | Streaming uses the file name only, so one silently replaces the other. | Keep one copy. |
| Meta or script inside stream/ | Warning | Files in `stream/` are streamed as assets, not loaded as data. | Move metas to `data/` and load them with `data_file`. Scripts go in `client_scripts`. |

### vehicles.meta

| Check | Severity | What it means | How to fix |
|---|---|---|---|
| Defines no vehicles | Warning | `<InitDatas>` is missing or empty. | Check the file was not saved half way. |
| No modelName | Error | An entry without `<modelName>`. | Set it to the `.yft` name without extension. |
| No .yft for modelName | Error | The car cannot spawn ("model does not exist"). If the name is a base game car, it is a Note instead: the entry edits that car. | Stream `<model>.yft` or fix `<modelName>`. |
| `_hi.yft` missing | Warning | No high detail model, the car can look low poly or flicker up close. | Stream `<model>_hi.yft` (a copy of the `.yft` works). |
| No txdName | Error | Entry without `<txdName>`. | Set it to the model name and stream `<model>.ytd`. |
| txdName has no .ytd | Error | Not in the pack, not a model name, not a shared game txd. Car renders white, checkered or not at all. | Stream the `.ytd` or point `txdName` at the right one. If `<model>.ytd` exists, the fix says to use it. |
| `<model>.ytd` exists but txdName differs | Warning | The model's own `.ytd` is streamed for nothing. | Set `<txdName>` to the model name if that is where the textures are. |
| Layout does not exist | Error | Not a base game layout and not in a loaded vehiclelayouts.meta. Breaks entering the car or crashes. | Use `LAYOUT_STANDARD`, `LAYOUT_LOW` or ship the layouts file. |
| Unknown vehicle type | Warning | `<type>` is not a game type. | Usually `VEHICLE_TYPE_CAR`. |
| Unknown vehicle class | Warning | `<vehicleClass>` is not a game class. | Use one the finding lists. |
| No display name | Note | No `AddTextEntry` for `<gameName>` in the resource's Lua, so menus show NULL. | Add `AddTextEntry('<gameName>', 'Your Car Name')` in a client script. |
| txd parent does not exist | Warning | `<txdRelationships>` parent is not in the pack or the game. | Point it at a `.ytd` in the pack or a shared game txd like `vehshare`. |
| txd child is not in the pack | Note | The relationship does nothing. | The child is usually the car's `txdName`. |
| modelName has special characters | Warning | Spaces and symbols break spawn commands and garages. | Use a-z, 0-9 and `_`, rename files to match. |
| No carvariations entry | Warning | No default colours and no mod kit, tuning menus stay empty. | Add an entry with colours and `<kits>` (`0_default_modkit` if no custom parts). |
| Also a base game car | Warning | A streamed `.yft` with a base game model name replaces that car for everyone, traffic too. | Rename the model if it is meant as a new car. |

### handling.meta

| Check | Severity | What it means | How to fix |
|---|---|---|---|
| No handlingId | Error | Entry without `<handlingId>`. | Set it to a `<handlingName>` from handling.meta. |
| handlingId not in any handling.meta | Error | Keeps the car from spawning or crashes the client. | Add the handling entry or fix the id. |
| Uses base game handling | Note | The id is a base game handling name. | Fine if on purpose. |
| handling without handlingName | Error | Empty `<handlingName>`. | Use the name vehicles.meta refers to. |
| handling not used | Note | No vehicle in the pack uses it. | Check for a typo or remove it. |
| handling changes a base game car | Warning | The name is a base game handling, so every car of that model on the server drives differently. | Rename it and point `handlingId` at the new name. |
| handlingName defined more than once | Warning | Only the last one loaded is used, start order decides. | Keep one, or give each car its own name. |

### Mod kits (carcols and carvariations)

| Check | Severity | What it means | How to fix |
|---|---|---|---|
| carvariations for an unknown model | Warning | No vehicles.meta defines that `modelName`. | Fix the typo or add the missing vehicles.meta. |
| No mod kit | Note | `<kits>` is empty, tuning menus show nothing. | Add `<Item>0_default_modkit</Item>` or the car's own kit. |
| Kit not in any carcols.meta | Warning | The car gets no tuning parts. | Match the `<kitName>` exactly or load the carcols.meta that has it. |
| Kit has no numeric id | Error | `<id value="..." />` missing or not a number. | Give every kit a unique id. |
| Kit id above 65535 | Error | Kit ids are 16 bit, it wraps and collides. | Pick an unused id between 1000 and 65535. |
| Kit id used by the base game | Warning | Tuning parts get mixed with a game car's kit. Game ids run 0 to 640 and 999. | Move yours above 1000 and keep a list across your packs. |
| Kit not used by any car | Note | No carvariations entry lists it. | Add it to the car's `<kits>`. |
| Tuning parts with no .yft | Warning | `visibleMods` or `linkMods` model missing, the part shows in the menu but is invisible. | Stream the `.yft` or remove the entry. |
| Kit id used by several kits | Error | Two kits with different names share an id, across resources too. | Give all but one a new id. |
| Kit name with different ids | Warning | carvariations picks kits by name, so only one is used. | Rename one kit and update its carvariations. |

### Sirens

| Check | Severity | What it means | How to fix |
|---|---|---|---|
| sirenSettings not defined | Warning | The id in carvariations exists in no carcols.meta or the game. Lights stay dark. | Load the carcols.meta with that siren id or use one that exists. |
| Siren id above 255 | Warning | FiveM keeps 8 bits, so 300 acts as 44 ([citizenfx/fivem issue 2612](https://github.com/citizenfx/fivem/issues/2612)). | Use a free id between 21 and 254. |
| Siren id taken by the base game | Warning | Game ids are 0 to 20. The patterns overwrite each other. | Pick a free id above that. |
| Siren settings share an id | Error | Also after the 255 wrap. Only one wins, other cars flash the wrong pattern. | Give each its own id and update `sirenSettings`. |

### Engine sound

| Check | Severity | What it means | How to fix |
|---|---|---|---|
| No audioNameHash | Note | Empty on a new model, so the car falls back to a generic engine. | Set it to a base car (`ADDER`, `SULTAN`) or your sound pack name. |
| Sound not in this pack's game.dat | Warning | The pack has sound files but none of its `.dat151.rel` files defines a sound with that name. | Check the spelling against the sound pack. |
| Sound is not a base game sound | Warning | No sound pack in the drop. Silent or default sound unless another resource streams it and starts first. | Ship the sound pack or use a base car name. |
| Audio file never loaded | Error | A `.dat151.rel`, `.dat54.rel` or `.dat10.rel` has no matching `AUDIO_GAMEDATA`, `AUDIO_SOUNDDATA` or `AUDIO_SYNTHDATA` line (or the wrong type). | Add `data_file '<TYPE>' '<path without the number and .rel>'` and list the `.rel` in `files { }`. |
| Sound folder has no AUDIO_WAVEPACK | Error | A folder of `.awc` files is never mounted. The car is silent. | Add `data_file 'AUDIO_WAVEPACK' '<folder>'` and list the `.awc` files. |

### Asset size

| Check | Severity | What it means | How to fix |
|---|---|---|---|
| Oversized asset | Warning over 16 MiB, Error over 48 MiB | The file's physical or virtual memory size, the number the server prints in its "Asset uses X MiB of physical memory" warning. FiveM says assets over 48 MiB "can and WILL lead to streaming issues". | `.ytd`: 2048 px is plenty for a body, 512 to 1024 for details, DXT1/BC1 without alpha. Models: fewer polygons, textures out to the `.ytd`. |
| Large file (header unreadable) | Warning | Escrowed or unreadable header and the file is over 16 MiB on disk. Only a hint. | Check it in CodeWalker. |

### File and folder names

| Check | Severity | What it means | How to fix |
|---|---|---|---|
| Resource folder name | Error with spaces, Warning with other symbols | `ensure` cannot start a name with spaces. | Rename to lowercase letters, numbers, `_` or `-`. |
| Paths with spaces | Warning | Break globs and some hosting panels. | Use underscores and update metas and manifest. |
| Stream files with special characters | Warning | The asset name no longer matches what the metas ask for. | Rename to plain lowercase names. |
| Stream files with uppercase | Note | Works, the game ignores case. | Lowercase avoids typos. |
| Escrowed resource | Note | `.fxap` found. Only runs with the owning license key, sizes are estimated. | Do not rename or move escrowed files. |

### Conflicts between resources

| Check | Severity | What it means | How to fix |
|---|---|---|---|
| modelName defined more than once | Error | Only one definition wins, start order decides. | Keep one, or rename a car. |
| Stream files in several resources | Warning | One finding per group of resources that share file names. The last started wins. | Often the same car installed twice: remove one. |

Handling, kit, kit name and siren duplicates across resources are also listed under Conflicts.

## Example

A typical manifest from the fxmanifest tab for a car with its own engine sound:

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

client_scripts {
    'client.lua',
}

files {
    'data/handling.meta',
    'data/vehicles.meta',
    'data/carcols.meta',
    'data/carvariations.meta',
    'audioconfig/mycar_game.dat151.rel',
    'audioconfig/mycar_sounds.dat54.rel',
    'sfx/dlc_mycar/*.awc',
}

data_file 'HANDLING_FILE' 'data/handling.meta'
data_file 'VEHICLE_METADATA_FILE' 'data/vehicles.meta'
data_file 'CARCOLS_FILE' 'data/carcols.meta'
data_file 'VEHICLE_VARIATION_FILE' 'data/carvariations.meta'
data_file 'AUDIO_GAMEDATA' 'audioconfig/mycar_game.dat'
data_file 'AUDIO_SOUNDDATA' 'audioconfig/mycar_sounds.dat'
data_file 'AUDIO_WAVEPACK' 'sfx/dlc_mycar'
```

And the display name the "No display name" note asks for:

```lua title="client.lua"
CreateThread(function()
    AddTextEntry('MYCAR', 'My Car GT')
end)
```

## Tips

- Drop all your car resources at once. Kit id, siren id, handling and stream file clashes only show up when the tool sees both sides.
- Keep one list of the kit and siren ids you use across packs. Base game kits run up to 640 (and 999), sirens up to 20.
- Links with `?sample` open the tool with the sample pack loaded, and `?tab=vehicles` or `?tab=manifest` picks the tab that opens after a check.

> [!WARNING]
> If a check is clean and a car still misbehaves, open the F8 console while you spawn it and look for streaming errors. This tool does not open the models.

## Limitations

- It reads metas and file headers. It does not open the models, so it cannot see a broken mesh, missing bones or a wrong embedded texture.
- Escrowed (`.fxap`) stream files are encrypted, so their memory size is estimated from the file size.
- A sound that another resource provides cannot be seen from here. The finding says so instead of calling it broken.
- Handling values themselves are not judged. Use the handling editor for that.
- Everything runs in your browser. Nothing is uploaded.

## Related tools

- [Vehicle Handling Editor](/docs/tools/vehicle-handling-editor)
- [Vehicle Sirens](/docs/tools/vehicle-sirens) to build siren settings with free ids
- [YTD Optimizer](/docs/tools/ytd-optimizer) for oversized texture dictionaries
- [Native Audio Builder](/docs/tools/native-audio-builder) for custom sound banks
- [fxmanifest Generator](/docs/tools/fxmanifest-generator)

_Last updated: 2026-09-22_

---

## YMT Creator

URL: https://fivemad.com/docs/tools/ymt-creator

Turn a folder of addon clothing .ydd and .ytd files into a streamable pack: ped variation .ymt, shop meta, fxmanifest and correctly renamed stream files.

The YMT Creator builds the ped variation `.ymt` for an addon clothing pack from the names of its `.ydd` and `.ytd` files. Drop the pack, and you get the `CPedVariationInfo` XML, the shop `.meta` that registers the collection, the `fxmanifest.lua`, and every stream file renamed to the name the game expects. It is for server owners who stream clothing for `mp_m_freemode_01` and `mp_f_freemode_01`.

## What it is for

Addon clothing needs three things to show up in game: files named in a strict pattern with the collection prefix, a `.ymt` that lists every drawable and texture per component, and a shop meta loaded with `SHOP_PED_APPAREL_META_FILE`. Get one number wrong and a top is invisible, a texture is purple or the whole pack does not load.

Use this tool when you:

- bought or made a clothing pack that ships loose files (`jbib_000_u.ydd`, `jbib_diff_000_a_uni.ytd`) and no ymt,
- want to add, remove or reorder drawables in an existing pack without renaming 300 files by hand,
- have a `.ymt.xml` from someone else and want to check or edit it.

## Quick start

1. Open **Add files**, **Files** tab, and drop the pack folder (or use **Pick a folder**). Put male files in a `male` folder and female files in a `female` folder, or use files that already carry the `mp_m_freemode_01_<name>^` prefix.
2. Set **Collection name** in the **Pack** panel. It must be unique on your server, lowercase.
3. Fix what the issue list in the right column points out. Click an issue to jump to the drawable.
4. Reorder drawables with the arrow buttons if you want another order in game. The number on each card is the number the drawable gets.
5. In **Export**, **Files** tab, press **Download my_clothes.zip** (named after your collection). It contains `stream/` with every file renamed, `fxmanifest.lua`, the `.meta` files and a `convert_in_codewalker/` folder with the ymt XML.
6. Convert the XML in CodeWalker (steps in the **Convert** tab) and put the `.ymt` files in `stream/`.
7. `ensure` the resource, restart the server and reconnect.

Want to see it with data first? The **Names** tab has **Fill an example**, and opening the tool with `?example` in the URL loads the same made up pack.

## Input file names

The tool reads everything from file names, so they must follow the game's pattern. Folders are allowed, and the `^` prefix is optional on input.

| File | Pattern | Example |
|---|---|---|
| Component model | `<slot>_<000>_<u or r>.ydd` | `jbib_000_u.ydd` |
| Component texture | `<slot>_diff_<000>_<letter>_<race>.ytd` | `jbib_diff_000_a_uni.ytd` |
| Alternate model | `<slot>_<000>_<u or r>_<1-9>.ydd` | `hair_000_u_1.ydd` |
| Cloth physics | `<slot>_<000>_<u or r>.yld` | `jbib_000_u.yld` |
| Prop model | `p_<anchor>_<000>.ydd` | `p_head_000.ydd` |
| Prop texture | `p_<anchor>_diff_<000>_<letter>.ytd` | `p_head_diff_000_a.ytd` |

- `_u` drawables use `_uni` textures. `_r` drawables draw skin and use a race suffix, usually `_whi`.
- Texture letters run `a` to `z`, so at most 26 textures per drawable.
- Prop textures have no race suffix.
- Only diffuse textures (`_diff_`) belong in the ymt. Normal and specular maps are skipped with a message.
- Names that almost match (1 or 2 digit numbers, a missing `_u`, a missing race suffix) are still read and get a note on the card. The export renames them to the standard form.
- `.ymt.xml` files dropped here are imported (see Import below).

**Gender** comes from, in this order: a `mp_m_freemode_01...` or `mp_f_freemode_01...` prefix, then the nearest folder called `male`, `female`, `men`, `women`, `m`, `f` and similar (also inside names like `[female]` or `my_pack_female`). Files with neither go to **Gender for files without one**, and the log tells you how many did.

**Collection name**: if all dropped files share one prefix (`mp_m_freemode_01_mybrand^...`) and the pack is still empty with the default name, the name is taken from that prefix.

### Names tab

When the files are on your server and not on this PC, paste the names, one per line, with or without folders and the `^` prefix. The output of `dir /b /s` or `ls -R` works too. Press **Add names**. Everything works the same except the zip, which needs the real files.

### Import tab

Open a ped variation `.ymt.xml` exported from CodeWalker (**Open .ymt.xml**) or paste it and press **Load pasted XML**. It replaces the drawables of that gender (undo brings them back). The gender comes from the file name (`mp_f_freemode_01...`), otherwise from the Male / Female switch next to the button. The collection name is read from the file.

Kept from an import: propMask, alternates, cloth flag, texture races, audio, flags, heel and hat values, inclusions and exclusions, prop render flags, and `aSelectionSets` as raw XML. The log lists anything odd in the file (unused component blocks, prop ids with gaps, wrong texture counts) and ends with a **Re-export check** line that says whether the generated XML has the same content as the file.

## Pack settings

| Field | What it does | Default |
|---|---|---|
| Collection name | The collection (DLC) name. Files become `mp_m_freemode_01_<name>^jbib_000_u.ydd`. Lowercase letters, digits and `_`; other characters are replaced when you leave the field. | `my_clothes` |
| Gender for files without one | Where files go when neither prefix nor folder says the gender. | Male |
| Male ped / Female ped | Under **Ped names and header flags**. Change only for an addon ped with its own ymt. | `mp_m_freemode_01`, `mp_f_freemode_01` |
| bHasTexVariations and bHasDrawblVariations true | Writes `true` in both header fields. The game's DLC clothing ymts write false, grzyClothTool writes true, both load. | off |

The **Pack** panel also has **Undo** (last add, move, delete or import, 40 steps) and **Clear** (removes every drawable, keeps name and peds). Your pack is saved in the browser. Dropped files themselves are not kept after a reload, so drop them again before you download the zip.

## Drawables

The **Drawables** panel has a **Male** and **Female** tab with counts. Drawables are grouped by slot, each group shows its drawable and texture count and an **Add** button for an empty drawable. **Start another slot...** plus **Add drawable** at the bottom starts a slot that has nothing yet.

Each card shows the number it will get (`000`, `001`...), the race suffix, one chip per texture letter (amber when the race does not fit the drawable), and the source file with its memory size. The buttons move it one number up or down, or remove it. Click the card to open it.

### Card fields

| Field | What it does |
|---|---|
| Slot | Moves the drawable to another component or prop anchor. It is appended at the end of that slot. |
| Race suffix | `_u` or `_r`. Switching updates the textures (`_uni` or `_whi`) and the skin bit of propMask. Components only. |
| propMask | `1` plain (`_u` clothing), `17` with skin (`_r` clothing), `19` with skin variant. Presets also list 3, 5, 9 (game hair), 11 (game hair, masks) and 65. |
| numAlternatives | Extra models named `_u_1.ydd`, `_u_2.ydd` (hair under hats). 0 to 9. |
| Cloth physics | **Has .yld cloth** when a `.yld` ships with the model (ownsCloth). Set automatically when you drop one. |
| Audio | `pedXml_audioID` for components, `audioId` for props. Suggestions per slot, like `shoe_trainers`, `shoe_heels`, `cloth_upper_jacket_leather`, `cloth_lower_pants_denim`. `none` is fine. New shoes default to `shoe_trainers`. |
| High heels | Shoes (feet) only. Heel height, the game's heels use `1`. `0` is off. |
| Hair scale under the hat | Hats (`p_head`) only. Squashes hair so it does not poke through. Game hats use `0.5`. `0` is off. |
| renderFlags | Props only: none, `PRF_ALPHA`, `PRF_DECAL`, `PRF_CUTOUT`. |
| compInfo flags / propFlags | Bulky, Job, Sunny, Wet, Cold, Not in car, Bike only, Not indoors, Fire retardant, Armoured, Lightly armoured, High detail, Default helmet, Random helmet, Script helmet, Flight helmet, Hide in first person, Use physics hat 2, Pilot helmet, Wet: more wet, Wet: less wet. |
| Textures | One row per letter with its race (`uni`, `whi`, `bla`, `chi`, `lat`, `ara`, `bal`, `jam`, `kor`, `ita`, `pak`) and file. **Add texture** adds the next letter, up to 26. |

The right side of an open card shows **Streams as** (the final file names) and the Lua line to put it on a ped.

### Components and props

| Id | Component | Holds | Prop anchor | Holds |
|---|---|---|---|---|
| 0 | `head` | Heads | `p_head` | Hats |
| 1 | `berd` | Masks | `p_eyes` | Glasses |
| 2 | `hair` | Hair | `p_ears` | Earrings |
| 3 | `uppr` | Arms (torso) | `p_mouth` | Mouth |
| 4 | `lowr` | Legs | `p_lhand` | Left hand |
| 5 | `hand` | Bags and parachutes | `p_rhand` | Right hand |
| 6 | `feet` | Shoes | `p_lwrist` | Watches |
| 7 | `teef` | Chains, ties | `p_rwrist` | Bracelets |
| 8 | `accs` | Undershirts | `p_hip` | Hip |
| 9 | `task` | Body armor | `p_lfoot` | Left foot |
| 10 | `decl` | Decals | `p_rfoot` | Right foot |
| 11 | `jbib` | Tops | `p_ph_l_hand` | Left hand (ph) |
| 12 | | | `p_ph_r_hand` | Right hand (ph) |

> [!IMPORTANT]
> Drawable numbers are positions. The game reads the Nth model of a slot as drawable N, so numbers must run 000, 001, 002 without gaps. The tool numbers drawables in list order and renames the files to match, so a gap in your source files closes up and later files get new numbers.

## Checks

| Severity | Check |
|---|---|
| Error | No collection name; a game collection name (`male_heist`, `female_freemode_beach` and the like); empty ped name; drawable with no texture; more than 26 textures; more than 256 drawables in one slot; two models with the same number; texture in a folder of the other gender than its drawable; file without a valid game header (broken, encrypted or renamed); a file over 48 MiB of memory; a gender whose drawables have no textures at all. |
| Warning | Collection name with capitals or symbols; name over 40 characters; textures without a matching `.ydd`; files not used (with the reason); the same texture letter twice (`_a_uni` and `_a_whi`); race suffix mismatch; skin bit on a `_u` drawable; `_r` drawable without the skin bit; `.ydd.xml` models instead of binary; files over 16 MiB of memory; files over 16 MB on disk; ownsCloth without a `.yld`; numAlternatives higher than the alternates dropped; heel height on something that is not a shoe; hair scale above 1. |
| Note | Gaps in drawable numbers (files get renamed); texture letters with gaps or not starting at `a`; names that do not follow the pattern; heel height above 1.5; addon heads (freemode characters use head blends, masks go in `berd`). |

## Output

### Export tabs

- **YMT**: the `mp_m_freemode_01_<name>.ymt.xml` for the selected gender (switch appears when the pack has both).
- **Files**: a table of every stream file, source name on the left and final name on the right; **Download <name>.zip**; and a copy script.
- **Resource**: the folder layout, `fxmanifest.lua`, the shop `.meta`, and the creature metadata XML when needed.
- **Convert**: the CodeWalker steps.

### Stream file names

| File | Name |
|---|---|
| Component model | `mp_m_freemode_01_<name>^jbib_000_u.ydd` |
| Component texture | `mp_m_freemode_01_<name>^jbib_diff_000_a_uni.ytd` |
| Alternate model | `mp_m_freemode_01_<name>^hair_000_u_1.ydd` |
| Cloth physics | `mp_m_freemode_01_<name>^jbib_000_u.yld` |
| Prop model | `mp_m_freemode_01_p_<name>^p_head_000.ydd` (note the `_p_`) |
| Prop texture | `mp_m_freemode_01_p_<name>^p_head_diff_000_a.ytd` |
| Variation data | `stream/mp_m_freemode_01_<name>.ymt` |
| Shop meta | `mp_m_freemode_01_<name>.meta` in the resource root |
| Creature metadata | `stream/mp_creaturemetadata_m_<name>.ymt` (only with heels or hat hair scale) |

Female files use `mp_f_freemode_01` the same way. The `^` stands for a folder: FiveM streams `a^b.ydd` as `b.ydd` inside `a`, the same layout as the game's DLC archives.

### Zip and copy script

**Download <name>.zip** renames the dropped files into `<name>/stream/`, adds `fxmanifest.lua`, the `.meta` per gender, and `convert_in_codewalker/` with the `.ymt.xml` (and `.ymt.rbf.xml` for creature metadata). Files added by typed name or import have no source and are left out; the message after the download says how many. Packs over 1.5 GB are too big for a browser zip, use the script instead.

The copy script comes as **PowerShell** or **bash**. Set **Output folder** (defaults to the collection name) and run it inside the folder you dropped. It copies every file to `<output>/stream/<final name>` and never moves or deletes anything.

```powershell title="rename_my_clothes.ps1"
# Copies the clothing files of "my_clothes" into my_clothes/stream with the names the ymt expects.
# Run it in the "my_clothes" folder. Your files are copied, not moved.
$ErrorActionPreference = 'Stop'
New-Item -ItemType Directory -Force -Path 'my_clothes/stream' | Out-Null
Copy-Item -LiteralPath 'male/jbib_000_u.ydd' -Destination 'my_clothes/stream/mp_m_freemode_01_my_clothes^jbib_000_u.ydd'
Copy-Item -LiteralPath 'male/jbib_diff_000_a_uni.ytd' -Destination 'my_clothes/stream/mp_m_freemode_01_my_clothes^jbib_diff_000_a_uni.ytd'
Copy-Item -LiteralPath 'male/jbib_diff_000_b_uni.ytd' -Destination 'my_clothes/stream/mp_m_freemode_01_my_clothes^jbib_diff_000_b_uni.ytd'
Write-Host "Copied 3 files to my_clothes/stream"
```

### The ymt XML

For a male pack with one top and two textures:

```xml title="mp_m_freemode_01_my_clothes.ymt.xml"
<?xml version="1.0" encoding="UTF-8"?>
<CPedVariationInfo name="my_clothes">
 <bHasTexVariations value="false" />
 <bHasDrawblVariations value="false" />
 <bHasLowLODs value="false" />
 <bIsSuperLOD value="false" />
 <availComp>255 255 255 255 255 255 255 255 255 255 255 0</availComp>
 <aComponentData3 itemType="CPVComponentData">
  <Item>
   <numAvailTex value="2" />
   <aDrawblData3 itemType="CPVDrawblData">
    <Item>
     <propMask value="1" />
     <numAlternatives value="0" />
     <aTexData itemType="CPVTextureData">
      <Item>
       <texId value="0" />
       <distribution value="255" />
      </Item>
      <Item>
       <texId value="0" />
       <distribution value="255" />
      </Item>
     </aTexData>
     <clothData>
      <ownsCloth value="false" />
     </clothData>
    </Item>
   </aDrawblData3>
  </Item>
 </aComponentData3>
 <aSelectionSets itemType="CPedSelectionSet" />
 <compInfos itemType="CComponentInfo">
  <Item>
   <pedXml_audioID>none</pedXml_audioID>
   <pedXml_audioID2>none</pedXml_audioID2>
   <pedXml_expressionMods>0 0 0 0 0</pedXml_expressionMods>
   <flags value="0" />
   <inclusions>0</inclusions>
   <exclusions>0</exclusions>
   <pedXml_vfxComps>PV_COMP_HEAD</pedXml_vfxComps>
   <pedXml_flags value="0" />
   <pedXml_compIdx value="11" />
   <pedXml_drawblIdx value="0" />
  </Item>
 </compInfos>
 <propInfo>
  <numAvailProps value="0" />
  <aPropMetaData itemType="CPedPropMetaData" />
  <aAnchors itemType="CAnchorProps" />
 </propInfo>
 <dlcName>hash_8AB05D7E</dlcName>
</CPedVariationInfo>
```

What the main fields mean:

| Field | Meaning |
|---|---|
| `availComp` | 12 numbers, one per component: the index of its block in `aComponentData3`, `255` when the pack has none. |
| `numAvailTex` | Total textures of all drawables in the component. |
| `propMask` | `1` plain clothing, `17` for `_r` drawables that draw skin. |
| `texId` | Texture race for components: 0 uni, 1 whi, 2 bla, 3 chi, 4 lat, 5 ara, 10 pak. For props, the texture position. |
| `distribution` | Random pick weight, 255 on every game texture. |
| `compInfos` | One entry per drawable: audio, expressionMods (heel height in the 5th value), flags. |
| `aAnchors` | Per prop anchor, the texture count of each prop drawable. |
| `dlcName` | Hash of the collection name. Must match `dlcName` in the shop meta. |

### Resource files

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

files {
  'mp_m_freemode_01_my_clothes.meta',
  'mp_f_freemode_01_my_clothes.meta'
}

data_file 'SHOP_PED_APPAREL_META_FILE' 'mp_m_freemode_01_my_clothes.meta'
data_file 'SHOP_PED_APPAREL_META_FILE' 'mp_f_freemode_01_my_clothes.meta'
```

```xml title="mp_m_freemode_01_my_clothes.meta"
<?xml version="1.0" encoding="UTF-8"?>
<ShopPedApparel>
  <pedName>mp_m_freemode_01</pedName>
  <dlcName>my_clothes</dlcName>
  <fullDlcName>mp_m_freemode_01_my_clothes</fullDlcName>
  <eCharacter>SCR_CHAR_MULTIPLAYER</eCharacter>
  <creatureMetaData>mp_creaturemetadata_m_my_clothes</creatureMetaData>
  <pedOutfits />
  <pedComponents />
  <pedProps />
</ShopPedApparel>
```

The `.meta` registers the collection. Without it the game never loads the `.ymt` and the addon drawables do not exist. It goes next to `fxmanifest.lua`, not in `stream/`. A pack with only one gender gets one meta and one line.

```text
my_clothes/
  fxmanifest.lua
  mp_m_freemode_01_my_clothes.meta
  stream/
    mp_m_freemode_01_my_clothes.ymt
    mp_m_freemode_01_my_clothes^jbib_000_u.ydd
    mp_m_freemode_01_my_clothes^jbib_diff_000_a_uni.ytd
    mp_m_freemode_01_my_clothes^jbib_diff_000_b_uni.ytd
```

### Heels and hats

Set **High heels** on a shoe or **Hair scale under the hat** on a hat and the **Resource** tab adds `mp_creaturemetadata_<m|f>_<name>.ymt.rbf.xml`. Keep the `.ymt.rbf.xml` name so CodeWalker converts it in the right format, then stream the resulting `mp_creaturemetadata_m_<name>.ymt`. The shop meta always names it in `creatureMetaData`; when you use neither heels nor hat hair scale, that file simply does not exist, which is harmless.

### Converting to binary

1. Download `mp_m_freemode_01_<name>.ymt.xml` (YMT tab) into an empty folder. Keep the double extension.
2. In CodeWalker open **RPF Explorer**, then **File, Open Folder** on that folder.
3. Turn on **Edit mode** and use **Edit, Import XML** (or drag the file in). CodeWalker writes the `.ymt`.
4. Do the same for the other gender and for any creature metadata file.
5. Put the `.ymt` files in `stream/` with the renamed `.ydd` and `.ytd`, keep the `.xml` files out of it.
6. `ensure` the resource, restart the server and reconnect.

## Using the clothes in scripts

Addon drawables come after the game's own, so their global number shifts whenever the game adds clothes. Use the collection natives with your collection name and the local number shown on each card:

```lua title="client.lua"
local ped = PlayerPedId()

-- top 000 of my_clothes, texture a
SetPedCollectionComponentVariation(ped, 11, 'my_clothes', 0, 0, 0)

-- hat 000 of my_clothes, texture a
SetPedCollectionPropIndex(ped, 0, 'my_clothes', 0, 0, true)

-- how many tops the pack added
print(GetNumberOfPedCollectionDrawableVariations(ped, 11, 'my_clothes'))
```

More on these natives: [collection based natives](https://docs.fivem.net/docs/scripting-manual/using-new-game-features/collection-based-natives/).

## Common mistakes

- **Nothing shows up.** The `.meta` is missing from `files` or `data_file`, the ymt is still XML, or its name does not match the `^` prefix of the files.
- **Invisible or wrong drawable.** A gap in the numbers, or the ymt lists more drawables than there are files. Stream the renamed files from the zip or script, not your originals.
- **Purple or missing texture.** Texture letter or race suffix does not match: `_u` needs `_uni`, `_r` needs `_whi`.
- **Skin looks broken.** `_r` drawable with propMask 1. Use 17.
- **Two packs clash.** Every pack on the server needs its own collection name.
- **Server console size warnings.** FiveM warns above 16 MiB of memory per asset and calls anything over 48 MiB oversized. Downsize the textures (2048 px is usually enough for clothing).

> [!TIP]
> Adding clothes to a pack later? Import the pack's `.ymt.xml`, then drop the pack's files plus the new ones. Files with a number the ymt already has are attached to that drawable, new numbers are added at the end of their slot, so existing drawables keep their numbers.

## Limitations

- It writes XML. The binary `.ymt` comes from CodeWalker.
- It does not open or edit the models or textures. Use the other clothing tools for that.
- Only `mp_m_freemode_01` and `mp_f_freemode_01` style packs are the target. Custom ped names work for the file names, but the shop meta still says multiplayer.
- Dropped files stay in your browser and are not uploaded. Only names, sizes and headers are read until you build the zip.

## Related tools

- [Clothing Designer](/docs/tools/clothing-designer)
- [Drawable Studio](/docs/tools/drawable-studio)
- [Texture Editor](/docs/tools/texture-editor)
- [YTD Optimizer](/docs/tools/ytd-optimizer) for oversized textures
- [joaat Hash Calculator](/docs/tools/hash-calculator)

_Last updated: 2026-09-22_

---

## YTD Optimizer

URL: https://fivemad.com/docs/tools/ytd-optimizer

How to shrink many .ytd files at once: pick a preset or your own size caps, review the plan per texture, run it and put the smaller files back in stream.

The YTD Optimizer takes a whole stream folder (or any pile of `.ytd` files) and makes the texture dictionaries smaller in one go. It caps texture sizes per type, turns opaque DXT5 into DXT1, compresses uncompressed textures and fixes missing mip chains, and shows you the memory saved per file before anything changes. It is for server owners fighting texture loss and FXServer memory warnings on vehicle packs, clothing packs and MLOs.

## What it is for

When a resource starts, FXServer checks every file in `stream/` and prints a warning for files that need a lot of physical memory. GTA has a fixed texture budget: when a player is near many heavy assets, the game runs out of room and drops things. Textures stay blurry, cars and clothes turn invisible, parts of the map do not render. That is "texture loss". Smaller dictionaries fix it for everyone, not only for players with weak PCs.

The **Physical** column in this tool is the number FXServer looks at.

| Size | What FXServer does |
| --- | --- |
| up to 16 MiB | Nothing, this is where you want every file. |
| over 16 MiB | Prints "Asset ... uses X MiB of physical memory". |
| over 32 MiB | Same warning, in yellow. |
| over 48 MiB | Adds "Oversized assets can and WILL lead to streaming issues (such as models not loading/rendering)". |
| over 64 MiB | Same, in red. |

The warning is not a hard limit, the file still streams. But it is a good sign of which files to fix first.

## Quick start

1. Make a copy of the resource you want to optimize.
2. Open the [tool](/tools/ytd-optimizer) and drop the resource folder, its `stream` folder or single `.ytd` files. **Choose folder** and **Choose .ytd files** do the same. Sub folders are searched; everything that is not a `.ytd` is ignored.
3. Pick a preset: **Safe**, **Balanced** (default) or **Strict**.
4. Look at the file table. **After** and **Saved** show the plan. Expand a file to see what happens to each texture and untick the ones you want to keep as they are.
5. Press **Optimize**.
6. Click a texture name to compare before and after.
7. Press **All as zip**, extract it over your copy of the resource and restart it.

## Rules

### Presets

| Preset | Colour maps | Normal maps | Spec maps | Skip up to | For |
| --- | --- | --- | --- | --- | --- |
| **Safe** | 2048 | 2048 | 2048 | 128 px | Anything players look at up close. Only textures above 2048 shrink, formats and mips get fixed. |
| **Balanced** | 2048 | 1024 | 1024 | 128 px | Most servers. Normal and spec detail is hard to see at 1024, big win on vehicles and MLOs. |
| **Strict** | 1024 | 512 | 512 | 64 px | Crowded servers and big packs (EUP, clothing, vehicle packs with dozens of cars). Check a few close up shots after. |

All three turn on **Opaque DXT5 to DXT1**, **Compress uncompressed** and **Rebuild missing mips**, leave **BC5 for normal maps** off, exclude `script_rt_*` and use **High** quality. Changing any setting switches the preset to **Custom**.

### Settings

| Setting | What it does |
| --- | --- |
| **Max size** | Longest side cap for colour maps and everything that is not a normal or spec map (4096 to 128). |
| **Normal maps** | Cap for normal maps. |
| **Spec maps** | Cap for specular maps. |
| **Skip up to** | Textures whose longest side is at or below this are left alone (Nothing, 32, 64, 128, 256 px). |
| **Opaque DXT5 to DXT1** | When the alpha of a DXT5 texture is fully opaque, store it as DXT1. Half the memory, pixels stay identical. Not applied to normal maps. |
| **Compress uncompressed** | A8R8G8B8 and similar to DXT1, or to DXT5 when the alpha is soft. |
| **Rebuild missing mips** | Adds the missing mip levels, down to 4 px as the game expects. The full size level is not touched. |
| **BC5 for normal maps** | Stores normal maps as ATI2 (BC5). Cleaner normals at DXT5 size, but many GTA shaders expect RGB normals, so test in game first. |
| **Exclude textures** | Name patterns, one per line or comma separated. `*` matches anything, `?` one character. |
| **Re-encode quality** | High or Fast. Only used when pixels really have to change. |

Normal and spec maps are recognised by their usage and their name (for example `_n`, `_nrm`, `_normal`, `_s`, `_spec`).

Always left as they are: BC7 textures, script render targets and A8 / L8 masks. Nothing is ever upscaled, and a texture is only halved until it fits the cap.

## How textures get smaller

Most changes do not touch the pixels at all:

- **Dropping mip levels.** A 2048 texture with a mip chain already holds 1024, 512 and so on. Capping it at 1024 removes the top level, nothing is compressed again. Each step saves three quarters of the memory.
- **Opaque DXT5 to DXT1.** Looks identical, half the size.
- **Missing mips** are added below the full size level, which stays the same.

**Re-encoding** only happens when the pixels have to change: uncompressed textures, BC5 normals, DXT3, or a downscale of a texture without mips. The plan marks those with `(re-encoded)`.

Name, usage and flags of every texture stay as they were, and the texture count never changes. Files where no texture changes are not rewritten.

## Summary panel

- **Physical memory**: total before, and the planned (or, after a run, the real) total after, with the amount and percentage saved.
- **Files**: files read so far.
- **Textures to change**: how many textures the plan touches, out of all textures.
- **Over 16 MiB now** and **After**: how many files FXServer would warn about.
- **Optimize** starts the run (turns into **Cancel** while it runs; finished files keep their result). **All as zip** downloads the result. **Add** adds more files.

## File table

Sort by **Most saved**, **Biggest** or **Name**. **Clear** empties the list.

| Column | Meaning |
| --- | --- |
| **File** | File name and folder. Click to expand the texture plan. |
| **Textures** | Textures to change / total. |
| **Physical** | Physical memory now. |
| **After** | Planned size, the real size after a run, or the progress while it runs. |
| **Saved** | Memory saved. |
| **Largest** | Size and format of the biggest texture. |
| **Notes** | The FXServer warning level, plus counts of textures over the cap, with missing mips, uncompressed or not a power of two, and read warnings. |

After a run, a **.ytd** button downloads that single file.

### Texture plan

Expanding a file shows every texture with **Now** and **After** (size, format, mip count, memory), **Saved** and **What happens**, for example `2048x2048 to 1024x1024 (drops 1 mip), opaque DXT5 to DXT1, lossless`. Textures that stay the same say why: `Already within the rules`, `Excluded by name`, `Script render target`, `BC7 is kept as is`, `Not above 128 px` and so on. **Sort by savings** puts the biggest wins on top.

Untick a texture to leave it exactly as it is. Unticked textures are copied over untouched.

### Compare

After a run, click a texture name to open the compare view: the original on the left and the result on the right, drawn at the same size with pixelated scaling so lost detail is easy to see. Drag across the image or use the **Split** slider to move the divider, and tick **Show alpha** to compare the alpha too.

## Report

A Markdown report under the table sums it up: preset and rules, textures changed (and how many without re-encoding), physical memory before and after, how many files FXServer warns about before and after, and the 20 files with the biggest savings. **Copy for Discord** copies it, **.md** downloads `ytd-optimizer-report.md`. Before a run it shows the plan, marked `(planned)`.

```bash
**YTD optimizer report**
Preset: Balanced (max 2048, normal maps 1024, spec maps 1024, skip up to 128 px, opaque DXT5 to DXT1, compress uncompressed, rebuild mips, exclude script_rt_*)
Files: 42, textures changed: 318 of 1204 (291 without re-encoding)
Physical memory: 812.40 MiB -> 401.77 MiB, saved **410.63 MiB** (50.5%)
Files FXServer warns about (over 16 MiB): 17 -> 3
```

The numbers above are an example layout; yours come from your files.

## Output

**All as zip** is named after the top folder of your drop, for example `stream_optimized.zip` or `my_cars_optimized.zip`. It keeps your folder layout and includes every file that was read, changed or not, so you can extract it straight over a copy of the resource.

## Put the files back

1. Extract **All as zip** over a copy of the resource (or copy the single `.ytd` downloads into `stream/`, same names).
2. Restart the resource and look at the server console: the memory warnings for these files should be gone.
3. Drive around, look at a few cars, clothes or interiors up close.
4. Keep the originals until you checked the result in game.

```cfg title="server.cfg"
ensure my_cars
```

No manifest change is needed: the files keep their names and stay in `stream/`.

## Tips

- Start with **Balanced**. Go **Strict** only on packs where memory is the real problem, like 50 EUP uniforms.
- Emissive and livery textures with text or logos suffer first. Add them to **Exclude textures** (for example `*_livery*` or `*_sign_*`) if they get too soft.
- Sort by **Most saved**: often a handful of files hold most of the memory.
- Rerun on the same files after changing the rules; press **Optimize** again and the new rules apply to the originals.

## Common mistakes

- **Optimizing the only copy.** Always work on a copy and keep the originals until you checked the result in game.
- **BC5 normals without testing.** Many GTA shaders expect RGB normal maps. Leave **BC5 for normal maps** off unless you tested it.
- **Mixing old and new files.** Extract the zip over the whole folder so no old `.ytd` is left next to a new one with a different path.

## Limitations

- Only `.ytd` files. Textures embedded in `.ydr`, `.ydd` or `.yft` files are not changed.
- Files protected by the Cfx asset escrow are encrypted and can not be read.
- BC7 textures, script render targets and A8 / L8 masks are left as they are.
- Everything runs in your browser. No files are uploaded.

## Related tools

- [Texture Editor](/docs/tools/texture-editor) to fix or replace single textures by hand.
- [Vehicle Pack Validator](/docs/tools/vehicle-pack-validator) to check a vehicle pack before you ship it.
- [Profiler Analyzer](/docs/tools/profiler-analyzer) to find what really costs frame time on your server.
- [Clothing Designer](/docs/tools/clothing-designer) for clothing textures.

_Last updated: 2026-09-22_

---

## Native Audio Builder

URL: https://fivemad.com/docs/tools/native-audio-builder

Turn WAV, MP3 or OGG files into a FiveM native audio resource and play them from Lua on the UI, on an entity or at a position, synced if you want.

The Native Audio Builder turns your sound files into a complete FiveM resource that plays them as real game audio: the `.awc` wave bank, the `.dat54.rel` sound data, `fxmanifest.lua` with the right `data_file` lines, and Lua to load the bank and play sounds. No CodeWalker step is needed. It is for script devs who want custom sounds without a NUI page.

## What it is for

Most servers play custom sounds through NUI, a hidden browser page with an audio tag. That works, but the game does not know the sound exists: no 3D position, no distance falloff, no game volume slider, and every client runs a browser page for it. Native audio puts your files into the game's own audio system, so `PlaySoundFrontend`, `PlaySoundFromEntity` and `PlaySoundFromCoord` play them like any Rockstar sound.

Typical uses: phone ringtones and notification sounds, a siren or horn attached to a vehicle, an alarm at a bank that everyone nearby hears, UI clicks for a custom menu, door buzzers and radio chatter.

Looking for a base game sound instead? Use the [Sound Browser](/docs/tools/sound-browser).

## Quick start

1. Open the tool and use **Choose audio files** or **Choose folder**, or drag files or a folder onto the page.
2. Check each sound's **Name** and **Sound set**. These are the two strings you pass to the play functions.
3. Set **Resource name** in the **Bank** panel (for example `my_sounds`). The wave pack, data file and default sound set follow it.
4. Press play on a row to hear what the game will get.
5. Tick **Loop** for sounds that should repeat until you stop them.
6. Fix anything shown in red, then press **Download resource**.
7. Unzip, put the `my_sounds` folder in your resources, add `ensure my_sounds` and run `/my_sounds_test` in game.

## Input

- Formats: WAV, MP3 and OGG work everywhere. FLAC, M4A, AAC, Opus and WebM work when your browser can decode them. Other files are skipped with a count.
- Up to 200 sounds per bank.
- Stereo and multichannel files are mixed down to mono, and every file is converted to the bank's sample rate. The row shows the length, the channel change and the rate change (for WAVs), for example `2.40 s, 2 ch to mono, 44100 to 32000 Hz`.
- Each file becomes one sound named after the file: lowercase, anything other than letters and digits becomes `_`, cut at 48 characters. `Door Buzzer (2).wav` becomes `door_buzzer_2`. A second file with the same name in the same set gets `_2`, `_3` and so on.
- The sound set comes from the folder the file is in. Drop `in/phone/ring.mp3` and `in/alerts/beep.wav` and you get the sets `phone` and `alerts`. Files dropped without a folder go into the **Default sound set**.
- Sounds whose name contains `loop` or `alarm`, or that sit in a set called `ringtone` or `ringtones`, start with **Loop** on.

Drop more files anywhere on the page at any time to add them. **Clear** removes every sound.

> [!NOTE]
> Everything runs in your browser. Your audio is decoded and converted locally and the zip is built on your PC. Nothing is uploaded.

## The sound list

Each row has:

| Control | What it does |
|---|---|
| Play / Pause | Preview after conversion: sample rate, mono downmix, trimming, normalizing, the codec, the row's volume and loop. What you hear is close to what the game plays. |
| Name | The sound name, first argument of the play natives. Lowercase letters, digits, `_` and `-`. |
| Sound set | The sound set name. Lowercase letters, digits and `_`. Existing sets are suggested as you type. |
| Volume dB | Volume stored in the sound, from `-60` to `+6`. Default `0`. |
| Loop | The sound repeats until you call `StopNative` (or `StopSound`). |
| Remove | Removes the sound from the bank. |

Under each row you see a small waveform, the source file name, length and conversion info, and **Copy call**, which copies a ready line like `exports['my_sounds']:PlayNative('beep', 'my_sounds_set')`. Problems for that sound are listed right under it.

## Bank settings

| Setting | What it does | Default |
|---|---|---|
| Resource name | Folder name of the resource and the name you `ensure`. Lowercase letters, digits, `_` or `-`. Changing it also updates the three names below while you have not edited them yourself. | `my_sounds` |
| Wave pack | Folder that holds the bank inside `audio/`, and the first half of the bank path in Lua. | `dlc_my_sounds` |
| Bank | File name of the `.awc`, second half of the bank path. | `sounds` |
| Data file | File name of the `.dat54.rel`. | `my_sounds_sounds` |
| Default sound set | Set for files dropped without a folder. **Apply to all** puts every sound in this set. | `my_sounds_set` |
| Codec | **ADPCM** is 4x smaller and lossy. **PCM** is lossless and 4x bigger. | ADPCM |
| Sample rate | 48000, 44100, 32000, 24000 or 22050 Hz. Every sound in the bank uses the same rate. | 32000 Hz |
| Category | The mix group the game puts the sounds in: `scripted_louder` or `scripted`. | `scripted_louder` |
| Trim silence | Cuts silence at the start and end, so sounds fire on time. | on |
| Normalize | Raises or lowers each sound so its peak sits at -1 dBFS. | off |
| Synced playback | Adds `server.lua` to play a sound for every player nearby. | on |
| CodeWalker source | Adds the `.awc.xml`, `.rel.xml` and WAVs next to the resource, for editing later. | on |

Wave pack, Bank and Data file allow lowercase letters, digits and `_` only.

The summary card shows the number of sounds, the total length and an estimated `.awc` size. Changing the sample rate, trim or normalize reconverts every sound; the download button waits until that is done ("Converting audio...").

### Choosing codec and rate

- **ADPCM** is fine for effects, voice and most music. Very hard edged synth sounds (square waves) lose detail, use PCM for those.
- **32 kHz** keeps banks small and is plenty for effects and UI sounds. Use 44.1 or 48 kHz for music.
- The whole bank is loaded into memory when a script requests it. Keep long music or big packs in a bank of their own (a second resource) and load it only when you need it.

## Checks

Errors block the download, warnings do not.

| Level | Check |
|---|---|
| Error | Resource name, Wave pack, Bank or Data file with characters that are not allowed; sound name with characters other than lowercase a-z, 0-9, `_`, `-`; name over 64 characters; sound set with characters other than lowercase a-z, 0-9, `_`; the same name twice in one sound set; two names that clash inside the bank or with each other (rename one); a sound that is empty after conversion (for example pure silence with Trim on); volume outside -60 to +6 dB; a sound set that already exists in the base game; a file the browser could not decode. |
| Warning | A sound longer than 30 seconds (the whole bank sits in memory once loaded). |

## Output

### What is in the zip

**Download resource** saves `<resource>.zip`:

```text
my_sounds/
  fxmanifest.lua
  client.lua                              load the bank, play, stop, free
  server.lua                              only with Synced playback
  audio/dlc_my_sounds/sounds.awc          the wave bank
  audio/data/my_sounds_sounds.dat54.rel   the sound data
codewalker_source/                        only with CodeWalker source
  sounds.awc.xml
  sounds/*.wav
  my_sounds_sounds.dat54.rel.xml
```

Put only the `my_sounds` folder in your server's resources. `codewalker_source` is for you, not for the server. The message under the button shows the exact size of the `.awc` and `.dat54.rel` after the download.

The code tabs under the list show `client.lua`, `server.lua` (with Synced playback), `fxmanifest.lua`, the `.rel.xml` and the `.awc.xml` before you download.

### fxmanifest.lua

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'
lua54 'yes'

description 'Native audio bank built with fivemad.com/tools/native-audio-builder'

client_script 'client.lua'
server_script 'server.lua'

files {
    'audio/data/my_sounds_sounds.dat54.rel',
    'audio/dlc_my_sounds/sounds.awc',
}

-- sound data: the path of the .dat54.rel without "54.rel"
data_file 'AUDIO_SOUNDDATA' 'audio/data/my_sounds_sounds.dat'
-- wave pack: the folder that holds the .awc bank
data_file 'AUDIO_WAVEPACK' 'audio/dlc_my_sounds'
```

```cfg title="server.cfg"
ensure my_sounds
```

> [!IMPORTANT]
> The `AUDIO_SOUNDDATA` path ends in `.dat`, not `.dat54.rel`, and `AUDIO_WAVEPACK` points at the folder, not the `.awc`. Both files must also be in `files { }`, or clients never download them. The generated manifest already does this, keep it that way if you merge it into another resource.

### client.lua

The generated `client.lua` loads the bank when the resource starts (it waits up to 10 seconds and prints an error if the bank does not load) and releases it when the resource stops. It defines these functions, all also available as exports:

| Function | What it does | Returns |
|---|---|---|
| `PlayNative(name, soundSet, loop)` | 2D sound (UI, phone, notifications) via `PlaySoundFrontend`. | sound id |
| `PlayNativeOnEntity(name, soundSet, entity, loop)` | 3D sound that follows a ped, vehicle or prop via `PlaySoundFromEntity`. | sound id |
| `PlayNativeAtCoords(name, soundSet, coords, range, loop)` | 3D sound at a position via `PlaySoundFromCoord`. `range` defaults to `20.0`. | sound id |
| `SetNativeVolume(id, volume)` | Changes the volume of a playing sound, `0.0` to `1.0`. | |
| `StopNative(id)` | Stops the sound and frees its id. | |

One shot sounds free their sound id by themselves when they finish. Looped sounds keep their id until you call `StopNative`, so store it. The `loop` argument only controls that cleanup; whether a sound actually repeats is set by the **Loop** toggle when you build the bank.

It also registers a test command named after the resource: `/my_sounds_test` plays every sound one after the other (looped ones for 5 seconds), `/my_sounds_test beep` plays just one.

## Examples

Inside the same resource (add your code to `client.lua` or another client script of the resource):

```lua title="client.lua"
-- UI sound
PlayNative('beep', 'my_sounds_set')

-- follows the vehicle
local veh = GetVehiclePedIsIn(PlayerPedId(), false)
PlayNativeOnEntity('horn', 'my_sounds_set', veh)

-- heard up to 30 m from the bank door
PlayNativeAtCoords('alarm', 'my_sounds_set', vector3(150.2, -1040.5, 29.4), 30.0)

-- looped ringtone at half volume, stopped later
local id = PlayNative('ringtone', 'my_sounds_set', true)
SetNativeVolume(id, 0.5)
Wait(8000)
StopNative(id)
```

From another resource, use the exports:

```lua title="phone/client.lua"
local ring = exports['my_sounds']:PlayNative('ringtone', 'phone', true)

RegisterNetEvent('phone:answered', function()
    exports['my_sounds']:StopNative(ring)
end)
```

### Synced playback

For everyone nearby to hear a sound, the server has to tell them. With **Synced playback** on, `server.lua` exports two functions that check each player's distance (needs OneSync) and send the sound only to players in range:

```lua title="bank_robbery/server.lua"
-- everyone within 30 m of the vault hears the alarm
exports['my_sounds']:PlayAtCoords('alarm', 'my_sounds_set', vector3(255.0, 225.0, 101.9), 30.0)

-- everyone within 30 m (the default) hears the horn on that networked vehicle
exports['my_sounds']:PlayOnEntity('horn', 'my_sounds_set', vehicle)
```

`PlayAtCoords` defaults to a 20 m range, `PlayOnEntity` to 30 m. The play natives also have an `isNetwork` argument, but it does not load your bank on the other clients, so the server event approach is the reliable one.

## Editing the bank later

With **CodeWalker source** on, the zip has everything to rebuild the bank in CodeWalker: open RPF Explorer, turn on edit mode, and drag `sounds.awc.xml` (with the `sounds` folder of WAVs next to it) and the `.dat54.rel.xml` into a folder. CodeWalker builds the binary files, drag them back into the resource. Or drop the WAVs into this tool again and download a new bank.

## Common mistakes

- **No sound at all.** The bank did not load: check the F8 console for "could not load audio bank", then check the `data_file` lines and that both files are in `files { }`. Restart the resource after changing the manifest and reconnect.
- **Wrong sound set or name.** Both strings are case sensitive in your scripts. Copy them with **Copy call**.
- **Sound plays only for you.** `PlayNative` is local. Use the server exports with Synced playback for sounds others must hear.
- **Looping sound never stops.** Keep the id returned by the play function and call `StopNative(id)`.
- **Name clash with the game.** Sound sets share one namespace with every game sound, so give them your own prefix. The tool refuses sets that already exist in the base game.
- **Huge bank.** A bank with ten minutes of music at 48 kHz is loaded into memory as a whole. Split music into its own resource.

## Limitations

- The page cannot play the finished `.awc` and `.rel` in the game itself, so test the resource on your own server before you ship it.
- Output is mono. Multichannel banks (the stereo format radio stations use) are not built here.
- One sample rate, codec and category per bank.
- Up to 200 sounds per bank.
- Files you drop are kept only for this page visit. After a reload, drop them again.

Based on [lb-nativeaudio](https://github.com/lbphone/lb-nativeaudio) by LB Scripts.

## Related tools

- [Sound Browser](/docs/tools/sound-browser) for base game sounds and sound sets
- [fxmanifest Generator](/docs/tools/fxmanifest-generator)
- [Vehicle Pack Validator](/docs/tools/vehicle-pack-validator) checks engine sound `data_file` lines in car packs

_Last updated: 2026-09-22_

---

## YMAP Builder

URL: https://fivemad.com/docs/tools/ymap-builder

Place props by coordinates or in a 3D world, get CodeWalker ready .ymap XML with correct rotations and extents, and stream it from a FiveM resource.

The YMAP Builder turns a list of props and positions into a `.ymap` placement file without opening a map editor. You paste coordinates from the game (or place props in the 3D world), set heading or full rotation, and the tool writes CodeWalker XML with the quaternions, entity extents, streaming extents and map flags already calculated. It is for server owners and devs who want a few benches, barriers or decorations streamed with the map instead of spawned by a script.

## What it is for

Props spawned with `CreateObject` live in a script: they need a thread, they need cleanup, and every client creates them again. A ymap is part of the map itself. The game streams it in when you get close and drops it when you leave, with no script at all. The catch is the file format: rotations are stored as an inverted quaternion, extents have to cover every entity plus its draw distance, and the map flags depend on the LOD levels you use. Get one of those wrong and props face the wrong way, pop out early or never load. This tool handles those parts so you only think about model, position and heading.

Typical jobs:

- Decorating a spot (benches, bins, barriers, plants) around an MLO or a job location.
- Turning a list of `vector4` spawn points from your config into static props.
- Editing an existing ymap XML: fix a rotation, move a group of props, change `lodDist` on everything.

## Quick start

1. Add the helper from **Grab positions in game** (bottom of the page) to a client script on your dev server. Stand where a prop should go and run `/ymappos`, or look at an existing prop and run `/ymapprop`. Finish with `/ymapdump`.
2. In **Import**, keep the **Coordinates** tab, paste the lines, pick a **Default model** and press **Add**.
3. Fine tune rows in **Entities**, or select several and use the bulk edit bar. Open **3D world** (desktop) to move them with a gizmo inside the GTA V map.
4. Set **Name** in the **Ymap** panel. It becomes the file name.
5. Check the warnings under the preview, then press **Download** on the **XML** tab of **Export**. You get `<name>.ymap.xml`.
6. Convert it to a binary `.ymap` with CodeWalker (see the **Convert** tab), put it in `stream/` of a resource and `ensure` it.

The page starts with three sample props at Vespucci Beach so you can see the output before adding your own. Your work is saved in the browser (local storage) and comes back when you reopen the page.

## Panels

### Ymap

| Field | What it does | Default |
| --- | --- | --- |
| **Name** | Ymap name and file name (`stream/<name>.ymap`). Lowercase letters, digits, `_` and `-` only; anything else is replaced on export. Must be unique across all your resources. | `my_props` |
| **Parent** | Parent ymap name, written to `<parent>`. Leave empty for standalone props. | empty |
| **Assumed entity radius (m)** | The tool does not know model sizes, so this radius (times the entity scale) stands in for each prop when the extents are filled in. Raise it for big props. | `10` |
| **lodDist when set to -1 (m)** | Entities with `lodDist -1` use the model's own draw distance. The extents still need a number, so this one is used. | `150` |
| **Scripted (flags 1)** | Sets map flag 1. The game then only loads the ymap after `RequestIpl('name')`. Leave it off for props that should always be there. | off |

**Undo** reverts the last structural change (add, delete, duplicate, reorder, import, bulk edit, 3D edits), up to 40 steps. Typing in a field is not recorded, to keep the history useful. **Clear** removes every entity, and Undo brings them back.

### Entities

Each row has a model field (with autocomplete from the vanilla objects list), `x`, `y`, `z` and `heading`. A model name that is not in the objects list is marked, and the row number turns amber when the row has a warning.

- **Add** appends a row 2 m east of the last one, with the same z and heading, using the model, flags and lodDist from the import defaults.
- Paste a whole `vector3(...)`, `vector4(...)` or a `/ymapprop` line into the **x** field and it fills x, y, z, heading (and pitch, roll and model when the line has them).
- The row buttons duplicate (the copy sits 1 m east) or delete that row. The chevron opens **More fields**.
- The checkbox bar on top selects rows. With a selection you get move up, move down, duplicate and delete for all of them, plus the bulk edit bar.
- Long lists show 60 rows at a time with a **Show more** button.

**More fields** per entity:

| Field | Written to | Notes |
| --- | --- | --- |
| **Rotation**: Heading only / Pitch / roll / yaw | `rotation` | Pitch/roll/yaw adds `pitch` and `roll` inputs and renames heading to `yaw`. The stored quaternion is shown next to it. |
| **lodDist** | `lodDist` | Draw distance in metres. `-1` uses the model's own value. Default `100`. |
| **childLodDist** | `childLodDist` | Only matters for LOD parents. Default `0`. |
| **priority** | `priorityLevel` | `REQUIRED`, `OPTIONAL_HIGH`, `OPTIONAL_MEDIUM`, `OPTIONAL_LOW`. |
| **lodLevel** | `lodLevel` | `ORPHANHD` for standalone props. HD, LOD and SLOD levels are for LOD chains. |
| **AO multiplier** | `ambientOcclusionMultiplier` | 0-255, default 255. |
| **artificial AO** | `artificialAmbientOcclusion` | 0-255, default 255. |
| **tint** | `tintValue` | Texture variation, same as `SetObjectTextureVariation`. |
| **scale xy / z** | `scaleXY`, `scaleZ` | Default 1. |
| **flags** | `flags` | Number field plus a preset menu and a **Flag bits** list with every known bit. |

Flag presets:

| Preset | Value | Use |
| --- | --- | --- |
| Static + shadows | `1572896` | Frozen prop that casts shadows. The default for new rows. |
| Static | `32` | Frozen prop, CodeWalker's default. |
| Dynamic + shadows | `1572864` | Physics on (if the model has physics), like most vanilla props. |
| Dynamic | `0` | Physics on, no extra bits. |

If an entity is tilted (pitch or roll not zero), flag `1` (allow full rotation) is added on export, and the flags editor says so. Without it the game ignores pitch and roll.

For entities loaded from an XML, `guid`, `parentIndex`, `numChildren` and any `extensions` block are kept and written back unchanged.

### Bulk edit

With rows selected, the bar under the toolbar edits all of them at once. Empty fields stay unchanged, offsets are added.

- **model**, **flags** (presets), **lodDist**, **priority**, **lodLevel**: replace the value.
- **offset x**, **offset y**, **offset z**: add to the position (move a whole group).
- **rotate heading by**: adds degrees to each heading. **set heading**: sets one heading for all (wins over rotate).
- **Apply to N** runs it, **Reset** empties the bar.

### Import: Coordinates

Paste one entity per line. It accepts `vector3`, `vector4`, `vec3`/`vec4`, `{x = , y = , z = , w = }`, JSON objects or arrays and plain numbers. A model name, `model=<hash>` or `rot=vector3(pitch, roll, yaw)` on the same line is picked up too. Model hashes are turned back into names when they are vanilla props, otherwise into `hash_XXXXXXXX`.

```lua
vector4(-1386.72, -1004.23, 3.86, 125.0)
{x = -1383.35, y = -1008.94, z = 3.86, w = 125.0}
prop_bin_07a vector3(-1385.1, -1006.62, 3.86)
model=prop_bench_01a pos=vector3(-1374.0, -1018.5, 3.86) rot=vector3(0.0, 0.0, 125.0)
```

| Option | What it does | Default |
| --- | --- | --- |
| **Default model** | Used for lines without a model. | `prop_bench_01a` |
| **Heading if missing** | Used for lines without a heading (vector3). | `0` |
| **Z offset (m)** | Added to every z. The **-1** link sets it for player coords. | `0` |
| **Flags for new rows** | Flag preset for the imported rows. | Static + shadows |
| **lodDist for new rows** | lodDist for the imported rows. | `100` |

**Add N** appends, **Replace all** replaces the list. Lines it cannot read are counted and the first five are listed.

### Import: Ymap XML

**Open .ymap.xml** or paste XML and press **Load pasted XML**. It replaces the current entities (Undo brings them back). Get the XML from CodeWalker: RPF Explorer, right click the ymap, Export XML. Rotations are read the way CodeWalker stores them and shown as in-game heading or pitch/roll/yaw. Sections the builder does not edit (car generators, occluders, LOD lights, time cycle modifiers and so on) are kept and written back as they were.

### Top-down preview

An SVG plan of every entity. The line on each dot shows its heading. Click a dot to jump to its row, <kbd>Shift</kbd> or <kbd>Ctrl</kbd> click to add it to the selection. The solid box is the entity extents; tick **Streaming extents** to also draw the dashed streaming box (the area in which the ymap is loaded).

### Warnings

The list under the preview checks your ymap as you edit. Click a warning to select the rows it is about.

- Missing or invalid name, empty model, invalid numbers.
- Models not in the vanilla objects list (fine for custom props, otherwise a typo).
- Two entities within 1 cm of each other, entities outside the playable map, entities at 0, 0.
- A ymap spanning a very large area, or more than 1000 entities (split it by area).
- `lodDist` under 20 m.
- HD levels without a LOD parent (use `ORPHANHD` for standalone props).
- Tilted entities that get flag 1 on export (info).

### 3D world

The **3D world** button in the preview panel (desktop only) opens the ymap inside the GTA V world at the top of the page, starting next to the active entity. Props that have a model in the Objects List show as the real mesh, others as a box of their real size (or a 1 m box). Everything you do there updates the entity list and the export right away, and Undo works for moves, rotations and placed props.

| Control | What it does |
| --- | --- |
| Click a prop | Select it (it becomes the active row). <kbd>Shift</kbd>, <kbd>Ctrl</kbd> or <kbd>Cmd</kbd> click adds it to the selection. |
| **Move** or <kbd>G</kbd> | Move gizmo (world axes). Drag an arrow or plane. |
| **Rotate** or <kbd>T</kbd> | Rotate gizmo (local axes). Heading-only entities only get the vertical ring; switch the row to Pitch / roll / yaw to tilt it. |
| **Place** | Pick a model, then click the ground to drop it. A ghost follows the mouse and the coordinates under it are shown. <kbd>R</kbd> turns it 15 degrees (<kbd>Shift</kbd> <kbd>R</kbd> the other way), <kbd>Esc</kbd> stops placing. |
| **Snap to ground** | Drops the selected entities (or the active one) so the model's lowest point rests on the ground or roof under it. Entities with no loaded ground under them are skipped and counted. |
| **Focus** | Moves the camera to the active entity. |
| Right mouse drag, <kbd>W</kbd> <kbd>A</kbd> <kbd>S</kbd> <kbd>D</kbd> | Look and move the freecam. Clicking does not capture the mouse here, so you can click props. |

The camera, quality setting and full screen work the same as in the [3D world](/docs/tools/world-3d) docs. **Close 3D** hides the panel again.

## Output

### Export tabs

- **XML**: a stats line (`entities`, map `flags`, `contentFlags`, entity extent size) and the full CMapData XML. **Download** saves it as `<name>.ymap.xml`.
- **Resource**: the folder layout, a ready `fxmanifest.lua`, and a `client.lua` with `RequestIpl` when **Scripted** is on.
- **Convert**: the CodeWalker steps below.

Each entity is written like this (a `prop_bench_01a` at heading 125):

```xml title="my_props.ymap.xml"
  <Item type="CEntityDef">
   <archetypeName>prop_bench_01a</archetypeName>
   <flags value="1572896" />
   <guid value="0" />
   <position x="-1386.72" y="-1004.23" z="3.86" />
   <rotation x="0" y="0" z="-0.8870108" w="0.4617486" />
   <scaleXY value="1" />
   <scaleZ value="1" />
   <parentIndex value="-1" />
   <lodDist value="100" />
   <childLodDist value="0" />
   <lodLevel>LODTYPES_DEPTH_ORPHANHD</lodLevel>
   <numChildren value="0" />
   <priorityLevel>PRI_REQUIRED</priorityLevel>
   <extensions />
   <ambientOcclusionMultiplier value="255" />
   <artificialAmbientOcclusion value="255" />
   <tintValue value="0" />
  </Item>
```

### Converting with CodeWalker

Browsers cannot write the binary ymap format, so CodeWalker does the last step:

1. Put `<name>.ymap.xml` in your resource's `stream` folder. Keep the double extension, CodeWalker uses it to know the file type.
2. Open CodeWalker's **RPF Explorer**, then **File, Open Folder** and pick that stream folder.
3. Turn on **Edit mode**, then **Edit, Import XML** (or drag the file into the window) and choose the XML.
4. CodeWalker writes `<name>.ymap` next to it. Delete the `.xml` from stream.
5. `ensure` the resource and reconnect.

To check it first, open CodeWalker's world view, use the Project window, **File, Open Files** to load the ymap and fly to it.

### The resource

```text
my_props/
├── fxmanifest.lua
└── stream/
    └── my_props.ymap        <- binary, converted with CodeWalker
```

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

name 'my_props'
description 'Props streamed with my_props.ymap'

-- A .ymap inside stream/ is picked up on its own, nothing else is required.
-- this_is_a_map 'yes' reloads the map store when the resource starts. Only add it
-- if you replace vanilla map files or ship map data files.
-- this_is_a_map 'yes'
```

```cfg title="server.cfg"
ensure my_props
```

With **Scripted** on, the manifest adds `client_script 'client.lua'` and the tool gives you:

```lua title="client.lua"
-- The ymap has the "scripted" flag, so the game only loads it on request.
CreateThread(function()
    RequestIpl('my_props')
end)

-- Later, to remove the props again:
-- RemoveIpl('my_props')
```

## Grabbing positions in game

The **Grab positions in game** panel gives you `ymap_helper.lua`, a client script for your dev server:

| Command | Output |
| --- | --- |
| `/ymappos` | Your position snapped to the ground (`GetGroundZFor_3dCoord`) plus heading, as `vector4(...)`. |
| `/ymapprop` | Model hash, position and rotation (`GetEntityRotation(ent, 2)`) of the object in front of the camera, found with a shape test ray of 30 m. |
| `/ymapdump` | Prints every collected line so you can paste them all at once. |
| `/ymapclear` | Forgets the collected lines. |

Each line is printed to the F8 console and chat. Tick **Copy to clipboard (ox_lib)** to also copy it with `lib.setClipboard` (needs ox_lib). Every line it prints is a format the importer reads. Remove the helper before going live.

> [!NOTE]
> `/ymapprop` only finds props the game spawned as objects. Static map geometry is not an object and will not be hit by the ray.

## Rotation

Enter rotations the way you read them in game: heading from `GetEntityHeading`, or pitch, roll and yaw from `GetEntityRotation(entity, 2)`. Heading 0 faces north and 90 faces west. The tool writes the quaternion a ymap expects, so you never type one yourself. The expanded row shows the value that will be written, if you want to compare it with another file.

When you open the result in CodeWalker, its entity panel shows the stored rotation as is, so its Euler Z reads minus your in-game heading. That is normal, the prop still faces the heading you entered.

## Common mistakes

- **Props float 1 m in the air.** `GetEntityCoords(PlayerPedId())` is at the pelvis. Use `/ymappos` (ground snapped) or set **Z offset** to -1 when importing.
- **Props face the wrong way.** Someone wrote the heading straight into the quaternion without inverting it. Import the XML here and headings are read correctly.
- **Props vanish when you walk away.** lodDist too low, or the streaming extents were not recalculated after moving things. The builder recalculates them on every change.
- **Nothing shows up.** The file in `stream/` is still the `.xml`, the name clashes with another ymap, or **Scripted** is on and nothing calls `RequestIpl`.
- **Custom props are invisible.** The ymap only places them. Their `.ydr`, `.ytd` and `.ytyp` must be streamed too.
- **One huge ymap.** The whole file streams in as soon as you enter its extents. Keep one ymap per area.
- **Changes do not show.** Reconnect. Map files load when you join, a resource restart is not always enough.

> [!TIP]
> You do not need `this_is_a_map 'yes'` to add props. It only matters when you replace vanilla map files.

## Limitations

- Output is CodeWalker XML. You still need CodeWalker to make the binary `.ymap`.
- The tool does not know model sizes, so extents use the **Assumed entity radius**. Raise it for big props.
- No LOD chain authoring (parents, LOD models), occluders, car generators or MLO interiors. Those sections are only passed through from an imported XML.
- The 3D world needs a desktop browser with WebGL 2, and it does not include Cayo Perico or North Yankton.
- Everything runs in your browser and is saved locally. Nothing is uploaded.

## Related tools

- [Objects / Props List](/docs/tools/objects-list): find model names, sizes and 3D previews.
- [3D world](/docs/tools/world-3d): camera modes, keys and performance tips for the 3D view.
- [Interactive Map](/docs/tools/interactive-map): grab coordinates without starting the game.
- [YTYP Creator](/docs/tools/ytyp-creator): archetypes for custom props you place with a ymap.
- [fxmanifest Generator](/docs/tools/fxmanifest-generator)

_Last updated: 2026-09-23_

---

## Minimap Editor

URL: https://fivemad.com/docs/tools/minimap-editor

Shape, place and style the FiveM minimap in the browser, see it over the real Los Santos map, and download a ready resource with the mask textures and Lua.

The Minimap Editor builds a complete minimap resource for your server. You pick the shape, place it on a real screen, style the border and the rings, and download a folder you can drop straight into `resources`. The preview draws over our own render of the Los Santos map, so what you judge is what players get.

## Quick start

1. Pick one of the presets at the top: **Classic round**, **Square modern**, **Minimal**, **Big square for RP** or **Hex tactical**.
2. Open the **Shape** tab and choose a silhouette, or upload your own mask image.
3. Open **Layout** and drag the minimap in the preview until the spacing looks right.
4. Switch the screen size above the preview between 1080p, 1440p and 21:9 to check all three.
5. Style the border and the rings, then press **Download resource**.
6. Unzip, put the folder in `resources`, add `ensure <your resource>` to your `server.cfg` and restart.

## The tabs

### Shape

Thirteen shapes, all drawn by the tool: circle, square, rounded square, squircle, octagon, two hexagons, diamond, pill, notched, blade, shield, and your own image.

- **Corner radius**, **Squareness** and **Cut size** appear only for the shapes that use them.
- **Edge softness** feathers the edge of the mask, so the map fades out instead of stopping on a hard line. A value of 0 gives a razor edge, 8 to 15 gives a soft one.
- **Mask texture size** is how sharp the exported mask is. 512 is enough for almost everything, 1024 helps a very soft edge on a large map.
- **Your own image**: a PNG with alpha, or a black and white picture. Only the silhouette is used, the colours in it never show up in game. The file is read in your browser and is never uploaded.
- **Blip clipping** is a separate setting from the mask. The mask cuts the map, this cuts the blips. Pick the option closest to your shape or blips will hang over the edge.

### Layout

- **Anchor** picks the screen corner or edge to measure from. Bottom left is where the game puts it.
- **Offset X, Offset Y, Width, Height** are fractions of the screen, the same units the game uses. X is measured over a 16:9 width, Y over screen height, which is why an ultrawide monitor gets the same minimap further from the centre.
- **Mask inset** shrinks the visible map inside its frame, useful when you want a thick border that eats into the edge.
- **Backing plate** is the dark panel behind the map. Size, spread and softness are separate so you can go from a tight drop shadow to a wide fade.
- **Expanded map** sets the size of the bigger map players toggle with the map key.
- **Raw component rows** shows the six rectangles the resource writes. Turn the link off and type exact numbers if you are matching an existing design.

Dragging inside the preview moves the minimap. It only works while the link is on.

### Style

- **Border** and **inner line**. The inner line is a darker stroke just inside the border, it stops the map bleeding into the border colour. Thickness is in pixels at 1080p and scales up on bigger screens.
- **Glow** puts a soft colour halo behind the border. Keep it under 15 px unless you want it obvious.
- **Plate colour** and opacity control the panel behind the map.
- **Map tint** lays a colour over the map. It also tints the blips, so keep the strength low. The blend modes behave the way they do in an image editor: multiply darkens, screen lifts, colour recolours while keeping the brightness.
- **Night colours** is a second full set of colours. Set the hours and the resource switches over by the game clock.

### Rings

First decide what happens to the game's own health and armour arcs:

| Setting | What happens |
| --- | --- |
| Keep | The arcs stay exactly as the game draws them |
| Recolour | The arcs stay, with the colours you set on the Game tab |
| Hide | The arcs are hidden, your own rings replace them |

Then add up to six rings. Each one has:

- **Value key**: `health`, `armour`, `stamina` and `oxygen` fill themselves. Any other key is filled by your own script.
- **Style**: *Follow shape* runs along the outline of your mask, *Arc* runs along a circle whatever the shape is, *Bar* sits under the map as a straight line.
- **Colour**, **track colour** and track opacity.
- **Thickness** and **gap from the border**, both in pixels at 1080p.
- **Start** and **Length**, measured as a percent of the outline starting at the top, plus the direction. Two rings at 50 percent and 0 percent going opposite ways give you the classic left and right arcs.
- **Rounded ends** and **glow**.
- **Preview value** is only for the preview.

To drive a ring of your own from Lua:

```lua title="somewhere in your script"
exports['fivemad_minimap']:SetMinimapRing('hunger', 0.62)
```

### Game

- **When the radar shows**: always, only in a vehicle, or off so your own script decides.
- **Zoom** is `SetRadarZoom`. 0 keeps the game default, higher values show less ground. The **Range** slider above the preview is separate and only changes how much map the preview draws.
- **Lock north up** stops the map turning with the player.
- **Reveal the whole map** clears the fog of war on join.
- **HUD colours**: tick an entry to override it. These are `hudcolor.dat` entries set by index, and the resource puts the originals back when it stops.
- **Hide HUD elements**: the cash, stars, street names and the rest. The preview shows a struck out box for each one you hide.

## What is in the zip

```
fivemad_minimap/
  fxmanifest.lua
  config.lua               every value, with a comment on each one
  client.lua               applies the config in game
  README.md
  textures/
    radarmasksm.png        mask for the small map
    radarmasklg.png        mask for the expanded map
  ui/
    index.html             the overlay page
    style.css
    app.js                 draws the border and the rings
    shape.json             the outline of your shape
    mask.png
    border.png             your border art
  minimap-project.json     open this back in the editor later
```

The mask is not streamed as a `.ytd`. The client builds a runtime texture from the PNG and swaps it in over the game's own mask, so nothing in the game is replaced and the originals come back when the resource stops. If you would rather have a real `.ytd`, take the PNG into the [Texture Editor](/docs/tools/texture-editor).

The border, the glow and the rings are drawn by the small overlay page in `ui/`. The game has no native for any of them. The page never asks for NUI focus, so it cannot eat a click.

## Saving and sharing

- Your work autosaves in this browser as you edit.
- **Save** writes a `.minimap.json` project file, **Open** loads one back.
- **Share** copies a link with the whole setup in it. Send it to someone and they open your exact minimap.
- The project JSON is also inside the zip, so you can always get back to the editor from the resource folder.

## Limits worth knowing

- **Land and sea colour** come from the game's own map textures, not from a HUD colour. The tint layer is an approximation over the top, a real recolour means replacing those textures.
- **The health and armour arcs cannot be restyled**, only hidden or recoloured. They live inside `minimap.gfx`, and rebuilding that movie breaks with every game update. Hide them and use your own rings instead.
- **Only one resource can own the minimap.** If another HUD resource also calls `SetMinimapComponentPosition`, load this one after it, or call `exports['fivemad_minimap']:ApplyMinimap()` once the other one is done.
- **The preview is a layout preview**, not a screenshot. The map inside the minimap is real, the space around it is deliberately empty.
- Cayo Perico and North Yankton are not in the preview map.

## Related

- [Texture Editor](/docs/tools/texture-editor) to put the mask into a `.ytd`
- [Blip, Marker and Checkpoint Browser](/docs/tools/blip-marker-browser) for the blips that sit on the map
- [Scaleform Functions](/docs/tools/scaleform-reference) for the other `minimap` movie calls

_Last updated: 2026-09-23_

---

## Zone Creator

URL: https://fivemad.com/docs/tools/zone-creator

Draw a zone on the real GTA V map in 2D or 3D and copy ready code for ox_lib zones, PolyZone, ox_target and qb-target, or the points as Lua or JSON.

The Zone Creator draws a zone on the actual Los Santos map, in 2D or in the 3D world, and hands you the code for whichever zone library your server uses. Nothing is uploaded and nothing needs a game client: you click where the zone belongs, set the two heights against the real ground, and copy the block.

## Quick start

1. Pick a shape: **Polygon**, **Box**, **Circle** or **Sphere**.
2. Click the map to drop corners (polygon) or to place the centre (the other three).
3. Switch to **Edit** and drag things into place. Set **minZ** and **maxZ** on the right, or press **Sit on the ground here** to put the band on the floor under the zone.
4. Open the output for your library at the bottom and copy it.

Switch to **3D world** on a desktop to see the zone as the solid it really is and check it clears the counter or the fence.

## Drawing and editing

| Action | How |
| --- | --- |
| Add a corner | **Add points** mode, click the map or the ground in 3D |
| Move a corner | **Edit** mode, drag it |
| Add a corner on an edge | **Edit** mode, drag the edge where you want the new corner |
| Delete a corner | Right click it, or use the bin in the Points list |
| Move the whole zone | **Edit** mode, drag from inside the shape |
| Set the heights in 3D | Drag the two flat discs in the middle of the zone |
| Undo / redo | <kbd>Ctrl</kbd> + <kbd>Z</kbd> and <kbd>Ctrl</kbd> + <kbd>Y</kbd> |

Changing shape keeps the zone where it is, so a polygon you drew turns into a box on the same spot.

## Heights

`minZ` and `maxZ` are world z, the same numbers `GetEntityCoords` returns. The panel shows the ground height under the zone, read from the same height data the map uses, so the numbers mean something instead of being a guess.

> [!TIP]
> A band from about a metre below the floor to two metres above it covers a player standing there. Go wider if people arrive by car, or if the floor slopes.

A **sphere** has no band. It is a ball around its centre, so it uses the centre z and the radius, and the two height fields are hidden.

## The outputs

Every tab says which library and version it was written against, and the comments at the top of each snippet list the `fxmanifest.lua` lines that library needs.

### ox_lib

`lib.zones.poly`, `lib.zones.box` and `lib.zones.sphere`, with `onEnter`, `onExit` and `inside` stubbed out.

Two things about ox_lib worth knowing, because the tool handles them for you:

- A poly zone is **flat**. Every point is put on one z and the height comes from `thickness`, which is the **total** height centred on that plane. So a band from 28 to 34 becomes points at z 31 with `thickness = 6.0`.
- `size` on a box is the **full** size, and `rotation` is the heading in degrees.

```lua title="client.lua"
local my_zone = lib.zones.box({
    name = 'my_zone',
    coords = vec3(213.94, -935.61, 31.0),
    size = vec3(10.0, 14.0, 6.0),
    rotation = 340.0,
    debug = true,
    onEnter = function(self)
        print('entered ' .. self.name)
    end,
    onExit = function(self)
        print('left ' .. self.name)
    end,
    inside = function(self)
        -- runs every frame while the player is inside
    end,
})
```

### PolyZone

`PolyZone:Create`, `BoxZone:Create` or `CircleZone:Create`, with an `onPlayerInOut` handler. `BoxZone` takes `(center, length, width, options)`: **length runs along the heading, width across it**, which the tool works out from the box you drew.

```lua title="client.lua"
local my_zone = PolyZone:Create({
    vector2(207.74, -943.21),
    vector2(230.1, -943.21),
    vector2(230.1, -925.4),
}, {
    name = 'my_zone',
    minZ = 28.0,
    maxZ = 34.0,
    debugPoly = true,
})

my_zone:onPlayerInOut(function(isPointInside, point)
    if isPointInside then
        print('entered my_zone')
    end
end, 500)
```

### ox_target and qb-target

The same zone as an interaction, with one option ready to edit: a label, a Font Awesome icon, a distance and a client event. Set those four in the tool and they land in the snippet.

ox_target uses ox_lib underneath, so its zone keys are ox_lib's. qb-target uses PolyZone, so its zone options are PolyZone's, and the interaction lives in a separate `targetoptions` table.

### Lua table and JSON

Just the numbers, for your own inside test or a library that is not listed here.

## Shapes a library does not have

- **ox_lib has no cylinder.** A circle is written as a sixteen sided polygon with a thickness, which is a real bounded cylinder.
- **PolyZone's `CircleZone` takes no `minZ` or `maxZ`.** With `useZ = false` it only tests x and y, so it has no top and no bottom; with `useZ = true` it is a ball. If the height matters, use a polygon there.

## Point order

Neither library needs a particular winding. ox_lib reverses a clockwise ring itself before it splits the polygon into triangles, and PolyZone's inside test does not care either way. The panel shows which way round your points run and there is a **Reverse order** button, which is useful when you are matching a list you already have.

What does matter is that the ring is **simple**: no edge may cross another. The tool flags a crossing and tells you which two edges do it.

## Bringing a zone back in

Paste any of these into the box at the bottom and press **Load it onto the map**:

- An ox_lib, ox_target, PolyZone or qb-target snippet
- The JSON this tool produces
- A plain list of `vector2` or `vector3` lines, or rows of `x, y` numbers

Only the shape and the heights are read back. Callbacks, target options and job checks are not.

## Share links

**Share link** puts the whole zone in the URL, so you can send it to whoever is writing the script and they open it exactly as you drew it. The link only carries what differs from the defaults, so it stays short.

## Limits

- One zone at a time. Putting several into a `ComboZone` is something you do in your own code.
- A self intersecting polygon is drawn and flagged, but no library can test it correctly. Fix the crossing first.
- Over roughly 400 metres across, or past about 40 points, the per frame inside test starts to cost real time. Split the area into a few zones, or use a box.
- The 3D view needs a desktop browser with WebGL 2. The 2D map works everywhere.

_Last updated: 2026-09-23_

---

## Server Status Checker

URL: https://fivemad.com/docs/tools/server-status-checker

Check whether a FiveM server is online by IP:port or cfx.re join code, and read its players, game build, OneSync, resources and server variables.

The Server Status Checker looks up any FiveM server by IP:port, host name or cfx.re join code and tells you whether it is online, who is playing, which game build and OneSync mode it runs, its resource list and its public server variables. Server owners use it to check their own server from outside; players and devs use it to peek at any public server.

## What it is for

- Checking from the outside that your server is reachable after a restart, a host move or a firewall change.
- Finding the game build, OneSync setting or resource list of a server you want to compare against.
- Getting the join code and F8 `connect` line of a server to share.
- Checking a player count before you hop on.

## Quick start

1. Type an address or join code in the **Server** box.
2. Press **Check status** (or <kbd>Enter</kbd>).
3. Read the summary card, then use the tabs below it for players, resources, variables or the raw data.

## What you can enter

| Input | Example |
| --- | --- |
| IP and port | `51.75.12.34:30120` |
| IP only (uses port 30120) | `51.75.12.34` |
| Host name and port | `play.myserver.com:30120` |
| Join link | `https://cfx.re/join/abc123` or `cfx.re/join/abc123` |
| Bare join code | `abc123` |

An IP or host name is asked directly. A join code goes through the Cfx.re server list, which also works for servers behind a proxy or a firewall that blocks direct HTTP. The summary shows which one was used: **via direct** or **via cfx.re list**.

Every lookup gets its own link with `?q=`, for example `/tools/server-status-checker?q=cfx.re/join/abc123`, so you can share a link that opens straight on the result. **Copy share link** copies it for you.

## The summary card

When the server is online you get:

- **Online** plus how it was reached, the response time in ms and how long ago it was fetched (with **(cached)** when the result came from the short cache).
- The hostname with its FiveM colour codes rendered, the project description, the server icon and the `banner_detail` image if the server sets one.
- **Players**: current and max slots with a fill bar (amber at 95 % and up).
- A row with **Game** (GTA V, RedM (RDR2) or LibertyM (GTA IV)), **Game build** (`default` when none is enforced), **OneSync** (On or Off), **Gametype**, **Map** and **Locale**.
- **Server** (the FXServer version string), **Endpoint** and **F8 connect**, all click to copy.

Buttons under it:

| Button | What it does |
| --- | --- |
| Connect | Opens `fivem://connect/...` so the FiveM client joins the server |
| Server list | Opens the server's page on servers.fivem.net (only with a join code) |
| Refresh | Checks again |
| Copy share link | Copies the `?q=` link |
| Make a badge | Opens the [Server Status Badge](/docs/tools/server-uptime-badge) tool with this server filled in |

**Auto-refresh every 30 seconds** keeps the result updated while the tab is open.

## Tabs

| Tab | What it shows |
| --- | --- |
| Players | ID, name (colour codes rendered) and ping, coloured green under 80 ms, amber under 150 ms, red above. Search by name or exact ID. |
| Resources | Every started resource the server publishes, sorted A-Z, click to copy, with search. |
| Variables | The `banner_detail` and `banner_connecting` images, the server tags, and every public `sets` variable with search. |
| Raw JSON | The whole result as JSON (the icon is shortened) for copying. |

Many servers hide player names and pings. In that case the tab says **Players (hidden)** and the tool shows only the count. Player identifiers (license, steam, discord, ip) and `sv_licenseKeyToken` are always removed from results.

## When it says offline

The result card tells you what went wrong: **Offline**, **Timed out**, **Not listed**, **Invalid input**, **Not allowed** or **Slow down**, with a **Retry** button.

- **Wrong port.** The game port is usually `30120`. `40120` is txAdmin, not the game.
- **Firewall.** FiveM needs both TCP and UDP open on the game port.- **Proxy.** Servers using `sv_forceIndirectListing`, a reverse proxy or a DDoS shield often do not answer plain HTTP. Check the join code instead.
- **Not listed.** A join code only resolves while the server is online and listed. A private server (`sv_master1 ""`) can only be checked by IP.
- **Not allowed.** Private and local addresses (`192.168.x.x`, `10.x.x.x`, `127.0.0.1` and so on) cannot be checked from the internet.

```cfg title="server.cfg"
endpoint_add_tcp "0.0.0.0:30120"
endpoint_add_udp "0.0.0.0:30120"
```

These are the usual endpoint lines. Make sure both are in your config and that your host's firewall allows TCP and UDP on that port.

## Limitations

- Results are cached for about 30 seconds, so a fresh restart can take a moment to show.
- Each visitor gets 30 lookups per minute. Auto-refresh keeps the last result on screen if you hit the limit.
- The tool only sees what the server makes public. Hidden player lists stay hidden.

## Related tools

- [Server Status Badge](/docs/tools/server-uptime-badge) to show your live player count on a website or README.
- [Cfx Blacklist Checker](/docs/tools/cfx-blacklist-checker) when a server will not show up in the list at all.
- [FXServer artifacts](/docs/tools/artifacts) to see whether the server version in the summary is a recommended build.
- [server.cfg Generator](/docs/tools/server-cfg-generator) for endpoints, OneSync and game build settings.

_Last updated: 2026-09-22_

---

## Profiler Analyzer

URL: https://fivemad.com/docs/tools/profiler-analyzer

Record a FiveM profile with profiler record and saveJSON, then read time per resource, worst frames, hitches, a flame graph and findings with fixes.

The Profiler Analyzer reads the JSON file the built-in FiveM profiler saves and turns it into a report you can act on: which resources eat your frame or tick time, which frames were the worst and what ran in them, which events and threads are heavy, when hitches happened, and plain advice on what to fix. It works for both server and client recordings and runs entirely in your browser.

## What it is for

`resmon` tells you a resource averages 0.8 ms, but not why, not when, and not what it looked like in the frame where the game stuttered. The profiler records all of that, but its raw output is hard to read. Use this tool when:

- Players report lag or rubber banding and you need to know which resource is responsible.
- The server console prints hitch warnings and you want to know whether a script caused them.
- You changed a resource and want proof that it got faster (the Compare tab).
- You want to share a short, readable summary with a script's developer.

## How to record a profile

FiveM has a profiler built in on both sides. It records every resource tick and event handler with microsecond timing, including escrowed resources. The **How to record** card next to the drop zone has the same commands with copy buttons for **Server console** and **Client F8**.

### Server (txAdmin Live Console or the FXServer window)

```bash
profiler record 1200
profiler status
profiler saveJSON lag.json
```

1. `profiler record 1200` records 1200 ticks. The server runs 20 ticks per second, so that is one minute. Use `600` for a quick look.
2. `profiler status` shows whether it is still recording. It stops by itself.
3. `profiler saveJSON lag.json` writes the file next to your `server.cfg` with txAdmin, or wherever FXServer was started.

Record while the server is busy. Problems that only show with players online will not show on an empty server.

### Client (F8 console)

```bash
profiler record 1000
profiler status
profiler saveJSON lag.json
```

Stand where the game feels bad and do the laggy thing while it records. 1000 frames is 8-16 seconds depending on your FPS. The file ends up in `%localappdata%\FiveM\FiveM.app\citizen\lag.json`.

Client recordings store a small screenshot per frame, so they get big fast. Files of a few hundred MB are fine here.

### Other profiler commands

| Command | What it does |
| --- | --- |
| `profiler record start` / `profiler record stop` | Record until you stop it |
| `profiler resource myresource 300` | Records Lua function calls of one resource (`*` for all). Slower, but shows which function is heavy |
| `profiler view` | Opens the raw trace in Chrome DevTools for a manual look |
| `profiler save name` | Writes a binary file this tool cannot read. Use `saveJSON` |

## Quick start

1. Record a profile as above.
2. Drop the `.json` on the page, or press **Choose a file**. A gzipped `.json.gz` works too.
3. Read the verdict at the top, then the **Findings** tab.
4. Click the worst bars on the timeline to see exactly what ran in those frames.

No file handy? **Try a sample** loads a made-up server recording so you can look around. Its resource names are invented.

## The report

### File bar

Shows the file name, size, number of events and how long it took to read. Buttons:

| Button | What you get |
| --- | --- |
| Copy for Discord | A short summary that fits in one Discord message (2000 characters) |
| Report .md | `<file>-report.md`, the full report as Markdown |
| Timeline .png | `<file>-timeline.png`, a picture of the current timeline |
| Open another | Load a different file. You can also drop a new file anywhere on the page |

### Verdict

A one-line status (**Healthy**, **Some pressure**, **Struggling** or **Overloaded**), a title and a sentence explaining it. **Read as** shows whether the file was detected as a **Server** or **Client** recording and why; switch it if the guess is wrong.

The card on the right shows:

- **Scripts per tick (or frame), average**: the big number.
- **p95 / p99**: how bad the slow ticks or frames get.
- **Worst tick / frame**: click it to open that frame.
- **FPS, avg / 1% low** on the client, or **Tick interval, p99** on the server.
- **Hitches**, and how many of them came from scripts.
- **Recorded** (ticks or frames) and **Length**.

### Timeline

One bar per tick or frame. Two views:

- **Script time**: what resources spent in each frame or tick.
- **Tick interval** (server) or **Frame time** (client): the time between two ticks or frames for the whole server or game.

Amber and red mark the budgets below, and guide lines show 50 ms (a whole tick) or 60 and 30 FPS. Hover a bar for the numbers and the top three resources in it. Click a bar to open that frame. Drag to zoom, <kbd>Ctrl</kbd> + scroll to zoom, <kbd>Shift</kbd> + scroll to pan. Under the chart, **Worst ticks / frames** lists the eight worst with their time in the recording.

When you select a resource in the Resources tab, its own time is drawn in white on top of the timeline.

### Frame detail

Opens under the timeline when you click a bar or a worst-frame button. It shows:

- **Scripts**, **Resource Manager Tick**, and **Until next tick** (server) or **Frame time** with the FPS pace (client), marked heavy, over budget or hitch when they are.
- A flame chart of exactly what ran in that frame, in order, left to right. Colours mark the type: frame, resource tick, event handler, thread or function. Hover a block for its duration, start and file lines. Click a block to zoom in, **Whole tick / frame** to zoom out.
- On client recordings, the screenshot the game took at the end of that frame.
- **Heaviest resources in this frame**: click one to open it in Resources.

Use the arrows to step to the previous or next frame.

## Tabs

### Findings

Rules that read the numbers and point at problems, grouped as **Fix first**, **Worth fixing** and **Good to know** (filter with the buttons at the top). Each finding lists the evidence and a concrete fix, with **Open resource** and buttons that jump to the frames involved. They cover:

- Scripts taking a big part of every tick or frame.
- A resource running code every frame (the `Wait(0)` loop pattern).
- Heavy event handlers and heavy NUI callbacks.
- Events that fire constantly or very often.
- Spikes that repeat on a timer, and one-off big spikes.
- Resources that run many small threads.
- Hitches caused by scripts, and hitches not caused by scripts (streaming, the host, garbage collection).
- Resources with no detail (JS and C#), Lua memory that keeps growing, short recordings and unclosed scopes.

If nothing stands out you get **Nothing stands out**, with the tip to record during the laggy moment or on the other side (client vs server).

### Resources

A sortable table of every resource:

| Column | Meaning |
| --- | --- |
| Share | Share of all script time in the recording |
| Avg | Average ms per frame or tick over the whole recording, the same thing `resmon` shows |
| Worst | Most time spent in a single frame or tick |
| Events | Time spent in event handlers |
| Calls | Number of calls |
| Active | Share of frames or ticks where it ran |

Times are exclusive: when resource A triggers an event in resource B, B's handler counts for B, not twice. Filter by name; the table shows 60 rows until you press **Show all**.

Click a resource to open its detail: average, p95, worst and total time, **Its worst ticks / frames**, **What triggered it** (every tick, or which events, with calls, average, worst and total), **Threads, handlers and functions** with file and line numbers, and the Lua heap at the start and end when the file has it.

### Flame graph

The whole recording merged by call path. The wider a block, the more total time it took. Hover for total, per tick or frame, share of all, self time and calls. Click a block to zoom in and use the path at the top to go back. **Highlight a name** marks every block that matches a resource or file and shows how much time the matches take in total.

### Compare

Did your fix work? The loaded file is **before**. Drop a second recording taken after your change, ideally the same length and in the same spot, on **Drop the "after" profile**. You get:

- A summary: scripts per tick or frame (average and 99th percentile), worst tick or frame, average FPS on the client and hitches per minute, each marked better, worse or about the same.
- **Per resource, average ms per tick / frame** with before, after and the change. Green means less time after the change.

Numbers are per tick or frame, so two recordings of different length still line up. A warning shows if you compare a client recording with a server one. **Remove after** clears the second file.

## Budgets

| | Client | Server |
| --- | --- | --- |
| Frame or tick | 16.7 ms at 60 FPS | 50 ms (20 ticks per second) |
| Scripts get heavy at | 4 ms per frame | 25 ms per tick |
| Hitch | a frame over 50 ms | ticks over 150 ms apart (the console's hitch warning) |
| One resource worth a look | 0.1 ms per frame, heavy from 0.5 ms | 0.5 ms per tick, heavy from 2 ms |

**Script time** is what resources spent in a frame or tick. **Frame time** and **tick interval** cover everything. When the gap is big but script time is small, the stall came from somewhere else, and the findings say so instead of blaming a script.

## Examples

The most common finding is a loop that runs every frame even when it has nothing to do:

```lua title="client.lua"
-- runs every frame, all the time
CreateThread(function()
    while true do
        Wait(0)
        local coords = GetEntityCoords(PlayerPedId())
        if #(coords - shopCoords) < 2.0 then
            DrawMarker(2, shopCoords.x, shopCoords.y, shopCoords.z, 0, 0, 0, 0, 0, 0, 0.3, 0.3, 0.3, 255, 255, 255, 150, false, true, 2, false, nil, nil, false)
        end
    end
end)
```

```lua title="client.lua"
-- only runs every frame while the player is close
CreateThread(function()
    while true do
        local sleep = 1000
        local coords = GetEntityCoords(PlayerPedId())
        if #(coords - shopCoords) < 10.0 then
            sleep = 0
            DrawMarker(2, shopCoords.x, shopCoords.y, shopCoords.z, 0, 0, 0, 0, 0, 0, 0.3, 0.3, 0.3, 255, 255, 255, 150, false, true, 2, false, nil, nil, false)
        end
        Wait(sleep)
    end
end)
```

Record again after a change like this and drop both files into **Compare**.

## Tips

- Record on the side where the problem is. Client FPS drops need a client recording; server hitch warnings need a server one.
- Record for long enough to catch the problem. A short recording gets a **Short recording** note.
- For a resource that shows as heavy but has no named threads, run `profiler resource <name> 300` for function-level detail.
- The profiler adds a little overhead itself, so absolute numbers run slightly high. Compare recordings made the same way.

## Limitations

- The file never leaves your browser. There is no upload and no shared leaderboard.
- Only Lua threads and handlers get names. JS and C# resources show up as a total per resource.
- Files from `profiler save` (binary) cannot be read; use `profiler saveJSON`.
- The sample file is synthetic, not a real server.

## Related tools

- [Server Status Checker](/docs/tools/server-status-checker) to check the server from outside while you debug.
- [FXServer artifacts](/docs/tools/artifacts) in case the hitches come from a known broken server build.
- [fxmanifest Generator](/docs/tools/fxmanifest-generator) when a finding points at how a resource is set up.

_Last updated: 2026-09-22_

---

## Cfx Blacklist Checker

URL: https://fivemad.com/docs/tools/cfx-blacklist-checker

Check whether an IP, host name or cfx.re join code is on the Cfx.re platform blacklist, up to 20 at once, before you rent a VPS or when a server vanishes.

The Cfx Blacklist Checker tells you whether an IP address is on the Cfx.re platform blacklist. Paste IPs, host names or cfx.re join codes, up to 20 at once, and each address comes back as blacklisted or not. It is for server owners picking a host, moving to a new IP, or wondering why their server is missing from the list.

## What the Cfx.re blacklist is

Cfx.re keeps a list of IP addresses that may not run public FiveM or RedM servers, usually addresses tied to abuse, ban evasion or hosting ranges that were used for it. A server on a blacklisted IP does not show up in the server list, and players get an error when joining. The blacklist is about the machine the server runs on, not about the players on it.

## When to check

- **Before renting a VPS or dedicated server.** Ask the host for the IP first and check it here. Cheap reseller plans and recycled IPs are the usual suspects.
- **When your server vanishes from the list** after moving hosts or getting a new IP.
- **Before buying a used IP block.**

## Quick start

1. Paste one or more addresses in **IPs, host names or join codes**, one per line (spaces and commas work too).
2. Press **Check**, or <kbd>Ctrl</kbd> + <kbd>Enter</kbd>.
3. Read the result list: every address gets **Blacklisted**, **Not blacklisted** or **Could not check**.

## What you can paste

| Input | What happens |
| --- | --- |
| `51.75.12.34` | Checked directly. IPv4 and IPv6 both work. |
| `play.myserver.com` | Every public A and AAAA record of the host is checked, so one host can give several rows. |
| `cfx.re/join/abc123` or `abc123` | Looked up to the server's address, then checked. |

Up to 20 inputs per check.

## Reading the results

The header says how many addresses were checked and how many are blacklisted or could not be checked. Each row shows:

- The IP (click to copy).
- Under it: the host name it came from, the reverse DNS name when there is one, and a note when something went wrong: a private or reserved address, a host name that did not resolve or has no public IP, a join code that was not found, or a server that hides its address behind a proxy.
- The state on the right.

| State | Meaning |
| --- | --- |
| Blacklisted | This IP may not host a public server. |
| Not blacklisted | The IP is not on the list right now. |
| Could not check | The input could not be turned into a public IP, or the check failed. See the note. |

The footer shows when the check ran. Every check gets its own link with `?q=`, so you can send the result to your host's support: `/tools/cfx-blacklist-checker?q=51.75.12.34`.

> [!TIP]
> The reverse DNS name often tells you which hosting company owns an IP. Handy when a join code resolves to an address you do not recognise.

## If your IP is blacklisted

- Ask your host for a different IP. Most hosts can swap it, and it is their range that is flagged.
- If you think the listing is a mistake, contact Cfx.re support through the forum with your server details.
- Changing ports does not help: the check is by IP.

## Limitations

- Servers behind a proxy hide their address, so a join code check for them comes back as **Could not check** with a note saying so. Check the real IP directly if you know it.
- Private and reserved addresses (LAN, `127.0.0.1`, `192.168.x.x` and so on) are not checked.
- Results are cached for 10 minutes, so a fresh change on Cfx.re's side can take a moment to show.
- A clean result only means the IP is not blacklisted now. It says nothing about the host's network quality.

## Related tools

- [Server Status Checker](/docs/tools/server-status-checker) to see whether a server answers at all.
- [FXServer artifacts](/docs/tools/artifacts) to pick a good server build for the new machine.
- [server.cfg Generator](/docs/tools/server-cfg-generator) to set up the config on a fresh host.

_Last updated: 2026-09-22_

---

## Server Status Badge

URL: https://fivemad.com/docs/tools/server-uptime-badge

Build a live SVG badge, card or signature square with your FiveM server's logo, player count and a Join button, and embed it with Markdown, HTML or BBCode.

The Server Status Badge tool makes a live image of your FiveM server: `402/700 players` while it answers, `offline` when it does not. You pick the shape, the artwork and the colours, and copy a ready snippet for a GitHub README, a website or a forum thread.

## What it is for

- A status card with your logo and a Join button at the top of your server's website or Tebex store.
- A small badge in a GitHub README for a server or a public config repo.
- A compact square for a forum.cfx.re signature, with BBCode.

The badge is not a historical uptime percentage. It shows the state at the moment it was loaded, and it updates about once a minute wherever it is embedded.

## Quick start

1. Enter your server in **Address or join code**: `ip:port`, `host:port`, `cfx.re/join/abc123` or just the join code.
2. Pick a starting point under **Start from**. **Dark card** is the one most people want.
3. Adjust **Shape**, **What it shows**, **Artwork** and **Colours**.
4. Check the **Live preview**. It shows the real image on a dark and a white plate, with its true pixel size.
5. Copy one of the snippets under **Embed**.

If you came from the [Server Status Checker](/docs/tools/server-status-checker), **Make a badge** opens this tool with your server already filled in.

## The three shapes

| Shape | What it looks like | Good for |
| --- | --- | --- |
| **Badge** | The small shields style strip with the count on the right | A README line, next to build badges |
| **Card** | Logo, server name, player bar, Join button | A website header, a README title block |
| **Square** | A tile with a player ring and your logo | Forum signatures, a sidebar |

## Your server logo

With a **cfx.re join code**, the badge uses the icon your server already shows in the FiveM server list. Nothing to upload, nothing to configure. Animated icons are drawn as one still frame so the badge stays small.

If your server has no icon, or you are badging it by `ip:port`, pick **Own picture** under **Artwork**. Your file is shrunk in the browser and travels inside the badge link, so keep it simple: the tool tells you how long the link has become and warns you when it gets too long for some forums.

**Backdrop** puts artwork behind a card or a square:

- **Icon, faded** blows up the same logo. It costs nothing extra.
- **Server banner** uses the banner your server advertises in `banner_detail`. We fetch it and put it in the image. If it is missing, slow, not an image or bigger than 96 KB, the badge drops it and still looks right.

> [!TIP]
> A badge with a banner is a much heavier image than a plain one. On a page where the badge loads on every visit, the icon backdrop is the cheaper choice.

## Options

| Group | Option | What it does |
| --- | --- | --- |
| Shape | Shape | Badge, card or square |
| | Style | Badge only: Flat, Square, Big |
| | Theme | Card and square: Dark or Light |
| | Size | Renders the badge bigger or smaller, from 0.5x to 3x |
| | Corner radius | Rounds the corners, 0 for sharp |
| | Text size / Width | Text size on a badge, fixed width on a card or square |
| What it shows | Player count | `402/700`, a bar, a ring, a percentage, or hidden |
| | Use the server name | Your server name as the label or title, colour codes stripped |
| | Game type, Map name, Last updated | Extra lines on a card or square |
| | Join button | Card only, needs a join code |
| | Extra line | Your own text, for example your Discord invite |
| Artwork | Logo | Server icon, none, or your own picture |
| | Backdrop | None, the icon faded, or your server banner |
| Colours | Online, Offline, Join button, Background, Text, Border | Every part separately |

Offline keeps its own colour whatever you pick for online, so a server that is down never shows up green.

## Embed snippets

The **Embed** panel gives you four versions, each with a copy button. With a join code the link goes to `https://cfx.re/join/<code>` so a click opens FiveM. With an IP it links to the Server Status Checker page for your server.

### Markdown (GitHub README)

```markdown
[![FiveM server status](https://fivemad.com/api/badge/abc123.svg?shape=card)](https://cfx.re/join/abc123)
```

### HTML (website)

```html
<a href="https://cfx.re/join/abc123"><img src="https://fivemad.com/api/badge/abc123.svg?shape=card" alt="FiveM server status" /></a>
```

### BBCode (forums)

```text
[url=https://cfx.re/join/abc123][img]https://fivemad.com/api/badge/abc123.svg?shape=square[/img][/url]
```

### Image URL

Just the image link, for places that only take an image URL.

## Editing the link by hand

Everything you set ends up in the image link, so you can tweak an existing badge without coming back to the tool:

```text
https://fivemad.com/api/badge/<server>.svg?shape=card&players=bar&logo=server&art=banner
```

| Part | Values |
| --- | --- |
| `<server>` | Join code (`abc123`), `ip:port` or `host:port` |
| `shape` | `badge` (default), `card`, `square` |
| `style` | Badge only: `flat` (default), `flat-square`, `for-the-badge` |
| `theme` | Card and square: `dark` (default) or `light` |
| `players` | `count`, `bar`, `ring`, `percent`, `none` |
| `logo` | `server`, `none`, or a `data:image/...` picture |
| `art` | `none`, `icon`, `banner` |
| `label` | Left text or card title. `hostname=1` uses your server name. |
| `sub` | Your own extra line |
| `map`, `mode`, `updated`, `join`, `border` | `1` or `0` |
| `scale`, `radius`, `font`, `width` | Size, corner radius, text size, fixed width |
| `color`, `offline`, `bg`, `bg2`, `fg`, `muted`, `accent`, `bcolor`, `labelColor` | Hex without `#`, or a colour name like `blue` |

The tool page takes the same options, so `/tools/server-uptime-badge?q=abc123&shape=card&art=banner` opens the editor on that design. Old badge links keep working: `label`, `style`, `color`, `labelColor` and `hostname` still mean what they did.

For example, a big blue badge with your server name:

```text
https://fivemad.com/api/badge/abc123.svg?style=for-the-badge&color=blue&hostname=1
```

## Tips

- Check the preview on both plates. A card set to the light theme disappears on a white page unless you keep the border on.
- Shorter titles read better. On a badge, `status` or your server tag often looks cleaner than the full hostname.
- **Size** is the cheapest way to make a card look sharp on a high resolution screen: 2x renders the same design at twice the pixels.
- GitHub shows README images through its own image cache, so a badge there can lag a few minutes behind.

## Limitations

- **Discord does not show SVG images**, neither in chat previews nor in embeds, and there is no PNG version yet. For Discord, link your [Server Status Checker](/tools/server-status-checker) page or use a bot that posts the player count.
- The badge updates about once a minute, not in real time. There is a limit of 120 badge requests a minute per address.
- The logo, the banner and the Join button need a **join code**. An `ip:port` badge shows the player count and the name only.
- It only knows what your server makes public. If the server does not answer from outside, the badge shows offline even when players on your LAN can join.

## Related tools

- [Server Status Checker](/docs/tools/server-status-checker) for the full picture: players, resources, variables.
- [Cfx Blacklist Checker](/docs/tools/cfx-blacklist-checker) if your server is up but missing from the list.
- [Generators](/docs/tools/generators) for a server name and a coloured `sv_hostname`.

_Last updated: 2026-09-23_

---

## FXServer artifacts

URL: https://fivemad.com/docs/tools/artifacts

Find the recommended FXServer artifact, see which builds have known issues, download for Windows or Linux and update your server step by step.

The FXServer artifacts page answers one question every server owner asks: which server build should I run? It shows the recommended artifact with direct Windows and Linux downloads, lists every build with known issues, and lets you look up any artifact number to see whether it is safe.

## What it is for

FXServer (the FiveM and RedM server) ships as numbered builds called artifacts. New ones come out often, and now and then one has a bug: crashes, voice not working, clients failing to connect. Use this page:

- Before you update, to pick a build without reported issues.
- When your server started acting up right after an update, to see if your build is on the issues list.
- When a resource says it needs "artifact 12345 or newer", to find and download a matching build.

## Quick start

1. Open [/artifacts](/artifacts). The **Recommended artifact** card shows the build number.
2. Press **Windows** or **Linux** under **Download** to get that build.
3. Follow the update steps below for your OS.

## The recommended artifact

The big number is the build most server owners should run. A new artifact is not recommended straight away: it waits a short period so server owners have time to report problems, and the recommended one is the newest build that cleared that window with no reported issues. The question mark button next to the number explains the same thing.

When a newer build exists, the card also shows **latest build** with its number. Newer is not always better; the latest one may simply not have been tested long enough yet.

## The build table

Every build is listed newest first, 10 per page, with a tag:

| Tag | Meaning |
| --- | --- |
| RECOMMENDED | The recommended build (highlighted) |
| OK | No reported issues |
| ISSUE | A build or range of builds with a known problem; the description says what |
| BUILD | A build that failed to build upstream. Hidden unless **Failed builds** is on |
| N/A | Not a valid artifact number (search results only) |

Controls above the table:

- **All** shows every build. **Issues only** shows just the builds with known problems, with a count.
- **Failed builds** shows or hides builds that never finished building.
- **Artifact number** looks up one build. Type a number and you get its tag, the reason if it has an issue, and download links if it is fine.

Rows with no issues have Windows and Linux download buttons on the right, and the five newest also show their release date. Click a build number to copy it.

> [!NOTE]
> The build list is loaded from GitHub, which allows 60 requests an hour per visitor. If you page through a lot of builds you may see **GitHub rate limit reached** with a time to try again. The **Issues only** view keeps working in the meantime.

## How to update FXServer

The rule for both systems: replace the contents of your **artifacts folder** (the server binaries), never your **server-data** folder (resources, `server.cfg`, database). Keep a copy of the old artifacts folder until the new build has run for a while.

### Windows

1. Download **Windows** from the page. You get `server.zip`.
2. Stop the server (in txAdmin, stop it and close the FXServer window).
3. Rename your current artifacts folder as a backup, for example `server` to `server_old`.
4. Make a new empty folder with the old name and extract `server.zip` into it.
5. Start `FXServer.exe` again (or your usual start script / txAdmin shortcut).
6. Check the console for the new build number.

### Linux

1. Download **Linux** from the page. You get `fx.tar.xz`. On a server without a browser, right click the button to copy the link and fetch it with `wget`.
2. Stop the server.
3. Move the old artifacts folder aside and extract the new one in its place:

```bash
cd /home/fivem
mv server server_old
mkdir server && cd server
wget -O fx.tar.xz "<link copied from the Linux button>"
tar xf fx.tar.xz
rm fx.tar.xz
```

4. Start it again with `./run.sh` from the artifacts folder (or your txAdmin service).

The folder names are examples; use whatever your setup calls them. If the new build misbehaves, stop the server and swap the old folder back.

> [!TIP]
> Found a bad build? The page links a **Report an issue** form, and the **Update guide** button opens a longer walkthrough. Reports end up in the shared issues list, so every server owner gets warned.

## Let your server check itself

Further down the page there is a Lua snippet with a **Copy** button. Drop it into any server script. On start it reads the running build from the `version` convar, asks the public artifacts database about it and prints a warning in the server console if the build has known issues:

```lua title="server/artifact_check.lua"
CreateThread(function()
    local build = GetConvar('version', ''):match('v1%.0%.0%.(%d+)')
    if not build then return end

    PerformHttpRequest('https://artifacts.jgscripts.com/check?artifact=' .. build, function(code, body)
        if code ~= 200 or not body then return end
        local data = json.decode(body)
        if data and data.status == 'BROKEN' then
            print(('^1[artifacts] Build %s has known issues: %s^0'):format(build, data.reason or 'unknown'))
            print('^3[artifacts] Recommended build: https://fivemad.com/artifacts^0')
        else
            print(('^2[artifacts] Build %s has no reported issues.^0'):format(build))
        end
    end, 'GET')
end)
```

The same database has a free JSON API (no key, no signup), described on the page, if you want the recommended build or the broken list in your own tools.

## Limitations

- The issues list only knows what server owners reported. A build marked OK can still have a problem nobody has hit yet.
- If the artifacts database cannot be reached, the card says **Could not load** and the downloads stay disabled. Try again later.
- Download links point straight at the official Cfx.re artifact server; nothing is re-hosted.

Artifact data comes from the open source FiveM Artifacts DB by JG Scripts.

## Related tools

- [Server Status Checker](/docs/tools/server-status-checker) to see which server version a running server reports.
- [Profiler Analyzer](/docs/tools/profiler-analyzer) to find out whether lag after an update comes from scripts or not.
- [server.cfg Generator](/docs/tools/server-cfg-generator) for game build and OneSync settings that go with a new artifact.

_Last updated: 2026-09-22_

---

## joaat Hash Calculator

URL: https://fivemad.com/docs/tools/hash-calculator

Turn any model, weapon or asset name into its GTA V joaat hash in unsigned, signed and hex form, one at a time or as a bulk Lua table.

The joaat Hash Calculator turns any string into the 32-bit hash GTA V uses for it, the same value `GetHashKey`, `joaat` and the Lua backtick give you in game. It is for anyone who needs a hash outside the game: comparing a value from a log, filling a config, or building a lookup table for a script.

## What it is for

GTA V (and RDR2) identify models, weapons, animations, components and most other assets by a Jenkins one-at-a-time hash of their lower-cased name. You meet those numbers everywhere: `GetEntityModel` returns one, weapon events carry one, and dumps print them in different formats. When a script prints `-1216765807` and you want to know if that is `adder`, or when you need a hash table for a whitelist, this tool gives you the number without starting the game.

## Quick start

1. Open the tool. The **Single** tab is selected, with `adder` already typed in.
2. Type your string in the **String** field. The **Result** panel updates on every key press.
3. Click any value in the result to copy it.
4. For many names at once, switch to **Bulk**, paste one name per line, pick an **Export format** and copy the generated `hashes.lua`.

## Single mode

The **Result** panel shows four rows for the current string:

| Row | Example for `adder` | Notes |
| --- | --- | --- |
| **Unsigned** | `3078201489` | The raw 32-bit value, 0 to 4294967295. |
| **Signed (int32)** | `-1216765807` | Same bits read as a signed int32. What most natives return and many dumps print. |
| **Hex** | `0xB779A091` | Always `0x` plus 8 upper-case digits. |
| **Lua backtick** | `` `adder` `` | Your string lower-cased inside backticks, ready to paste into Lua. |

The input is lower-cased before hashing, exactly like the game does, so `ADDER`, `Adder` and `adder` all give the same result. `WEAPON_PISTOL` and `weapon_pistol` are the same hash too.

## Bulk mode

Paste one string per line in **One string per line**. Empty lines are skipped and spaces around each line are trimmed. The panel title shows how many hashes were computed, and the table lists each name with its **Signed** and **Hex** value (click to copy).

Below the table, **Export format** (**Hex**, **Signed** or **Unsigned**, default Hex) controls the value used in the generated `hashes.lua` block:

```lua title="hashes.lua"
local Hashes = {
    adder = 0xB779A091,
    zentorno = 0xAC5DF515,
    WEAPON_PISTOL = 0x1B06D571,
    mp_m_freemode_01 = 0x705E61F2,
    prop_bench_01a = 0x6BA514AC,
}
```

Names that are valid Lua identifiers become plain keys. Anything else (a name with a dash or starting with a digit) is written as `["name"]`, so the table always parses.

## Examples

Reverse lookup of a model you got from the game, using a table built in bulk mode:

```lua title="client.lua"
local Names = {
    [`adder`] = "adder",
    [`zentorno`] = "zentorno",
}

local veh = GetVehiclePedIsIn(PlayerPedId(), false)
local model = GetEntityModel(veh)
print(Names[model] or ("unknown model %d"):format(model))
```

The backtick is resolved when the script is compiled, so it costs nothing at runtime:

```lua
local model = `adder`
RequestModel(model)
while not HasModelLoaded(model) do Wait(0) end
local veh = CreateVehicle(model, coords.x, coords.y, coords.z, heading, true, false)
SetModelAsNoLongerNeeded(model)
```

## Signed vs unsigned

The hash itself is unsigned, but natives hand it to Lua as a signed int32, so `GetEntityModel` on an Adder returns `-1216765807`, not `3078201489`. Both are the same model. In Lua, compare against the backtick or `GetHashKey` result instead of a hard-coded unsigned number, and the sign never gets in the way. Hex literals like `0xB779A091` are positive in Lua 5.4, so a table keyed by hex will not match a signed value from a native. Pick **Signed** as the export format when you compare against values returned by natives.

> [!TIP]
> Use **Signed** when the table is compared with `GetEntityModel`, `GetSelectedPedWeapon` or event payloads. Use **Hex** when you want readable values in a config that is only passed back into natives.

## Common mistakes

- Hashing a display name. `Adder` is fine because case does not matter, but "Truffade Adder" is not the model name. Use the spawn name.
- Adding spaces or a file extension. `adder.yft` hashes to something else entirely.
- Comparing a signed value from a native with an unsigned or hex constant.

## Limitations

- The tool only hashes. It does not look a hash up to find the name. For vehicles, peds and weapons, the [Model & Hash Browser](/tools/model-hash-browser) lists spawn names next to their signed, unsigned and hex hashes.
- Everything runs in your browser. Nothing you type is sent anywhere.

## Related tools

- [Model & Hash Browser](/docs/tools/model-hash-browser)
- [Weapon Stats & Components](/docs/tools/weapon-stats)
- [Objects / Props List](/docs/tools/objects-list)
- [Player Stats List](/docs/tools/player-stats)

_Last updated: 2026-09-22_

---

## Driving Style Calculator

URL: https://fivemad.com/docs/tools/driving-style-calculator

Build and decode the driving style integer for TaskVehicleDriveToCoord, TaskVehicleDriveWander and SetDriveTaskDrivingStyle, with every flag bit listed.

The Driving Style Calculator combines vehicle AI flags into the single integer the driving tasks expect, and decodes any value you find in someone else's script. It also writes a ready Lua snippet for the task you pick, for the player's own car or an NPC driver.

## What it is for

A driving style is a 32-bit number where each bit switches one AI behaviour: stop for cars, obey lights, use shortcuts, drive in reverse. You pass it to `TaskVehicleDriveToCoord`, `TaskVehicleDriveToCoordLongrange`, `TaskVehicleDriveWander`, or change a running task with `SetDriveTaskDrivingStyle`. Guessing numbers like `786603` by hand is slow, and reading one back is worse. This tool does both directions.

## Quick start

1. Pick a **Preset** (the page opens on **Normal**, `786603`) or tick the flags you want.
2. Read the result in the **Driving style** panel: **Decimal**, **Hex**, **Binary**, plus **Signed int32** when bit 31 is set.
3. In **Snippet options**, choose the **Task**, the **Driver** (**Player** or **NPC**) and the **Destination** (**Waypoint** or **Coords**).
4. Copy `driving_style.lua` from the code block under the calculator.

To decode, paste a value into **Decode a value**. It accepts decimal, negative int32, `0x` hex, `0b` binary and expressions like `1 | 2 | 128` (a `+` works as well). Underscores are ignored. The value is kept in the URL as `?v=`, so you can share a link to it.

## Flags

| Bit | Value | Name | What it does |
| --- | --- | --- | --- |
| 0 | 1 | StopForVehicles | Brakes and waits behind vehicles in its way. |
| 1 | 2 | StopForPeds | Stops for pedestrians on the road. |
| 2 | 4 | SwerveAroundAllVehicles | Swerves around moving and stopped vehicles instead of waiting. |
| 3 | 8 | SteerAroundStationaryVehicles | Steers around parked and empty vehicles. |
| 4 | 16 | SteerAroundPeds | Steers around pedestrians instead of stopping. |
| 5 | 32 | SteerAroundObjects | Steers around props on the road. |
| 6 | 64 | DontSteerAroundPlayerPed | Does not steer around the player: stops or hits it. |
| 7 | 128 | StopAtTrafficLights | Obeys red lights and stop lines. |
| 8 | 256 | GoOffRoadWhenAvoiding | May leave the road to get around something. |
| 9 | 512 | AllowGoingWrongWay | Uses oncoming lanes when its own lane is blocked. |
| 10 | 1024 | Reverse | Drives the whole route in reverse. |
| 11 | 2048 | UseWanderFallbackInsteadOfStraightLine | Wanders if no route is found, instead of a straight line. |
| 12 | 4096 | AvoidRestrictedAreas | Keeps out of restricted zones. |
| 13 | 8192 | PreventBackgroundPathfinding | Cruise tasks: no background re-planning. |
| 14 | 16384 | AdjustCruiseSpeedBasedOnRoadSpeed | Cruise tasks: matches each road's speed. |
| 15 | 32768 | Unknown15 | No known effect. |
| 16 | 65536 | Unknown16 | No known effect. |
| 17 | 131072 | Unknown17 | No known effect. |
| 18 | 262144 | UseShortCutLinks | Allows dirt tracks, alleys and other shortcut links. |
| 19 | 524288 | ChangeLanesAroundObstructions | Changes lanes to pass slower traffic. |
| 20 | 1048576 | Unknown20 | No known effect. |
| 21 | 2097152 | UseSwitchedOffNodes | Routes over nodes switched off for traffic (goto tasks only). |
| 22 | 4194304 | PreferNavmeshRoute | Navmesh pathing for off-road, roughly 200 m around the player. |
| 23 | 8388608 | PlaneTaxiMode | Planes on a goto task taxi on the ground. |
| 24 | 16777216 | ForceStraightLine | Ignores pathing, heads straight for the target. |
| 25 | 33554432 | UseStringPullingAtJunctions | Cuts corners through junctions. |
| 26 | 67108864 | Unknown26 | No known effect. |
| 27 | 134217728 | Unknown27 | No known effect. |
| 28 | 268435456 | Unknown28 | No known effect. |
| 29 | 536870912 | TryToAvoidHighways | Avoids highways when there is another way. |
| 30 | 1073741824 | ForceJoinInRoadDirection | Always joins a road in the direction of traffic. |
| 31 | 2147483648 | StopAtDestination | Brakes to a stop at the destination. |

Each flag row in the tool also shows older community names under "Also known as" (for example `DF_StopForCars`, or "Use blinkers" for bit 8). Unknown bits can be hidden with **Show unknown bits**. **All on**, **All off** and **Invert** work on the defined bits.

## Presets

| Preset | Value |
| --- | --- |
| Normal | 786603 |
| Strict | 262275 |
| Ignore lights | 786475 |
| Avoid vehicles | 786469 |
| Reckless | 786468 |
| Avoid, obey lights | 786597 |
| Avoid, stop for peds, lights | 786599 |
| Rushed | 1074528293 |
| Off-road allowed | 2883621 |
| Avoid highways | 537657515 |
| Plough through | 262144 |
| Straight line | 17039360 |

Under the flag list, **Values used in Rockstar's scripts** holds 39 raw values from the decompiled scripts. Click one to load and decode it.

## Snippet options

| Option | What it does | Default |
| --- | --- | --- |
| **Task** | `TaskVehicleDriveToCoord`, `TaskVehicleDriveToCoordLongrange`, `TaskVehicleDriveWander` or **SetDriveTaskDrivingStyle only** | TaskVehicleDriveToCoord |
| **Driver** | **Player** uses your current vehicle (you must be the driver). **NPC** adds a `SpawnDriver()` function that spawns an `adder` with `a_m_y_business_01` in front of you. | Player |
| **Destination** | **Waypoint** reads blip sprite 8, **Coords** uses the x, y, z fields. Only for the two goto tasks. | Waypoint |
| **Speed (m/s)** | Cruise speed, with km/h and mph shown under it. | 20 |
| **Stop range (m)** | How close to the target the task ends. Goto tasks only. | 8 |
| **Ability** / **Aggressiveness** | `SetDriverAbility` and `SetDriverAggressiveness`, 0.0 to 1.0. | 1.0 / 0.0 |

## Example

A trimmed version of what the tool writes for the Normal preset and a waypoint:

```lua title="driving_style.lua"
local drivingStyle = 786603
local speed = 20.0
local stopRange = 8.0

CreateThread(function()
    local ped = PlayerPedId()
    local vehicle = GetVehiclePedIsIn(ped, false)
    if vehicle == 0 or GetPedInVehicleSeat(vehicle, -1) ~= ped then return end

    local blip = GetFirstBlipInfoId(8) -- 8 = waypoint
    if not DoesBlipExist(blip) then return end
    local target = GetBlipInfoIdCoord(blip)

    SetDriverAbility(ped, 1.0)
    SetDriverAggressiveness(ped, 0.0)
    TaskVehicleDriveToCoord(ped, vehicle, target.x, target.y, target.z, speed, 0, GetEntityModel(vehicle), drivingStyle, stopRange, 1.0)
end)
```

> [!NOTE]
> When bit 31 is set the snippet writes the negative signed value, for example `local drivingStyle = -1073741824`, with the unsigned number in a comment. Natives take the style as an int32, so this is correct.

## Tips

- Speed is metres per second. 20.0 is about 72 km/h.
- NPC drivers react to gunfire and give up unless you call `SetBlockingOfNonTemporaryEvents(ped, true)`. The NPC snippet does this and adds `SetPedKeepTask`.
- Take control back from your own AI driving with `ClearPedTasks(ped)`.
- The yellow warning in the value panel means the value has bits with no known effect.

## Limitations

The descriptions reflect what is known about each bit from the FiveM native docs and community testing. The calculator runs entirely in your browser.

## Related tools

- [Animation Flags Calculator](/docs/tools/animation-flags-calculator)
- [Warning Screen Buttons](/docs/tools/warning-buttons)
- [Vehicle Handling Editor](/docs/tools/vehicle-handling-editor)
- [Interactive Map](/docs/tools/interactive-map)

_Last updated: 2026-09-22_

---

## Animation Flags Calculator

URL: https://fivemad.com/docs/tools/animation-flags-calculator

Build and decode the flag value for TaskPlayAnim: every eScriptedAnimFlags bit, common presets and a ready Lua snippet with dict loading and a toggle command.

The Animation Flags Calculator builds the `flag` argument of `TaskPlayAnim` from named bits, decodes values you find in other scripts, and writes a Lua snippet that loads the dictionary and plays the clip. It is for anyone writing emotes, interactions or cutscene-like moments.

## What it is for

The flag decides how an animation behaves: whether it loops, plays on the upper body only, lets the player walk, freezes on the last frame, ignores collision. Most scripts copy `49` around without knowing why. This tool shows every bit with its name from the `eScriptedAnimFlags` enum, so you can pick exactly what you need or see what a value in an old emote menu does.

## Quick start

1. Pick a **Preset** (the page opens on `49`, the classic emote flag) or toggle flags by hand.
2. In the **TaskPlayAnim** panel, click an **Example animation** or type your own **Anim dictionary** and **Anim name**.
3. Adjust **Blend in**, **Blend out**, **Duration (ms)** and **Playback rate** if needed.
4. Copy `play_anim.lua` from the code block under the calculator.

**Decode a value** in the **Animation flag** panel accepts `49`, `0x31`, `0b110001` or `1 | 16 | 32`. The value is stored in the URL (`?v=`) so a link shares it.

## Flags

| Bit | Value | Name | What it does |
| --- | --- | --- | --- |
| 0 | 1 | AF_LOOPING | Repeats until stopped. |
| 1 | 2 | AF_HOLD_LAST_FRAME | Freezes on the last frame instead of blending out. |
| 2 | 4 | AF_REPOSITION_WHEN_FINISHED | Moves the ped to where the clip ended. |
| 3 | 8 | AF_NOT_INTERRUPTABLE | AI events and other tasks cannot interrupt it. |
| 4 | 16 | AF_UPPERBODY | Only the upper body plays the clip. |
| 5 | 32 | AF_SECONDARY | Runs as a secondary task: the player keeps control. |
| 6 | 64 | AF_REORIENT_WHEN_FINISHED | Applies the clip's final heading to the ped. |
| 7 | 128 | AF_ABORT_ON_PED_MOVEMENT | Stops as soon as the ped moves. |
| 8 | 256 | AF_ADDITIVE | Plays as an additive layer on the current pose. |
| 9 | 512 | AF_TURN_OFF_COLLISION | No ped collision while playing. |
| 10 | 1024 | AF_OVERRIDE_PHYSICS | The clip fully drives position, physics ignored. |
| 11 | 2048 | AF_IGNORE_GRAVITY | No gravity while playing. |
| 12 | 4096 | AF_EXTRACT_INITIAL_OFFSET | Applies the clip's initial mover offset. |
| 13 | 8192 | AF_EXIT_AFTER_INTERRUPTED | Ends the task once interrupted. |
| 14 | 16384 | AF_TAG_SYNC_IN | Syncs the blend in with sync tags. |
| 15 | 32768 | AF_TAG_SYNC_OUT | Syncs the blend out with sync tags. |
| 16 | 65536 | AF_TAG_SYNC_CONTINUOUS | Keeps syncing to tags the whole time. |
| 17 | 131072 | AF_FORCE_START | Starts this frame even if the ped is busy. |
| 18 | 262144 | AF_USE_KINEMATIC_PHYSICS | Pushes objects but is not pushed back. |
| 19 | 524288 | AF_USE_MOVER_EXTRACTION | Moves the ped with the clip's mover track. |
| 20 | 1048576 | AF_HIDE_WEAPON | Hides the weapon while playing. |
| 21 | 2097152 | AF_ENDS_IN_DEAD_POSE | The clip ends in a dead pose. |
| 22 | 4194304 | AF_ACTIVATE_RAGDOLL_ON_COLLISION | Ragdolls on collision. |
| 23 | 8388608 | AF_DONT_EXIT_ON_DEATH | Keeps playing if the ped dies. |
| 24 | 16777216 | AF_ABORT_ON_WEAPON_DAMAGE | Stops on weapon damage. |
| 25 | 33554432 | AF_DISABLE_FORCED_PHYSICS_UPDATE | Skips the forced physics update at start. |
| 26 | 67108864 | AF_PROCESS_ATTACHMENTS_ON_START | Updates attached props on the first frame. |
| 27 | 134217728 | AF_EXPAND_PED_CAPSULE_FROM_SKELETON | Grows the capsule to fit the pose. |
| 28 | 268435456 | AF_USE_ALTERNATIVE_FP_ANIM | Uses the first-person variant if one exists. |
| 29 | 536870912 | AF_BLENDOUT_WRT_LAST_FRAME | Blend out finishes exactly at the last frame. |
| 30 | 1073741824 | AF_USE_FULL_BLENDING | Blends every bone fully. |

Older names from the first calculators (`ANIM_FLAG_REPEAT`, `ANIM_FLAG_STOP_LAST_FRAME`, `ANIM_FLAG_UPPERBODY`, `ANIM_FLAG_ENABLE_PLAYER_CONTROL`) are shown in the tool as "Also known as" on bits 0, 1, 4 and 5.

## Presets

| Preset | Value | Flags |
| --- | --- | --- |
| Play once | 0 | none |
| Loop | 1 | AF_LOOPING |
| Freeze at end | 2 | AF_HOLD_LAST_FRAME |
| Upper body once | 16 | AF_UPPERBODY |
| Upper body, can move | 48 | AF_UPPERBODY, AF_SECONDARY |
| Upper body loop, can move | 49 | AF_LOOPING, AF_UPPERBODY, AF_SECONDARY |
| Upper body hold, can move | 50 | AF_HOLD_LAST_FRAME, AF_UPPERBODY, AF_SECONDARY |
| Loop, can move | 51 | bits 0, 1, 4, 5 |
| Loop, stop when moving | 129 | AF_LOOPING, AF_ABORT_ON_PED_MOVEMENT |
| Cancelable | 120 | bits 3, 4, 5, 6 |
| Loop, no collision | 2561 | AF_LOOPING, AF_TURN_OFF_COLLISION, AF_IGNORE_GRAVITY |

## TaskPlayAnim panel

| Option | What it does | Default |
| --- | --- | --- |
| **Example animations** | Hands up, Arms crossed, Smoking, Cuffed, Wave, Triathlon idle. Sets dict, name and a fitting flag. | Hands up |
| **Anim dictionary** / **Anim name** | The clip to play. | `missminuteman_1ig_2` / `handsup_base` |
| **Blend in** / **Blend out** | 1.0 is a slow blend, 8.0 is nearly instant. | 8.0 / 8.0 |
| **Duration (ms)** | `-1` plays the whole clip, or forever when looping. | -1 |
| **Playback rate** | Really the start phase, 0.0 to 1.0. | 0.0 |
| **Lock X / Y / Z** | Passes `true` for lockX, lockY and lockZ. | off |
| **/anim toggle command** | Wraps it in a `/anim` command that starts or stops the clip. Off gives a plain `CreateThread`. | on |

## Example

The core of the generated snippet:

```lua title="play_anim.lua"
local function LoadAnimDict(dict)
    if not DoesAnimDictExist(dict) then return false end
    RequestAnimDict(dict)
    local timeout = GetGameTimer() + 5000
    while not HasAnimDictLoaded(dict) do
        if GetGameTimer() > timeout then return false end
        Wait(0)
    end
    return true
end

RegisterCommand("anim", function()
    local ped = PlayerPedId()
    local dict, name = "missminuteman_1ig_2", "handsup_base"
    if IsEntityPlayingAnim(ped, dict, name, 3) then
        StopAnimTask(ped, dict, name, 8.0)
    elseif LoadAnimDict(dict) then
        TaskPlayAnim(ped, dict, name, 8.0, 8.0, -1, 49, 0.0, false, false, false)
        RemoveAnimDict(dict)
    end
end, false)
```

## Tips

> [!TIP]
> Upper body alone (`16`) still blocks walking. Add `AF_SECONDARY` (`32`) to let the player move while the clip plays.

- Stop a clip with `StopAnimTask(ped, dict, name, blendOut)` or `ClearPedTasks(ped)`.
- `RemoveAnimDict` right after starting is fine: the running task keeps its own reference.
- For sitting or lying on props, try the **Loop, no collision** preset.
- Bit 31 is not part of this enum, so the bit strip only shows bits 0 to 30.

## Limitations

The tool does not check that a dictionary or clip name exists. The snippet does that at runtime with `DoesAnimDictExist` and a 5 second load timeout. Everything runs in the browser.

## Related tools

- [Driving Style Calculator](/docs/tools/driving-style-calculator)
- [Warning Screen Buttons](/docs/tools/warning-buttons)
- [Controls Reference](/docs/tools/controls-reference)

_Last updated: 2026-09-22_

---

## Warning Screen Buttons

URL: https://fivemad.com/docs/tools/warning-buttons

Pick the buttons for a GTA V alert screen, get the flag value for SetWarningMessageWithHeader, preview it and copy a Lua snippet that reads the input.

Warning Screen Buttons calculates the button flags for the full-screen GTA V alert (the black "Alert" screen with Yes / No at the bottom). You pick the buttons, see a preview with your own text, and copy a Lua snippet that draws the screen and waits for the player's choice.

## What it is for

`SetWarningMessage` and `SetWarningMessageWithHeader` take a bit field that decides which instructional buttons appear on the screen. Each bit adds one button: Yes is 4, No is 32, so Yes / No is `36`. Useful for "are you sure" prompts: leaving a job, deleting a character, confirming a purchase.

## Quick start

1. Pick a **Preset** (the page opens on **Yes / No**, `36`) or toggle buttons.
2. Fill **Header**, **Line 1** and **Line 2** in the **Text** panel and check the **Preview**.
3. Turn **Black background** on or off.
4. Copy `warning.lua`.

**Decode a value** in the **Button flags** panel reads `36`, `0x24` or `4 | 32` and shows which buttons it contains.

## Button flags

| Bit | Value | Name | Text | Key |
| --- | --- | --- | --- | --- |
| 0 | 1 | SELECT | Select | Enter |
| 1 | 2 | OK | OK | Enter |
| 2 | 4 | YES | Yes | Enter |
| 3 | 8 | BACK | Back | Esc |
| 4 | 16 | CANCEL | Cancel | Esc |
| 5 | 32 | NO | No | Esc |
| 6 | 64 | RETRY | Retry | Space |
| 7 | 128 | RESTART | Restart | Space |
| 8 | 256 | SKIP | Skip | Space |
| 9 | 512 | QUIT | Quit | Esc |
| 10 | 1024 | ADJUST | Adjust | Left / right arrows |
| 11 | 2048 | SPACE_NO_TEXT | (no text) | Space |
| 12 | 4096 | SHARE | Share | Space |
| 13 | 8192 | SIGN_IN | Sign In | Space |
| 14 | 16384 | CONTINUE | Continue | Enter |
| 15 | 32768 | ADJUST_ARROWS | Adjust | Left / right symbols |
| 16 | 65536 | SCROLL | Scroll | Up / down symbols |
| 17 | 131072 | OVERWRITE | Overwrite | Space |
| 18 | 262144 | SOCIAL_CLUB_SIGN_UP | Social Club Sign Up | Enter |
| 19 | 524288 | CONFIRM | Confirm | Enter |
| 20 | 1048576 | QUEUE | Queue | Enter |
| 21 | 2097152 | RETRY_ACCEPT | Retry | Enter |
| 22 | 4194304 | BACK_ESC | Back | Esc |
| 23 | 8388608 | SOCIAL_CLUB | Social Club | Enter |
| 24 | 16777216 | SPECTATE | Spectate | Space |
| 25 | 33554432 | OK_CANCEL_KEY | OK | Esc |
| 26 | 67108864 | CANCEL_TRANSFER | Cancel Transfer | Esc |
| 27 | 134217728 | LOADING_SPINNER | (spinner) | none |
| 28 | 268435456 | NO_RETURN_TO_GTA | No - Return to Grand Theft Auto V | Esc |
| 29 | 536870912 | CANCEL_ESC | Cancel | Esc |

The constant names are descriptive labels used by this tool. The game has no official names for most of these bits.

## Presets

| Preset | Value |
| --- | --- |
| OK | 2 |
| Yes / No | 36 |
| OK / Cancel | 18 |
| Confirm / Back | 524296 |
| Retry / Cancel | 80 |
| Continue | 16384 |
| Back / Continue | 16392 |
| Skip / OK | 258 |
| Loading spinner | 134217728 |
| Cancel + spinner | 134217744 |

## The generated snippet

The snippet registers your text with `AddTextEntry` (warning screens only take text entry keys, not raw strings), then draws the screen every frame until a key is pressed. Buttons are grouped by what they mean, and each group is checked with frontend controls in input group 2, which still work while the warning is up:

| Group | Controls checked |
| --- | --- |
| accept | 201, 217 (`INPUT_FRONTEND_ACCEPT`, `INPUT_FRONTEND_SELECT`) |
| cancel | 202 (`INPUT_FRONTEND_CANCEL`) |
| alt | 203 (`INPUT_FRONTEND_X`) |
| adjust | 189, 190 (`INPUT_FRONTEND_LEFT`, `INPUT_FRONTEND_RIGHT`) |
| scroll | 188, 187 (`INPUT_FRONTEND_UP`, `INPUT_FRONTEND_DOWN`) |

For Yes / No it looks like this:

```lua title="warning.lua"
local WARNING_FLAGS = 36 -- YES | NO

AddTextEntry("FM_WARN_HEADER", "Alert")
AddTextEntry("FM_WARN_LINE1", "Are you sure you want to leave the server?")
AddTextEntry("FM_WARN_LINE2", "Unsaved progress will be lost.")

local function ShowWarning()
    while true do
        SetWarningMessageWithHeader("FM_WARN_HEADER", "FM_WARN_LINE1", WARNING_FLAGS, "FM_WARN_LINE2", false, -1, true, 0, true)
        if IsControlJustPressed(2, 201) or IsControlJustPressed(2, 217) then return "accept" end
        if IsControlJustPressed(2, 202) then return "cancel" end
        Wait(0)
    end
end

CreateThread(function()
    local choice = ShowWarning()
    if choice == "accept" then
        print("Accepted")
    elseif choice == "cancel" then
        print("Cancelled")
    end
end)
```

If only the loading spinner (or nothing) is selected, there is nothing to press, so the snippet shows the screen for 5 seconds instead.

## Tips

> [!IMPORTANT]
> The buttons are only visual. The game does not report which one was pressed, you check the keys yourself, like the snippet does.

- The warning has to be drawn every frame, inside a loop with `Wait(0)`.
- Several bits share a key. Select, OK, Yes and Continue are all Enter, so combining two of them gives the player two labels for the same key.
- **Black background** is passed as the background argument of `SetWarningMessageWithHeader`.

## Limitations

The preview is an approximation of the game's layout, not a screenshot. Everything runs in the browser.

## Related tools

- [Controls Reference](/docs/tools/controls-reference)
- [Draw Text Colors](/docs/tools/text-colors)
- [Scaleform Functions](/docs/tools/scaleform-reference)
- [Driving Style Calculator](/docs/tools/driving-style-calculator)

_Last updated: 2026-09-22_

---

## Draw Text Colors

URL: https://fivemad.com/docs/tools/text-colors

Preview GTA V tilde colour and formatting codes live in DrawText, notifications and help text, and FiveM chat caret codes, with ready Lua snippets.

Draw Text Colors lets you type a string with GTA V formatting codes (`~r~`, `~h~`, `~n~`, `~INPUT_CONTEXT~` and friends) and see how it looks as on-screen text, a feed notification or a help text box. A second section does the same for the caret codes (`^1`, `^*`) of the FiveM chat. Every preview comes with a Lua snippet.

## What it is for

Testing text formatting in game means a restart or a resource reload for every tweak. Here you see the colours, bold parts, line breaks and key prompts as you type, then copy code that draws the same thing with the right natives.

## Quick start

1. Type in the **Text** box. The page starts with a sample that uses colours, a key prompt, a `~a~` name and a `~1~` number.
2. Click the colour buttons under the box (or any card in **Reference**) to insert a code at the cursor.
3. Pick the output style with the tabs above the preview: **DrawText**, **Notification** or **Help text**.
4. If your text has `~a~` or `~1~`, fill the value fields that appear under the text box.
5. Copy `drawtext.lua`, `notify.lua` or `helptext.lua`.

The preview uses system fonts in place of the game fonts, so it is close but not pixel exact.

## Tilde codes

| Code | Result | Colour |
| --- | --- | --- |
| `~r~` | Red | #E03232 |
| `~b~` | Blue | #5DB6E5 |
| `~g~` | Green | #72CC72 |
| `~y~` | Yellow | #F0C850 |
| `~p~` | Purple | #8466E2 |
| `~q~` | Pink | #CB3694 |
| `~o~` | Orange | #FF8555 |
| `~c~` | Grey | #8C8C8C |
| `~m~` | Dark grey | #646464 |
| `~u~` | Black | #000000 |
| `~l~` | Black | #000000 |
| `~d~` | Dark blue | #2F5C73 |
| `~f~` | Friendly blue | #5DB6E5 |
| `~w~` | White | #F0F0F0 |
| `~s~` | Back to the default colour | set by `SetTextColour` |
| `~h~` | Bold on / off | |
| `~bold~` | Bold on / off (newer builds) | |
| `~italic~` | Italic on / off (newer builds) | |
| `~n~` | New line | |
| `~a~` | String placeholder, filled by `AddTextComponentSubstringPlayerName` | |
| `~1~` | Integer placeholder, filled by `AddTextComponentInteger` | |
| `~ws~` | Wanted star icon | |
| `~EX_R*~` | Rockstar logo | |

A colour stays active until the next colour code. The **HUD colours** tab lists 32 `~HUD_COLOUR_NAME~` tokens (for example `~HUD_COLOUR_FREEMODE~`, `~HUD_COLOUR_REDLIGHT~`) with their RGB values, and they work inline the same way.

The **Buttons** tab lists `~INPUT_*~` tokens such as `~INPUT_CONTEXT~`, `~INPUT_ENTER~`, `~INPUT_DETONATE~` and `~INPUTGROUP_MOVE~`. In game they render the key the player has bound (or the pad button), so a prompt stays correct on custom bindings. The preview shows the default keyboard key.

## DrawText options

Shown only on the **DrawText** tab:

| Option | What it does | Default |
| --- | --- | --- |
| **Font** | 0 Chalet London, 1 House Script, 2 Monospace, 4 Chalet Comprime, 7 Pricedown | 4 |
| **Scale** | 0.2 to 1.2, written as `SetTextScale(0.0, scale)` | 0.5 |
| **Colour** / **Alpha** | Base colour for `SetTextColour`, and what `~s~` returns to | white, 255 |
| **X (0 to 1)** / **Y (0 to 1)** | Screen position for `EndTextCommandDisplayText` | 0.5 / 0.8 |
| **Outline** | Adds `SetTextOutline()` | on |
| **Drop shadow** | Adds `SetTextDropShadow()` | off |
| **Centre** | Adds `SetTextCentre(true)` | on |

## Snippets

DrawText is drawn every frame inside a thread:

```lua title="drawtext.lua"
CreateThread(function()
    while true do
        Wait(0)
        SetTextFont(4)
        SetTextScale(0.0, 0.5)
        SetTextColour(255, 255, 255, 255)
        SetTextOutline()
        SetTextCentre(true)
        BeginTextCommandDisplayText("STRING")
        AddTextComponentSubstringPlayerName("~b~Mission~s~ started.")
        EndTextCommandDisplayText(0.5, 0.8)
    end
end)
```

A notification is a single call:

```lua title="notify.lua"
BeginTextCommandThefeedPost("STRING")
AddTextComponentSubstringPlayerName("~g~Saved~s~ your outfit.")
EndTextCommandThefeedPostTicker(false, true)
```

Help text has to be called every frame while it should stay up:

```lua title="helptext.lua"
BeginTextCommandDisplayHelp("STRING")
AddTextComponentSubstringPlayerName("Press ~INPUT_CONTEXT~ to open the shop")
EndTextCommandDisplayHelp(0, false, true, -1)
```

When the text contains `~a~` or `~1~`, the snippet registers it with `AddTextEntry("FIVEMAD_TEXT", ...)` and adds one component per placeholder, in order, with the values you typed.

> [!NOTE]
> One `AddTextComponentSubstringPlayerName` is cut at 99 characters. For longer text without placeholders, the snippet switches to the built-in `CELL_EMAIL_BCON` entry and splits your text into chunks of up to 99 characters without breaking a `~code~` in half.

## FiveM chat colours

The default chat resource does not read tilde codes. It uses caret codes:

| Code | Result |
| --- | --- |
| `^0` | White |
| `^1` | Red |
| `^2` | Green |
| `^3` | Yellow |
| `^4` | Blue |
| `^5` | Light blue |
| `^6` | Purple |
| `^7` | White |
| `^8` | Orange red |
| `^9` | Grey |
| `^*` | Bold |
| `^_` | Underline |
| `^~` | Strikethrough |
| `^=` | Underline and strikethrough |
| `^r` | Reset |

Type an **Author** and **Text**, click the colour swatches (which also copy the code) or format buttons, and copy `chat.lua`:

```lua title="chat.lua"
TriggerEvent("chat:addMessage", {
    color = { 255, 255, 255 },
    multiline = true,
    args = { "Dispatch", "^1[Police]^0 Suspect spotted near ^3Legion Square^0." }
})
```

The colours shown are the stock chat stylesheet defaults. A custom chat theme can change them.

## Common mistakes

- Using `~r~` in chat messages or `^1` in DrawText. They do not mix.
- Forgetting `~s~` after a coloured word, so the rest of the line stays coloured.
- Showing help text once. It disappears the next frame unless you call it in a loop.

## Related tools

- [Controls Reference](/docs/tools/controls-reference)
- [Warning Screen Buttons](/docs/tools/warning-buttons)
- [Blip, Marker & Checkpoint Browser](/docs/tools/blip-marker-browser)
- [Scaleform Functions](/docs/tools/scaleform-reference)

_Last updated: 2026-09-22_

---

## Screen Effects Browser

URL: https://fivemad.com/docs/tools/screen-effects

Find the right GTA V timecycle modifier or animpostfx effect, see what it does before you try it, and copy the Lua that switches it on.

The Screen Effects Browser lists every named screen effect the game ships: 1,101 timecycle
modifiers and 252 animpostfx effects. Each one has a before and after preview you can drag, the
exact values it sets, and ready Lua.

## The two tabs

**Timecycle modifiers** are named sets of overrides on the lighting and the screen: light and
ambient colour, fog, exposure, the tone curve, colour correction, vignette, grain, blur and so on.
You switch one on and it stays on until you clear it. Most interiors, drunk and drugged states and
"this area feels different" effects on a server are a timecycle modifier.

**animpostfx** effects are stacks of those modifiers with timing on top. Each layer has a start
delay, a fade in, a hold and a fade out, and the stack can loop. The character switch flash, the
death fade and the race boost streaks are animpostfx.

## Finding one

- The search box matches the name, and for timecycle modifiers also the file it comes from. For
  animpostfx it also matches the modifiers the effect plays, so searching `nightvision` finds the
  effects that use it.
- The dropdown filters by source file for timecycle modifiers, or by a rough family (character
  switch, drugs, racing, damage, vision modes) for animpostfx.
- The three buttons on the right switch the viewpoint every card is rendered from: a city street,
  a shop interior and a view over the city. Interior lighting values show up best on the interior
  view, fog and far clip on the landscape one.

## Reading a card

Each card is the same view drawn twice: the left half with the game's clear noon lighting, the
right half with the effect's values on top. Drag the divider, or focus it and use the arrow keys.
The badge in the corner says how many parameters the modifier sets, or how many layers the effect
stacks.

## The detail view

Click a name to open it. You get:

- the bigger comparison and the viewpoint switcher
- a **strength** slider, which blends the effect back towards the plain frame the same way
  `SetTimecycleModifierStrength` blends a modifier towards the timecycle that is running
- the full parameter table, searchable and filterable by group, with both floats the game file
  stores, the clear noon value for comparison, and a mark on every parameter the preview draws
- for an animpostfx effect, the layer table with every duration and the layer blend settings
- cross links: which animpostfx effects play a modifier, and which modifiers an effect plays
- copy buttons for the name and for ready Lua
- **Open it live in the 3D map**, which loads the Interactive Map in 3D with the effect applied to
  the world and the same strength slider

## Using a timecycle modifier

```lua title="client.lua"
SetTimecycleModifier("CAMERA_BW")
SetTimecycleModifierStrength(0.6)   -- 0.0 to 1.0

-- later
ClearTimecycleModifier()
```

- Only one modifier is active at a time. Setting a second one replaces the first.
- `SetExtraTimecycleModifier` and `ClearExtraTimecycleModifier` give you a second slot that stacks
  on top.
- Modifiers are client side and per player.

> [!TIP]
> Strength is the cheapest way to make a strong effect usable. Most of the dramatic modifiers look
> right somewhere between 0.3 and 0.6.

## Playing an animpostfx effect

```lua title="client.lua"
AnimpostfxPlay("SwitchHUDIn", 0, true)  -- 0 = the effect's own timings, true = loop

AnimpostfxStop("SwitchHUDIn")
AnimpostfxStopAll()

if AnimpostfxIsRunning("SwitchHUDIn") then
    -- ...
end
```

> [!WARNING]
> A looping effect runs until something stops it. Always pair a loop with an `AnimpostfxStop`, and
> call `AnimpostfxStopAll()` when your resource stops, or players get stuck with it.

## What the previews can and cannot show

The pictures are ours, rendered from the effect's own values. They show light and ambient colour
and intensity, fog colour, density, start and far clip, exposure, the filmic tone curve, colour
correction and colour shift, saturation, the screen gradient, vignette, grain, scan lines,
chromatic aberration, lens distortion, bloom, blur, depth of field and the night vision curve.

They do not show shadows, ambient occlusion, reflections, water, streaming distances, heat haze,
god rays, light directions, lens flares or the weather and particle switches. Those parameters are
still in the table, just not in the picture.

Treat a preview as a hint about the direction an effect pulls the image in. The parameter tables,
the layer timings and the names are exact.

## Names shown as a hash

A few animpostfx effects are listed with a `hash_xxxxxxxx` name. The game only stores the hash for
those and the readable string is not in the files we can read, so there is nothing to type. They
are shown so the list is complete.

_Last updated: 2026-09-23_

---

## Model & Hash Browser

URL: https://fivemad.com/docs/tools/model-hash-browser

Search every GTA V vehicle, ped and weapon by spawn name, display name or hash, copy hashes in any format and get a ready Lua spawn snippet.

The Model & Hash Browser lists every GTA V vehicle (921), ped (1,109) and weapon (184) with a picture, spawn name, display name, class and hash. Search by any of them, paste a hash to find out which model it is, and copy a Lua snippet that spawns or gives the thing you picked.

## What it is for

- You need the spawn name of a car you only know by its in-game name (Zentorno, Pegassi Tempesta).
- A log or an event prints `-1216765807` and you want to know which model that is.
- You are filling a garage, shop or whitelist config and need exact names and hashes.
- You want the right ped model for an NPC, or the `WEAPON_` name for a loadout.

## Quick start

1. Pick a tab: **Vehicles**, **Peds** or **Weapons**.
2. Type in the search box: a spawn name (`adder`), a display name (`Zentorno`), a manufacturer (vehicles), or a hash.
3. Narrow it down with the filters next to the search box.
4. Click the spawn name or the hash on a card to copy it.
5. Click anywhere else on the card to open the details drawer with every hash format and a Lua snippet.

## Search and filters

The search matches spawn name, display name and (for vehicles) manufacturer. Several words narrow the search: `pegassi super` finds cars with both words. Quotes and backticks are ignored, so you can paste `` `adder` `` straight from a script.

A hash in any format finds its model:

| Format | Example (Adder) |
| --- | --- |
| Signed | `-1216765807` |
| Unsigned | `3078201489` |
| Hex with `0x` | `0xB779A091` |
| Hex without `0x` (8 digits) | `B779A091` |

| Filter | Tabs | What it filters |
| --- | --- | --- |
| **Any class** / **Any ped type** / **Any category** | all | Vehicle class (Super, Sport, Emergency...), ped type (Civ Male, Cop, Animal...) or weapon category (Pistol, Rifle, Thrown...). Each option shows how many entries it has. |
| **Any type** | Vehicles | Vehicle type: Car, Bike, Boat, Heli, Plane, Trailer, Submarine and so on. |
| **Any DLC** | all | The update that added it. |

The line under the filters shows how many entries match, with a **Reset filters** button. Results load 48 at a time; scroll to the button at the bottom for more.

Switching tabs resets the filters. Your search, filters, tab and the open drawer are kept in the page URL, so you can bookmark or share a link to an exact result.

### Card hash format

**Card hash** (top right) picks which hash the cards show: **Signed**, **Unsigned** or **Hex**. It only changes the cards; the drawer always shows all formats.

## The details drawer

Opens from the right on desktop and from the bottom on phones. <kbd>Esc</kbd>, the close button or a click outside closes it.

**Hashes** (every tab), each one click to copy:

| Row | Example |
| --- | --- |
| Spawn name | `adder` |
| Signed | `-1216765807` |
| Unsigned | `3078201489` |
| Hex | `0xB779A091` |
| Lua backtick | `` `adder` `` |

### Vehicles

- **Details**: manufacturer, class, type, seats, wheels, DLC, value, sirens and armored glass.
- **Performance**: top speed (km/h and mph), acceleration, braking and traction as bars, scaled against land vehicles.
- **Mod kits**, **Vehicle weapons** and **Flags** (the model's `FLAG_` list without the prefix).
- **Spawn it** snippet:

```lua
local model = `adder`
RequestModel(model)
while not HasModelLoaded(model) do Wait(0) end

local ped = PlayerPedId()
local coords = GetEntityCoords(ped)
local veh = CreateVehicle(model, coords.x, coords.y, coords.z, GetEntityHeading(ped), true, false)
SetPedIntoVehicle(ped, veh, -1)
SetVehicleNumberPlateText(veh, "FIVEMAD")
SetModelAsNoLongerNeeded(model)
```

Top speed is the game's estimated max speed for the model (what `GetVehicleModelEstimatedMaxSpeed` returns), not a measured run. Jets and some boats sit at the top of the bar. Handling edits and upgrades change the real numbers.

### Peds

- **Details**: display name, ped type, DLC.
- **Use it** snippet, to change the player model or spawn the ped as an NPC:

```lua
local model = `a_m_y_hipster_01`
RequestModel(model)
while not HasModelLoaded(model) do Wait(0) end

-- Change the player model
SetPlayerModel(PlayerId(), model)
SetPedDefaultComponentVariation(PlayerPedId())

-- Or spawn it as an NPC
-- local c = GetEntityCoords(PlayerPedId())
-- local npc = CreatePed(4, model, c.x + 2.0, c.y, c.z, 0.0, true, false)

SetModelAsNoLongerNeeded(model)
```

### Weapons

- The in-game description, when there is one.
- **Details**: category, ammo type, damage type, max ammo (MP), number of components and tints, weapon model, DLC, and whether it is a vehicle weapon.
- **Components, tints and flags** opens the [Weapon Stats & Components](/tools/weapon-stats) tool on this weapon.
- **Give it** snippet, with the weapon's max MP ammo:

```lua
local ped = PlayerPedId()
GiveWeaponToPed(ped, `WEAPON_PISTOL`, 250, false, true)
```

## Signed, unsigned or hex?

They are the same 32-bit hash of the spawn name, written three ways. Natives such as `GetEntityModel` and `GetHashKey` return the signed form, dumps and native docs often use hex, and most natives accept any of them. In Lua you can skip the lookup and write the name in backticks: `` `adder` `` is turned into the hash when the script loads.

```lua
local veh = GetVehiclePedIsIn(PlayerPedId(), false)
if GetEntityModel(veh) == `adder` then
    print("You are in an Adder")
end
```

## Tips

- Paste an unknown hash from an error or a log first. It is the fastest way to find out which model a script is talking about.
- Compare models with backticks or `GetHashKey`, not with a hard-coded unsigned number: natives hand you the signed value.
- Weapon names are upper case by convention (`WEAPON_PISTOL`), but hashes ignore case, so `weapon_pistol` gives the same hash.
- Some peds and newer DLC models have no picture yet. They show an icon instead; the names and hashes are still right.

## Limitations

- Base game content only. Addon vehicles, peds and weapons from your server are not listed. For those, hash the name with the [joaat Hash Calculator](/tools/hash-calculator).
- Stats are the game's reference values, not the handling on your server.
- Pictures are loaded from the FiveM docs site.

## Related tools

- [joaat Hash Calculator](/docs/tools/hash-calculator)
- [Weapon Stats & Components](/docs/tools/weapon-stats)
- [Objects / Props List](/docs/tools/objects-list)
- [Vehicle Handling Editor](/docs/tools/vehicle-handling-editor)

_Last updated: 2026-09-22_

---

## Interactive Map

URL: https://fivemad.com/docs/tools/interactive-map

Find any spot on the GTA V map, copy exact vector3 and vector4 coordinates, drop pins, measure distances and share links to a location.

The Interactive Map is the whole GTA V map in your browser, with coordinates under the cursor. Click to drop a pin and copy it as `vector3` or `vector4`, measure a route, or share a link that opens the map on an exact spot. On a desktop you can switch to a 3D world and move to the place you are about to script with a freecam or on foot. It is for anyone who needs coordinates without starting the game: spawn points, blips, job locations, teleports, zones.

## What it is for

Most FiveM configs are full of coordinates. Getting them usually means joining your server, walking to the spot and printing `GetEntityCoords`. With the map you can pick rough positions for a whole job route in a minute, check the distance between two shops, or look up where a coordinate from a config actually is. For spots where height matters (a roof, under a bridge), use the 3D view or fine tune the z in game.

## Quick start

1. Open the tool. On a desktop it starts in the **3D world** at Legion Square; press **2D map** to see the flat map. On phones and tablets it opens the 2D map.
2. Drag to pan, scroll (or pinch) to zoom. The box in the bottom right corner shows `x, y` under the cursor, plus `z` when the ground height there is known.
3. With **Drop pins** active, click the map. A pin appears and is added to **Pins** on the right.
4. In the pin card, set **heading** if you need one, then press **vector3** or **vector4** to copy the line.
5. Paste it into your script or config.

## The 2D map

| Control | What it does |
| --- | --- |
| Drag | Pan the map. |
| Mouse wheel / pinch | Zoom, centred on the cursor. |
| **+** / **-** buttons (top right) | Zoom in and out one step. |
| Click | Drop a pin (**Drop pins** tool) or add a measure point (**Measure** tool). |
| Cursor box (bottom right) | `x, y` and `z` of the spot under the mouse. |
| Scale bar (bottom left) | Shows metres or kilometres at the current zoom. |

When you have been in the 3D view, a small white arrow on the 2D map shows where the 3D camera is and which way it looks.

### Drop pins

The default tool. Each click drops a pin at that spot with the ground height filled in. If the height is still loading when you click, the z is filled in about a second later. Pins draw a short line in the direction of their heading.

### Measure

Switch to **Measure** and click two or more points. The **Measure** card shows:

- **flat distance**: the length of the line on the map, point to point.
- **with height**: the same route including height differences.
- **points**: how many points you clicked.

Distances over 1000 m are shown in km. **Clear** starts over. The measure line stays on the map when you switch back to pins, until you clear it.

## Go to a place or coordinates

The search box at the top of the side panel does two things:

- **Places**: with an empty box you get a list of well known spots (Legion Square, Pillbox Hill Medical, Mission Row Police, Maze Bank Tower roof, Vespucci Beach, Del Perro Pier, Vinewood Sign, LS International Airport, Sandy Shores, Paleto Bay, Mount Chiliad, Fort Zancudo). Type to filter, click one (or press <kbd>Enter</kbd> for the first match) to jump there.
- **Coordinates**: paste a coordinate in any common format, for example `vector3(195.2, -933.8, 30.7)`, `vector4(...)`, `{x = ..., y = ..., z = ...}` or plain `195.2, -933.8, 30.7`. A **Go to x, y and pin it** button appears. Click it or press <kbd>Enter</kbd> to centre the map there and drop a pin, with the heading from a `vector4`.

This is the quickest way to answer "where is this coordinate from the config?".

## Pins

The **Pins** card lists every pin with its x, y, z. Pins are saved in your browser, so they are still there next time you open the map.

- Click a pin's coordinates to centre the map (or the 3D camera) on it.
- Click a pin card to make it active. The active pin is drawn larger on the map.
- The trash icon removes one pin, **Clear** removes all of them.

The active pin opens its editor:

| Field / button | What it does |
| --- | --- |
| **z** | Height. Filled in from the map, edit it if you know better (roofs, bridges, interiors). |
| **heading** | 0 faces north, 90 west, 180 south, 270 east, the same as `GetEntityHeading`. Values are wrapped into 0-360. |
| **vector3** | Copies `vector3(x, y, z)`, rounded to 2 decimals. |
| **vector4** | Copies `vector4(x, y, z, heading)`, heading rounded to 1 decimal. |
| **Link** | Copies a link that opens the map on this pin with the same heading. |
| **See in 3D** | Desktop only. Opens the 3D world standing at the pin, looking along its heading. |

### Share links

A link looks like `https://fivemad.com/tools/interactive-map#at=195.2,-933.8,29.7,90&zoom=6`. Opening it shows the 2D map centred on that spot and adds a pin labelled **Shared** (only once, even if you open the link again). Good for pointing a teammate at the exact spot you mean.

## The 3D world

Press **3D world** (desktop browser with mouse and keyboard) to leave the flat map and move through the world itself. It opens standing at the active pin, or, with no pin selected, above the area you were looking at on the 2D map. In 3D:

- Click the view to look around with the mouse, <kbd>Esc</kbd> releases it. Holding the right mouse button also works.
- <kbd>W</kbd> <kbd>A</kbd> <kbd>S</kbd> <kbd>D</kbd> move, <kbd>Shift</kbd> goes faster, <kbd>Space</kbd> up, <kbd>C</kbd> down, the mouse wheel sets the camera speed.
- **Freecam** and **Walk** switch the movement mode.
- **Pin here** (bottom left) drops a pin on the ground under the camera, with the camera's heading. Switch back to **2D map** to copy it.
- Picking a place or pasting coordinates in the search box teleports the camera above that spot.

Every key and the quality settings are in the [3D world](/docs/tools/world-3d) docs.

## Examples

A pin copied as `vector4` works straight away as a spawn point:

```lua title="client.lua"
local spawn = vector4(195.2, -933.8, 29.7, 144.0)

RegisterCommand('legion', function()
    local ped = PlayerPedId()
    SetEntityCoords(ped, spawn.x, spawn.y, spawn.z, false, false, false, false)
    SetEntityHeading(ped, spawn.w)
end, false)
```

A `vector3` for a map blip:

```lua title="client.lua"
local shop = vector3(25.7, -1347.3, 29.5)

CreateThread(function()
    local blip = AddBlipForCoord(shop.x, shop.y, shop.z)
    SetBlipSprite(blip, 52)
    SetBlipAsShortRange(blip, true)
    BeginTextCommandSetBlipName("STRING")
    AddTextComponentSubstringPlayerName("24/7")
    EndTextCommandSetBlipName(blip)
end)
```

A list of pins pasted into a config for a job route:

```lua title="config.lua"
Config.Deliveries = {
    vector3(-1300.0, -1600.0, 3.3),
    vector3(1860.0, 3678.0, 32.5),
    vector3(-287.0, 6220.0, 30.5),
}
```

## Tips

- The z under the cursor is the top surface: ground, road or roof. For a spot under a bridge or inside a building, fix the z by hand or check it in the 3D view.
- `GetEntityCoords(PlayerPedId())` returns a point about 1 m above the ground (the pelvis). Map pins sit on the ground. For `SetEntityCoords` either is fine; for props and markers, the ground value is what you want.
- Use the **Measure** tool to size `#(a - b) < radius` checks, zones and delivery payouts before you write them.
- Pins are only stored in this browser. Copy what you need, or use **Link** to move a pin to another device.

> [!TIP]
> The [YMAP Builder](/tools/ymap-builder) imports `vector3` and `vector4` lines directly, so a set of pins can become a set of placed props.

## Limitations

- Heights are accurate to a few metres. Always check spawn heights on roofs, bridges and stairs in game.
- Cayo Perico and North Yankton are not on the map.
- The 3D view needs a desktop browser with WebGL 2, a mouse and a keyboard. On phones the 2D map works fully.
- Pins, measure points and links stay in your browser. Nothing is uploaded.

## Related tools

- [3D world](/docs/tools/world-3d)
- [YMAP Builder](/docs/tools/ymap-builder)
- [Blip, Marker & Checkpoint Browser](/docs/tools/blip-marker-browser)
- [Objects / Props List](/docs/tools/objects-list)

_Last updated: 2026-09-23_

---

## 3D world

URL: https://fivemad.com/docs/tools/world-3d

Move through GTA V in your browser with a freecam or on foot: every key and mouse control, the quality settings, what is shown, and tips for a smooth frame rate.

The 3D world is GTA V's map, rendered in your browser so you can move through it like a free camera. It is the **3D world** tab of the [Interactive Map](/tools/interactive-map) and the **3D world** panel of the [YMAP Builder](/tools/ymap-builder). Use it to scout a location before you script it, check what a spot looks like from the street, grab a pin at an exact place, or place ymap props where they belong.

## Where you find it

| Where | How to open it | What is different |
| --- | --- | --- |
| [Interactive Map](/tools/interactive-map) | On a desktop it opens in 3D straight away. Otherwise press the **3D world** tab, or **See in 3D** on a pin. | Clicking the view captures the mouse for looking around. Has **Pin here**. |
| [YMAP Builder](/tools/ymap-builder) | **3D world** button in the **Top-down preview** panel. | Clicking selects and places props, so you look around with the right mouse button. Adds the prop editing toolbar (see the [YMAP Builder docs](/docs/tools/ymap-builder)). |

Both need a desktop browser with WebGL 2, a mouse and a keyboard. On phones the Interactive Map stays on the 2D map and the YMAP Builder hides the button.

## Quick start

1. Open the [Interactive Map](/tools/interactive-map) on a desktop. You start above Legion Square.
2. Click the view. The mouse now turns the camera. Press <kbd>Esc</kbd> to get the pointer back.
3. Hold <kbd>W</kbd> to move forward. Scroll the mouse wheel to change speed.
4. Press **Walk** in the top left toolbar to drop to street level and walk.
5. Press **Pin here** to save the spot, then switch to **2D map** to copy it as `vector3` or `vector4`.

## Toolbar

The toolbar sits in the top left corner of the view.

| Control | What it does |
| --- | --- |
| **Freecam** | Free camera. The default. |
| **Walk** | Walk on the ground with gravity, at eye height. |
| Quality (gauge icon) | **Low**, **Medium** or **High**. Remembered for next time. See Quality below. |
| **Full screen** | Puts the view in full screen (in the YMAP Builder the whole panel, toolbar included). <kbd>Esc</kbd> or **Exit full screen** leaves it. |

The box in the top right corner shows live numbers: **fps** (amber below 30), **draws** (draw calls), **tris** (triangles in millions), **nodes** (world pieces loaded, plus how many are still loading), **props** (trees, lamps, benches and other props drawn right now), **data** (MB of world data loaded), **heap** (browser memory, only in Chromium browsers) and, in freecam, **speed** in m/s.

## Controls

### Looking around

| Input | What it does |
| --- | --- |
| Click the view | Interactive Map: captures the mouse, so moving it turns the camera. <kbd>Esc</kbd> releases it. |
| Hold right mouse button and drag | Turns the camera without capturing the mouse. Works in both tools, and is the only way in the YMAP Builder. |

The keyboard only works while the view has focus. If keys do nothing, click the view once.

### Freecam

| Key | Action |
| --- | --- |
| <kbd>W</kbd> / <kbd>Up</kbd> | Forward, in the direction you look (up and down too) |
| <kbd>S</kbd> / <kbd>Down</kbd> | Back |
| <kbd>A</kbd> / <kbd>Left</kbd>, <kbd>D</kbd> / <kbd>Right</kbd> | Strafe left, right |
| <kbd>Space</kbd> or <kbd>E</kbd> | Straight up |
| <kbd>C</kbd>, <kbd>Q</kbd> or <kbd>Ctrl</kbd> | Straight down |
| <kbd>Shift</kbd> (hold) | 4x speed |
| Mouse wheel | Camera speed, from 2 to 800 m/s. Starts at 40 m/s. |

The camera eases in and out of movement, so short taps give small, precise moves.

### Walk

| Key | Action |
| --- | --- |
| <kbd>W</kbd> <kbd>A</kbd> <kbd>S</kbd> <kbd>D</kbd> / arrows | Walk along the ground, relative to where you look |
| <kbd>Shift</kbd> (hold) | Run (twice the walking speed) |
| <kbd>Space</kbd> | Jump |

In walk mode you follow the ground and roofs, you step up curbs and stairs, and you cannot climb anything higher than about 0.8 m in one step. Walls stop you and you slide along them. Doorways stay open. Props such as trees, lamp posts and benches do not block you. The mouse wheel does nothing while walking.

Switch to **Walk** while you are high up and you fall to the ground under you. If the ground there has not loaded yet, you hover until it has.

## Quality

The quality menu trades detail for frame rate. The choice is saved in your browser.

| Setting | Draw distance | Textures | Interiors | Props on screen | Resolution |
| --- | --- | --- | --- | --- | --- |
| **Low** | Shorter than the game | Less filtering | Off | Up to 25,000 | Normal |
| **Medium** (default) | Same as the game | Sharper at angles | On | Up to 50,000 | Slightly sharper on high DPI screens |
| **High** | Longer than the game | Sharpest | On | Up to 90,000 | Full sharpness on high DPI screens |

The setting applies right away, no reload needed.

## What you see

- The whole main island: Los Santos, Blaine County and Paleto Bay, with terrain, roads, buildings, bridges and the sea, lakes and rivers.
- Detail changes with distance like in the game: far away you see the low detail versions of districts and mountains, and full detail buildings, trees and street props appear as you get closer.
- Street props and vegetation: trees, lamp posts, benches, bins, fences and so on.
- Interiors of many buildings that are open in the base game (police stations, banks, shops, the car showroom and others) on **Medium** and **High**. They load when you are close to them.
- Fixed calm daylight.

Not shown:

- Cayo Perico and North Yankton.
- Peds, traffic, parked vehicles and animals.
- Time of day, weather, street lights at night and shadows.
- Interiors that a server has to load with a script, and interiors on **Low**.

Textures are lighter than the game's, so close up surfaces look flatter than in GTA V. Distances, heights and positions match the game.

## Performance tips

- Watch **fps** in the corner. If it drops below 30 (it turns amber), switch to **Low**.
- Move slower when you arrive somewhere new. At full speed the world has to catch up, so you see low detail for a moment. At the same spot a second later everything is there.
- **Full screen** renders more pixels. On a weak GPU a normal size view is smoother.
- Use a browser with hardware acceleration on. If `chrome://gpu` or `about:support` says WebGL is software only, the view will be slow or will not start.
- Laptops: plug in and pick the high performance GPU for your browser if you have two.
- Close other heavy tabs (other 3D pages, video). Only one 3D view runs well at a time.
- If **data** keeps climbing after a long session and things get choppy, reload the page.

## Messages you may see

| Message | Meaning |
| --- | --- |
| **Loading the world...** | The view is starting. Takes a few seconds the first time. |
| **WebGL 2 is not available in this browser, so the 3D view can't run.** | Your browser or GPU does not support WebGL 2, or hardware acceleration is off. The 2D map still works. |
| **The 3D world data is not available right now.** | The world could not be loaded. Try again later. |
| **The 3D view failed to start.** | Something went wrong while starting. A reload usually fixes it. |

## Common mistakes

- **Keys do nothing.** The view does not have focus. Click it once.
- **The mouse is stuck.** You clicked the view in the Interactive Map, which captures the pointer. Press <kbd>Esc</kbd>.
- **Walking through a tree or bench.** Props do not block you in walk mode. Walls and buildings do.
- **Low detail everywhere.** You are moving faster than the world loads, or **Low** is selected. Stop for a second, or pick **Medium**.

## Limitations

- Desktop only: WebGL 2, a mouse and a keyboard are needed.
- It is a viewer. Positions you pick here are exact enough for scripts, but check spawn heights on roofs and stairs in game.
- Everything runs in your browser. Nothing you do in the view is uploaded.

## Related tools

- [Interactive Map](/docs/tools/interactive-map)
- [YMAP Builder](/docs/tools/ymap-builder)
- [Objects / Props List](/docs/tools/objects-list)

_Last updated: 2026-09-23_

---

## Blip, Marker & Checkpoint Browser

URL: https://fivemad.com/docs/tools/blip-marker-browser

Pick a GTA V blip sprite and colour, a DrawMarker type or a race checkpoint by picture, tune it, and copy a ready FiveM Lua snippet.

The Blip, Marker & Checkpoint Browser shows every map blip sprite (966), blip colour (100), marker type (44) and checkpoint type (50) with a preview and its id. Click one to copy the id, tune the options in the side panel, and copy a Lua snippet that creates it.

## What it is for

Blip sprite 52, colour 2, marker 1: scripts are full of these numbers and nobody remembers them. Instead of guessing and reconnecting, you pick the icon or shape by picture here, check how the colour looks on it, and paste a working snippet into your client script.

## Quick start

1. Pick a tab: **Sprites**, **Colours**, **Markers** or **Checkpoints**. The tab is kept in the URL (`?tab=markers`), so you can link straight to it.
2. Search by id or name in the box on the right. A number matches ids that start with it.
3. Click a tile. It becomes the selected one and its id is copied (the tile briefly says **Copied**).
4. Adjust the options in the panel (**Blip**, **Marker** or **Checkpoint**).
5. Copy the code block under the panel (`blip.lua`, `marker.lua` or `checkpoint.lua`).

## Sprites and colours

The **Sprites** and **Colours** tabs share the **Blip** panel.

| Option | What it does | Default |
| --- | --- | --- |
| **Colour** swatches | Pick the blip colour. Picking one also turns the tint preview on. | 0 (White) |
| **Tint preview** | Multiplies the sprite previews by the selected colour, the way the game tints white icons. | off |
| **Label** | The name shown in the map legend. | `My Blip` |
| **Scale** | Blip size, 0.3 to 2. | 0.8 |
| **Coords (x, y, z)** | Where the blip goes. Any `x, y, z` text works. | `215.76, -810.12, 30.73` |
| **Short range** | Only show it on the minimap when the player is nearby. | on |

The **Colours** tab lists every `SetBlipColour` value with its name and hex code. Some colours have **enemy** and **friendly** variants: picking one adds `SetBlipAsFriendly` to the snippet.

Most sprites are white and take the colour. A few (police, gang and mission icons) are already coloured and ignore it, which the tint preview shows too.

```lua title="blip.lua"
local blip = AddBlipForCoord(215.76, -810.12, 30.73)
SetBlipSprite(blip, 1) -- radar_level
SetBlipDisplay(blip, 4)
SetBlipScale(blip, 0.8)
SetBlipColour(blip, 0) -- White
SetBlipAsShortRange(blip, true)
BeginTextCommandSetBlipName("STRING")
AddTextComponentSubstringPlayerName("My Blip")
EndTextCommandSetBlipName(blip)
```

`SetBlipDisplay(blip, 4)` shows the blip on both the pause map and the minimap.

## Markers

The **Markers** tab lists every `DrawMarker` type with a picture. The **Marker** panel:

| Option | What it does | Default |
| --- | --- | --- |
| **Scale X / Y / Z** | Size on each axis. | 1.0, 1.0, 1.0 |
| **Colour** | Any colour from the picker. | `#5db6e5` |
| **Alpha** | Opacity, 0 to 255. | 150 |
| **Blip colour presets** | The first 30 blip colours as quick picks, so a marker can match its blip. | |
| **Bob up and down** | Marker floats up and down. | off |
| **Rotate** | Marker spins. | off |
| **Face camera** | Marker always turns towards the camera. | off |
| **Draw distance** | Only draw it when the player is within this many metres. | 20 |
| **Coords** | Marker position (shared with the blip coords). | |

Markers only last one frame, so the snippet draws it every tick while you are close and sleeps 500 ms when you are not. The z is lowered by 0.98 so the marker sits on the ground when you paste player coordinates.

```lua title="marker.lua"
local pos = vector3(215.76, -810.12, 30.73)

CreateThread(function()
    while true do
        local sleep = 500
        local dist = #(GetEntityCoords(PlayerPedId()) - pos)
        if dist < 20.0 then
            sleep = 0
            DrawMarker(
                1, -- MarkerTypeVerticalCylinder
                pos.x, pos.y, pos.z - 0.98,
                0.0, 0.0, 0.0,   -- direction
                0.0, 0.0, 0.0,   -- rotation
                1.0, 1.0, 1.0,   -- scale
                93, 182, 229, 150,   -- rgba
                false, false, 2, false,
                nil, nil, false
            )
        end
        Wait(sleep)
    end
end)
```

## Checkpoints

The **Checkpoints** tab lists the `CreateCheckpoint` types (race cylinders, rings, arrows, flags). Ids match game build 2189 and newer. Types that are not used in game are dimmed. A checkpoint is created once and the game keeps drawing it until you delete it, so there is no per-frame loop.

| Option | What it does | Default |
| --- | --- | --- |
| **Number or icon (reserved)** | Only for types 44 to 46. Pick a group (numbers 0 to 99, or chevrons, circles, arrows and spheres with a digit, 100 to 189) and a value. The preview tile updates. | 1 |
| **Position (x, y, z)** | Where the checkpoint is. Shared with the blip and marker coords. | |
| **Next point (x, y, z)** | Only sets where the arrow faces. Pass the next checkpoint of the route. | `225.40, -798.90, 30.73` |
| **Diameter** | 0.5 to 20. | 4 |
| **Colour** / **Alpha** | Main colour. | `#5db6e5`, 120 |
| **Blip colour presets** | Quick picks for the main colour. | |
| **Icon colour** / **Alpha** | Colour of the arrow, flag or number inside. | white, 200 |
| **Cylinder height**: **Near**, **Far**, **Radius** | Height while the player is within the radius (near) and outside it (far). | 2.0, 2.0, 4.0 |
| **Delete when reached** | Adds a loop that deletes the checkpoint once the player is inside it. | on |

```lua title="checkpoint.lua"
local pos = vector3(215.76, -810.12, 30.73)
local nextPos = vector3(225.40, -798.90, 30.73) -- arrows point here

-- Created once. The game draws it every frame until you delete it.
local cp = CreateCheckpoint(
    12, -- Ring, 1 arrow
    pos.x, pos.y, pos.z,
    nextPos.x, nextPos.y, nextPos.z,
    4.0, -- diameter
    93, 182, 229, 120, -- rgba
    0 -- reserved
)
SetCheckpointCylinderHeight(cp, 2.0, 2.0, 4.0) -- near, far, radius
SetCheckpointRgba2(cp, 255, 255, 255, 200) -- icon colour, old name SetCheckpointIconRgba

CreateThread(function()
    while true do
        if #(GetEntityCoords(PlayerPedId()) - pos) < 2.0 then
            DeleteCheckpoint(cp)
            break
        end
        Wait(100)
    end
end)

AddEventHandler("onResourceStop", function(resource)
    if resource == GetCurrentResourceName() then DeleteCheckpoint(cp) end
end)
```

## Tips

- Use **Short range** for shops, garages and other static points so the minimap edge stays clean.
- `SetBlipScale` between 0.8 and 1.0 matches most vanilla blips.
- Set the same coordinates once: the blip, marker and checkpoint panels share one position, so a shop's blip and its marker line up.
- For a race, chain checkpoints by passing the following checkpoint as **Next point**, and use a chequered flag type for the last one.
- Grab coordinates on the [Interactive Map](/tools/interactive-map) and paste them into **Coords**.

## Common mistakes

- **Marker flickers or costs CPU.** `DrawMarker` must run every frame while visible, but the thread should sleep when the player is far away. Keep the distance check.
- **Checkpoints pile up.** `CreateCheckpoint` inside a loop creates a new one every tick. Create once, delete with `DeleteCheckpoint`.
- **Blip has no name.** The label needs the three text command natives (`BeginTextCommandSetBlipName`, `AddTextComponentSubstringPlayerName`, `EndTextCommandSetBlipName`).
- **Wrong checkpoint shape.** Type ids moved in build 2189. On an older game build, types can look different.

## Limitations

- Previews are pictures, not live renders. Colour and size in game can look a little different.
- Sprite, marker and checkpoint pictures load from the FiveM docs site. If one fails, an icon is shown instead.
- Everything else runs in your browser.

## Related tools

- [Interactive Map](/docs/tools/interactive-map)
- [Text Colors](/docs/tools/text-colors)
- [Controls Reference](/docs/tools/controls-reference)
- [Scaleform Reference](/docs/tools/scaleform-reference)

_Last updated: 2026-09-22_

---

## Weapon Stats & Components

URL: https://fivemad.com/docs/tools/weapon-stats

Look up any GTA V weapon: hashes, group, ammo type, max ammo, damage type, flags, every component, livery and tint, plus a Lua loadout snippet.

Weapon Stats & Components is a searchable list of every GTA V weapon (184 entries, 23 of them vehicle weapons) with its hashes, ammo type, max ammo, flags, attachments and tints. Tick attachments and pick a tint, and it writes the Lua to give that exact loadout.

## What it is for

Giving a weapon with the right attachments means knowing names like `COMPONENT_AT_AR_SUPP` and which tint indices exist for that gun. Shops, loadout menus, armoury scripts and admin tools all need these. This page puts every weapon's components and tints next to each other, with copyable hashes for when you have to decode a value from an event or a database.

## Quick start

1. Type in the search box, for example `carbine`, `suppressor` or `AMMO_SHOTGUN`.
2. Narrow by group with the chips (**All**, **Pistol**, **Smg**, **Rifle** and so on). Each chip shows a count.
3. Click a weapon row to open it.
4. Tick the components you want and click a tint. The **Lua** block updates as you go.
5. Copy the snippet into a client script.

## Searching

The search box matches the weapon name (`WEAPON_*`), its label, its ammo type, and the names and labels of its components. Several words must all match. It also takes a hash: signed, unsigned or `0x` hex, for both weapons and components. So pasting `-2084633992` (the Carbine Rifle) or a component hash from a log finds the weapon it belongs to.

Vehicle weapons (tank cannons, jet guns) are hidden unless you turn on **Vehicle weapons**. The search, group and vehicle toggle are kept in the URL (`?q=`, `?group=`, `?vehicle=1`), and a search that leaves exactly one weapon opens it automatically, so a link like `/tools/weapon-stats?q=WEAPON_PISTOL` lands on the pistol.

## What a weapon shows

Each row shows the picture, label, `WEAPON_*` name, ammo type, hex hash and component count. Opening it shows:

| Section | Contents |
| --- | --- |
| Description | The in-game description, when there is one. |
| **Hashes** | Spawn name, Signed, Unsigned, Hex and Lua backtick, all click to copy. |
| **Details** | Group, Ammo type, Damage type, Model, DLC, Vehicle weapon. |
| **Max ammo** | Story (Default, Skill > 50, Max skill) and Online (the same plus Bonus). |
| **Components** | Label, component name, hash (hex and signed), type and attach slot. The default component is marked **default**. |
| **Liveries / camos** | Mk II camo components, tick to add them. |
| **Tints** | Every tint index with its label. Click one to put it in the snippet, click again to remove it. |
| **Flags** | The weapon's flags, such as `Automatic`, `TwoHanded`, `CanFreeAim`. |

## Example

With the Carbine Rifle open, the flashlight and suppressor ticked and tint 2 picked:

```lua title="client.lua"
local ped = PlayerPedId()
local weapon = `WEAPON_CARBINERIFLE`
GiveWeaponToPed(ped, weapon, 250, false, true)

GiveWeaponComponentToPed(ped, weapon, `COMPONENT_AT_AR_FLSH`) -- Flashlight
GiveWeaponComponentToPed(ped, weapon, `COMPONENT_AT_AR_SUPP`) -- Suppressor

SetPedWeaponTintIndex(ped, weapon, 2) -- Gold tint
```

The ammo amount is the weapon's Online default max ammo (250 when unknown). Nothing ticked means the component and tint lines are shown commented out as a hint.

Checking what the player is holding, against a hash from this page:

```lua
local ped = PlayerPedId()
if GetSelectedPedWeapon(ped) == `WEAPON_CARBINERIFLE`
    and HasPedGotWeaponComponent(ped, `WEAPON_CARBINERIFLE`, `COMPONENT_AT_AR_SUPP`) then
    print("Suppressed carbine")
end
```

## Tints

Regular weapons have 8 tints, 0 to 7 (Black, Green, Gold, Pink, Army, LSPD, Orange, Platinum). Mk II weapons use their own longer list, for example 33 tints on the Pistol Mk II.

> [!WARNING]
> Tint indices are not shared between normal and Mk II weapons. An index that does not exist for that weapon does nothing, so always use the list shown for the weapon you give.

## Tips

- Only one component per slot applies: giving an extended clip replaces the default clip.
- Mk II camos are components too, give them with `GiveWeaponComponentToPed` like any attachment.
- Components with no label in the list exist in the game files but have no display name, such as rail covers.

## Limitations

The page does not show damage, fire rate, accuracy or range. Those bars on the weapon wheel are HUD values, not raw `weapons.meta` values, so they are left out rather than guessed. For real per-shot damage, read `Damage` in the weapon's `weapons.meta`, or change it at runtime with `SetWeaponDamageModifier`.

Data comes from [DurtyFree/gta-v-data-dumps](https://github.com/DurtyFree/gta-v-data-dumps), images from the FiveM docs.

## Related tools

- [Weapons Meta Editor](/docs/tools/weapons-meta-editor)
- [joaat Hash Calculator](/docs/tools/hash-calculator)
- [Model & Hash Browser](/docs/tools/model-hash-browser)
- [Game Damage Events](/docs/tools/damage-events)

_Last updated: 2026-09-22_

---

## Objects / Props List

URL: https://fivemad.com/docs/tools/objects-list

Find any GTA V prop by name, tag or hash, check it in 3D with its real size, and copy the model name, hashes and a CreateObject snippet.

The Objects / Props List is a searchable catalogue of more than 30,000 GTA V props. Most have a picture, a readable label, a category, tags and their real size in metres, and almost all of them open as a 3D model you can turn around. Pick one and copy its name, its hash or a ready `CreateObject` snippet.

## What it is for

- Finding the right prop for a script or a ymap without guessing names: "office chair", "traffic cone", "atm".
- Checking the size of a prop before you place it, so the table fits in the room.
- Turning a hash from `GetEntityModel` or a log back into a model name.
- Getting the hash of a custom or addon prop name that is not in the base game.

## Quick start

1. Type part of a name, label or tag in the search box (`bench`, `cone`, `chair office`).
2. Narrow it down with a category chip, or tick **Only props with a picture**.
3. Click a prop. It opens in the **Prop** panel on the right (below the list on phones).
4. Look at it in **3D** or as a **Picture**, check the **Size**.
5. Copy the name, a hash, or the Lua snippet under it.

## Search

- Several words narrow the search: `chair office` finds props that have both words in their name, label, category or tags.
- Quotes and backticks are ignored, so you can paste `` `prop_bench_01a` `` from a script.
- Paste a hash to find its model. Signed or unsigned decimal (`1805980844`) and hex (`0x6BA514AC`) both work. The line above the results says **Hash matches prop_bench_01a**, or that no prop in the list has that hash (then it is probably an MLO piece, a map model or an addon).
- Type a single name that is not in the list and a card shows its signed and hex hash anyway. Handy for addon props.

The counter shows how many props match. Very broad searches keep the first 5,000 matches; refine the search to see the rest.

## Filters and views

| Control | What it does |
| --- | --- |
| Category chips | The 7 biggest categories, with counts. **All** clears the filter. |
| **More categories...** | The rest of the categories in a menu. |
| **Only props with a picture** | Hides entries that only have a name. |
| Grid / list buttons | **Grid** shows picture cards (60 per page). **List** shows compact rows with the **Signed** and **Hex** hash in columns (100 per page), click any of them to copy. |

Search, category, view, the picture filter and the selected prop are kept in the page URL, so a link opens the same result.

## The Prop panel

| Part | What it shows |
| --- | --- |
| Preview | The prop in **3D** when a model is available (the default), or its **Picture**. The **3D** / **Picture** switch in the corner changes it. |
| Label and name | The readable label and the model name (click to copy). |
| Category chip and tags | Click the category chip to filter the list by it. |
| **Size** | Width × depth × height in metres. |
| **Signed** / **Hex** | The model hash, click to copy. |
| **Needs game build** | Shown when the prop only exists from a certain game build. Set `sv_enforceGameBuild` to at least that number. |
| Lua snippet | Spawns the prop in front of the player. |

### 3D preview controls

| Input | Action |
| --- | --- |
| Drag | Turn the model |
| Mouse wheel | Zoom |
| Arrow keys (with the preview focused) | Turn |
| <kbd>+</kbd> / <kbd>-</kbd> | Zoom |
| <kbd>0</kbd> or <kbd>Home</kbd> | Reset the view |
| Reset button (bottom right) | Reset the view |

The model turns slowly on its own until you touch it (not when your system asks for reduced motion). The size in metres is shown in the bottom left corner. The 3D models are lighter than the game's, so small details and textures are simpler. If a prop has no 3D model, or your browser has no WebGL, the picture is shown instead.

## Spawning a prop

The snippet in the panel follows the prop you picked:

```lua
local model = `prop_bench_01a`
RequestModel(model)
while not HasModelLoaded(model) do Wait(0) end

local ped = PlayerPedId()
local coords = GetOffsetFromEntityInWorldCoords(ped, 0.0, 1.5, 0.0)
local obj = CreateObject(model, coords.x, coords.y, coords.z, true, false, false)
PlaceObjectOnGroundProperly(obj)
FreezeEntityPosition(obj, true)
SetModelAsNoLongerNeeded(model)
```

To place many props permanently, use the [YMAP Builder](/tools/ymap-builder) instead: it streams them with the map, with no script running.

Comparing a prop you are looking at against a known model:

```lua
if GetEntityModel(entity) == `prop_atm_01` then
    print("That is an ATM")
end
```

## Tips

- Search by what the prop is, not only by its name. Labels and tags cover things like "bench", "barrier" or "plant" even when the model name is cryptic.
- Check **Size** before placing props in an MLO or a tight garage.
- Names ending in `_lod` or `_slod` are distance models, and some map pieces are huge or invisible on their own. Pick the plain name when in doubt.
- `CreateObject` with `true` as the network argument creates a networked object. Use `false` for props only one client needs.

## Common mistakes

- **Prop does not appear.** The model did not load (typo in the name) or the game build is too old. Check **Needs game build**.
- **Prop floats or sinks.** Call `PlaceObjectOnGroundProperly` after creating it, or set the z yourself.
- **Hash search finds nothing.** The model is not a base game prop: MLO parts, map models and addon props are not in the list.
- **Prop falls over.** Freeze it with `FreezeEntityPosition(obj, true)`.

## Limitations

- Base game props only. Addon props are not listed, but typing their name still gives you the hash.
- Not every entry has a picture, a label or a size. Plain name entries still have hashes and the snippet.
- 3D models and pictures are simplified previews, not the in-game look.
- Search and hashing run in your browser.

## Related tools

- [YMAP Builder](/docs/tools/ymap-builder)
- [Model & Hash Browser](/docs/tools/model-hash-browser)
- [joaat Hash Calculator](/docs/tools/hash-calculator)
- [YTYP Creator](/docs/tools/ytyp-creator)

_Last updated: 2026-09-22_

---

## Particle Effects List

URL: https://fivemad.com/docs/tools/particles-list

Search all 2,900+ GTA V particle effects with their ptfx dictionaries and build a working Lua snippet: one-shot, networked or looped.

The Particle Effects List is the full text list of GTA V particle effects: 2,907 effect names in 360 dictionaries (ptfx assets). Search it, pick an effect, choose how you want to spawn it, and copy a Lua snippet that loads the dictionary and starts the effect.

## What it is for

Every particle effect lives inside a dictionary, and you need both names to spawn it. Getting one wrong gives you nothing on screen and no error. This list pairs every effect with its dictionary and writes the loading code for you, so you only decide what the effect should do: fire once, loop on the player, loop at a spot, or show for everyone.

If you want to see what an effect looks like first, many entries have a film icon that opens its video on [Particle videos](/particles).

## Quick start

1. Search for a word (`fire`, `smoke`, `spark`, `water`) or a dictionary name (`core`, `scr_rcbarry2`).
2. Optionally pick a dictionary in the menu next to the search box.
3. Press **Use** on a row. It turns into **Selected** and the snippet updates.
4. Pick a **Mode**, set **Scale** (and **Duration** for looped modes).
5. Copy `ptfx.lua` or press its **Download** button, and test it in game.

## The list

| Column | What it does |
| --- | --- |
| **Effect** | The effect name. Click to copy. A film icon means there is a video preview: click it to watch it on [Particle videos](/particles). |
| **Dictionary** | The ptfx asset it belongs to. Click to copy. |
| **Use** | Loads this effect into the snippet panel. |

The search matches effect names and dictionary names: typing a dictionary name lists all of its effects. The panel title shows how many effects match. Rows load 100 at a time with a button for more.

## Snippet options

| Option | What it does | Default |
| --- | --- | --- |
| **Mode**: **At coord** | One-shot effect at the player's position, only this client sees it. Uses `StartParticleFxNonLoopedAtCoord`. | selected |
| **Mode**: **Networked** | One-shot effect other players also see. Uses `StartNetworkedParticleFxNonLoopedAtCoord`. | |
| **Mode**: **Looped on entity** | Attached to the player ped until stopped. Uses `StartParticleFxLoopedOnEntity`. | |
| **Mode**: **Looped at coord** | Looped effect at a fixed position until stopped. Uses `StartParticleFxLoopedAtCoord`. | |
| **Scale** | Effect size. Any value above 0. | 1.0 |
| **Duration (ms)** | How long a looped effect runs before `StopParticleFxLooped`. Only for looped modes. | 5000 |
| **Networked** | Only in **Looped on entity**: switches to `StartNetworkedParticleFxLoopedOnEntity` so others see it. | off |
| **Wrap in /ptfx command** | Wraps the code in a `/ptfx` command for quick testing. | off |

The panel starts with `core` / `ent_sht_steam` selected.

## Examples

**At coord**, the default:

```lua title="ptfx.lua"
CreateThread(function()
    local dict, name = "core", "ent_sht_steam"

    RequestNamedPtfxAsset(dict)
    while not HasNamedPtfxAssetLoaded(dict) do Wait(0) end

    local coords = GetEntityCoords(PlayerPedId())
    UseParticleFxAsset(dict)
    StartParticleFxNonLoopedAtCoord(name, coords.x, coords.y, coords.z, 0.0, 0.0, 0.0, 1.0, false, false, false)
    RemoveNamedPtfxAsset(dict)
end)
```

**Looped at coord** with **Wrap in /ptfx command**:

```lua title="ptfx.lua"
RegisterCommand("ptfx", function()
    CreateThread(function()
        local dict, name = "core", "ent_sht_steam"

        RequestNamedPtfxAsset(dict)
        while not HasNamedPtfxAssetLoaded(dict) do Wait(0) end

        local coords = GetEntityCoords(PlayerPedId())
        UseParticleFxAsset(dict)
        local fx = StartParticleFxLoopedAtCoord(name, coords.x, coords.y, coords.z, 0.0, 0.0, 0.0, 1.0, false, false, false, false)

        Wait(5000)
        StopParticleFxLooped(fx, false)
        RemoveNamedPtfxAsset(dict)
    end)
end, false)
```

**Looped on entity** keeps a handle so you can stop it:

```lua
UseParticleFxAsset(dict)
-- offset xyz, rotation xyz, scale, axis flip x/y/z
local fx = StartParticleFxLoopedOnEntity(name, PlayerPedId(), 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, false, false, false)
```

## How to load an effect

The order matters:

1. `RequestNamedPtfxAsset(dict)` and wait for `HasNamedPtfxAssetLoaded(dict)`.
2. `UseParticleFxAsset(dict)` right before the start call. It only applies to the next `Start*ParticleFx*` call, so call it again before each one.
3. Start the effect with the native that fits (see **Mode** above).
4. Looped effects return a handle: stop them with `StopParticleFxLooped(handle, false)`.
5. `RemoveNamedPtfxAsset(dict)` when you no longer need the dictionary.

For looped effects you can also change colour and alpha with `SetParticleFxLoopedColour` and `SetParticleFxLoopedAlpha`, but only effects made with tintable colours react.

## Common mistakes

- **Nothing shows up.** Looped and one-shot effects are not interchangeable. Most names with `_loop`, `ent_amb_` or `_trail` are looped: switch the mode and try again.
- **Forgot `UseParticleFxAsset`.** Without it right before the start call, the game looks in the wrong dictionary.
- **Effect never stops.** You dropped the handle of a looped effect. Keep it and call `StopParticleFxLooped`.
- **Other players cannot see it.** Use a networked mode.
- **Scale does nothing.** Some effects ignore scale or only change part of the effect.

> [!TIP]
> Test with **Wrap in /ptfx command** on, type `/ptfx` in game, and try both modes. Once it looks right, turn the wrapper off and paste the code where you need it.

## Limitations

- Names and dictionaries only. For previews, use [Particle videos](/particles), which has clips for most effects.
- The snippet always spawns at or on the player. Change the coordinates or entity for your use.
- Everything runs in your browser.

## Related tools

- [Particle videos](/docs/tools/particle-videos)
- [Sound Browser](/docs/tools/sound-browser)
- [Objects / Props List](/docs/tools/objects-list)

_Last updated: 2026-09-22_

---

## Particle videos

URL: https://fivemad.com/docs/tools/particle-videos

Watch video previews of 2,300+ GTA V particle effects, filter by dictionary, and copy a ready FiveM Lua snippet for the effect you like.

Particle videos lets you see what a GTA V particle effect looks like before you put it in a script. It has 2,317 effects from 278 dictionaries, and 2,312 of them have a video clip recorded in game. Hover a card to play it, click it for the names and a Lua snippet.

## What it is for

Effect names like `scr_xm_orbital_blast` or `ent_amb_fbi_door_smoke` tell you little. Testing each one in game means a restart per try. Here you scroll through a dictionary, watch the clips, and only take the one that fits into your script.

For the complete text list (2,907 effects, including those without a clip) use the [Particle Effects List](/tools/particles-list). Rows there that have a clip show a film icon linking back here.

## Quick start

1. Open [Particle videos](/particles).
2. Search for a word (`fire`, `explosion`, `water`, `smoke`) or pick a dictionary on the left.
3. Hover a card to play its clip. Turn on **Autoplay** to play every clip on screen as you scroll.
4. Click a card to open it.
5. In the window, pick a snippet mode, set the scale and copy the code.

## Browsing

| Control | What it does |
| --- | --- |
| Search box | Matches effect and dictionary names. Several words narrow the search. `#120` or `120` jumps to effect number 120. |
| Dictionary list (left, desktop) | Every dictionary with its effect count. Filter the list with the box on top. Click a dictionary again to clear it. **All dictionaries** shows everything. |
| Dictionary menu (phones and tablets) | Same as the list, as a menu next to the search box. |
| **Autoplay** | Off: a clip plays while you hover its card. On: every card on screen plays. Remembered in your browser. |
| **Clear filters** | Resets the search and the dictionary. |
| **Show more** | Cards load 48 at a time. |

Each card shows the effect number (`#id`), the effect name, its dictionary and a copy button for the name. Effects without a clip say **No preview**.

The search, dictionary and open effect are kept in the page URL (`/particles?q=fire&dict=core&fx=120`), so you can send someone a link to an exact effect.

## The effect window

| Part | What it does |
| --- | --- |
| Video | Plays the clip in a loop, with player controls. |
| **Effect**, **Dictionary**, **Both** | Copy the effect name, the dictionary, or both as `dict:effect`. |
| **Snippet** tabs | **At coords**, **On entity** or **Networked**. |
| **Scale** | Slider from 0.1 to 5. |
| Code block | The Lua snippet for the chosen mode and scale. |
| Arrows / counter | Previous and next effect in the current results (for example `3 / 48`). |

Keyboard: <kbd>Left</kbd> and <kbd>Right</kbd> go to the previous or next effect, <kbd>Esc</kbd> closes the window. Clicking outside also closes it.

## Snippet modes

| Mode | Native | Use it for |
| --- | --- | --- |
| **At coords** | `StartParticleFxNonLoopedAtCoord` | One-shot effect at the player's position, only this client sees it. |
| **On entity** | `StartParticleFxLoopedOnEntity` | Looped effect attached to the player, stopped after 5 seconds. |
| **Networked** | `StartNetworkedParticleFxNonLoopedAtCoord` | One-shot effect every nearby player sees. |

**At coords** for `core` / `ent_sht_steam` at scale 1:

```lua
local dict, name = 'core', 'ent_sht_steam'

RequestNamedPtfxAsset(dict)
while not HasNamedPtfxAssetLoaded(dict) do Wait(0) end
UseParticleFxAsset(dict)

-- One-shot effect at the player's position (only this client sees it).
local coords = GetEntityCoords(PlayerPedId())
StartParticleFxNonLoopedAtCoord(name, coords.x, coords.y, coords.z, 0.0, 0.0, 0.0, 1.00, false, false, false)
RemoveNamedPtfxAsset(dict)
```

**On entity**:

```lua
local dict, name = 'core', 'ent_sht_steam'

RequestNamedPtfxAsset(dict)
while not HasNamedPtfxAssetLoaded(dict) do Wait(0) end
UseParticleFxAsset(dict)

-- Looped effect attached to the player. Keep the handle to stop it later.
local ped = PlayerPedId()
local handle = StartParticleFxLoopedOnEntity(name, ped, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.00, false, false, false)

Wait(5000)
StopParticleFxLooped(handle, false)
RemoveNamedPtfxAsset(dict)
```

The snippet runs its `Wait` directly, so put it inside a `CreateThread` or a command handler. For a looped effect at a fixed spot (`StartParticleFxLoopedAtCoord`) or a custom duration, build the snippet in the [Particle Effects List](/tools/particles-list), which has those options.

## Tips

- Turn on **Autoplay** and pick a dictionary to skim through it quickly. With a slow connection, leave it off and hover instead.
- If the effect looks right in the clip but nothing shows in game, you probably used the wrong mode. Clips do not tell you whether an effect is looped: most names with `_loop`, `ent_amb_` or `_trail` are.
- Effect and dictionary names are the same in FiveM, alt:V and RageMP, so names you find here work in any of them.

## Limitations

- 5 effects in the list have no clip.
- Clips show the effect at its default scale and colour. Your scale and any colour changes will look different.
- The video previews were originally recorded for the alt:V ParticleDB.

## Related tools

- [Particle Effects List](/docs/tools/particles-list)
- [Sound Browser](/docs/tools/sound-browser)

_Last updated: 2026-09-22_

---

## Sound Browser

URL: https://fivemad.com/docs/tools/sound-browser

Search GTA V sound names and sound sets, listen to them in the browser, and copy a working PlaySoundFrontend, PlaySoundFromCoord or PlaySoundFromEntity call.

The Sound Browser lists 2,179 known GTA V script sounds across 498 sound sets. 1,353 of them have a preview you can play right in the page. Pick one, hear it, and copy a Lua call that plays it in FiveM.

## What it is for

Finding the right beep for a menu, a checkpoint or a hacking minigame usually means guessing names in game and restarting. Here you can listen through dozens of candidates in a minute, then copy the exact name and set, already wrapped in the native you need.

## Quick start

1. Type part of a name or set in the search box (`beep`, `checkpoint`, `HUD_FRONTEND`).
2. Click a row to select it and hear it. The round button on each row plays or stops without moving the selection.
3. Use <kbd>↑</kbd> and <kbd>↓</kbd> to step through the list and <kbd>Space</kbd> to play or stop. While something is playing, stepping with the arrows plays the next sound too.
4. In the detail panel, choose a snippet tab and copy the code.

## Filters and list

| Control | What it does |
| --- | --- |
| Search box | Matches sound name and set name. Several words must all match. |
| Sound set list (left side on wide screens, a dropdown on smaller ones) | Limits the list to one set. Each set shows its count. **No set (AudioRef 0)** holds names that play without a set. The side list has its own filter box. |
| **Only with preview** | Hides sounds that have no clip. |
| Volume slider and mute button | Preview volume. |
| **Loop** | Repeats the preview. |
| **Clear filters** | Resets search, set and the preview toggle. |

The list shows 120 rows at first, **Show more** adds more. Each row has **Name** and **Set** copy buttons, and icons for sounds that are one of several random variations (shuffle) or that loop in game (repeat). Sounds with no clip show a crossed speaker, and generated ones show "synth" in place of a duration.

The search, set and selected sound are kept in the URL (`?q=`, `?set=`, `?s=`), so you can send someone a link to the exact sound you mean. On phones and tablets, the info button on a row opens the details in a drawer.

## Detail panel

The panel shows the name and set (click to copy), the clip length, and notes about the preview when they apply:

- One of several variations: the game picks one at random each time.
- Partly synthesized: the preview has only the recorded layers.
- Looping: in game it keeps playing until your script stops it.
- Streamed from disk: it can start a moment late the first time.
- Several recorded layers mixed together, as the game plays them.

**Same name elsewhere** lists up to 6 other sets that have a sound with the same name, so you can compare them.

### Snippet tabs

| Tab | Native used | Notes |
| --- | --- | --- |
| **Frontend** | `PlaySoundFrontend(-1, ...)` | 2D, fire and forget. For looping sounds it tells you to use the Sound ID tab, since id -1 cannot be stopped. |
| **Sound ID** | `GetSoundId` + `PlaySoundFrontend` | Stops and releases the id in a thread. |
| **Coords** | `PlaySoundFromCoord` | Plays at the player's position. |
| **Entity** | `PlaySoundFromEntity` | Plays on the player ped, or swap in a vehicle or object. |

When the sound's waves are in a bank that is not always loaded, the panel shows the **Wave bank** and every snippet loads it first with `RequestScriptAudioBank` and releases it at the end.

## Examples

A one-shot menu sound:

```lua
PlaySoundFrontend(-1, "SELECT", "HUD_FRONTEND_DEFAULT_SOUNDSET", true)
```

A sound you need to stop, in the style of the **Entity** tab:

```lua title="client.lua"
local soundId = GetSoundId()
PlaySoundFromEntity(soundId, "Beep_Red", PlayerPedId(), "DLC_HEIST_HACKING_SNAKE_SOUNDS", false, 0)

CreateThread(function()
    local stopAt = GetGameTimer() + 10000
    while not HasSoundFinished(soundId) and GetGameTimer() < stopAt do
        Wait(100)
    end
    StopSound(soundId)
    ReleaseSoundId(soundId)
end)
```

> [!IMPORTANT]
> Always call `ReleaseSoundId` when you are done with an id from `GetSoundId`. The game has a small pool of sound ids, and leaking them breaks audio for every script on the client.

## When a sound is silent in game

- DLC sound sets only exist when the server runs that game build. Set `sv_enforceGameBuild` in `server.cfg`.
- If the panel shows a wave bank, keep the `RequestScriptAudioBank` part of the snippet.
- Streamed sounds can start late the first time they play.
- Names under **No set (AudioRef 0)** are passed with `0` as the set, as the snippets do.

## Limitations

- Some sounds have no preview. Many HUD beeps are generated live by the game's synthesizer and have no recording, and some names could not be matched to game data (newer DLC, renamed sets, or sets built at run time).
- For random-variation sounds you hear one of the variations.
- Preview levels are evened out so you can compare clips. In game, volume also depends on the sound's category, distance and the player's audio settings.

Sound names and sets come from [mikigoalie/gta_sound_tester](https://github.com/mikigoalie/gta_sound_tester), originally collected by PlebMasters.

## Related tools

- [Native Audio Builder](/docs/tools/native-audio-builder)
- [Controls Reference](/docs/tools/controls-reference)
- [Scaleform Functions](/docs/tools/scaleform-reference)
- [Particle Effects List](/docs/tools/particles-list)

_Last updated: 2026-09-22_

---

## Controls Reference

URL: https://fivemad.com/docs/tools/controls-reference

Find any GTA V control index by number, INPUT_ name or key, press a real key to see every control on it, and copy detect, disable or RegisterKeyMapping code.

The Controls Reference lists all 361 GTA V controls (index 0 to 360) with their `INPUT_` name, default keyboard key and default gamepad button. Press a key on your keyboard or controller to see every control bound to it, then copy a snippet to detect it, disable it, or replace it with your own key mapping.

## What it is for

`IsControlJustPressed(0, 51)` means nothing until you know 51 is `INPUT_CONTEXT` on <kbd>E</kbd>. And <kbd>E</kbd> is also `INPUT_PICKUP`, `INPUT_TALK`, `INPUT_VEH_HORN` and more, depending on what the player is doing. This page answers "what index is that key" and "what else uses this key" before you pick one for your script.

## Quick start

1. Search by index (`51`), name (`CONTEXT`, `veh exit`) or key (`E`, `LEFT SHIFT`). Searching for a single letter or two looks up the key, not names.
2. Or click **Press a key to find it** and press the real key. Click **Stop listening** when done.
3. Click a row. The detail panel (right side on desktop, inline on phones) shows the bindings and snippets. Before you click anything it shows control 51.
4. Pick the **Input group**, a snippet tab, and copy the code.

## Filters

| Control | What it does |
| --- | --- |
| Search box | Index, `INPUT_` name, name words or key. Exact index and key matches rank first. |
| Group dropdown | On foot, Camera, Weapons, Melee, Vehicle, Aircraft, Submarine, Bicycle, Parachute, Phone, Frontend, Cursor & map, Script, Multiplayer, Replay editor, Creator. Each shows a count. |
| Device chips | **All**, **Keyboard / mouse** (has a keyboard default), **Gamepad only**, **No default**. |
| **Copy link** | Copies a link to the exact view. |

The list shows 80 rows at a time with a button to show more. Click the index or name to copy it, click a key chip to filter the list by that key.

## Key finder

The **Key finder** panel has a **Keyboard** and a **Gamepad** tab. Each key on the map shows how many controls use it (within the current group). Click a key to filter the list, and **Clear key** removes the filter.

With listening on:

- Any key press on the keyboard selects that key.
- A box appears where you can left click, right click, middle click or scroll to pick mouse buttons and the wheel.
- On the **Gamepad** tab, pressing a controller button or pushing a stick picks it. Browsers only see a controller after you press something on it, and controllers without the standard mapping may pick the wrong button.

## Detail panel

Shows the name, index, group, whether it is an axis, the keyboard and gamepad bindings, and the raw text from the FiveM docs.

**Input group (first argument)** switches the snippets between:

| Value | Name | Use it for |
| --- | --- | --- |
| `0` | PLAYER_CONTROL | Almost everything: on foot, driving, weapons. |
| `1` | CAMERA_CONTROL | Camera inputs, rarely needed. |
| `2` | FRONTEND_CONTROL | Menus and the pause screen. Still works while a frontend menu is open. |

### Snippet tabs

| Tab | What you get | File name |
| --- | --- | --- |
| **Detect** | A `Wait(0)` loop with `IsControlJustPressed`, `IsControlPressed` or `IsControlJustReleased` (buttons to switch). For axis controls the tab is called **Read** and uses `GetControlNormal`. | `control.lua` |
| **Disable** | `DisableControlAction` every frame plus an `IsDisabledControlJustPressed` check. | `disable_control.lua` |
| **Key mapping** | `+` and `-` commands with `RegisterKeyMapping`, using the control's default key. Set a **Command prefix** (default `myres`) and a **Settings label**. | `keymapping.lua` |

## Examples

Detecting <kbd>E</kbd> near something:

```lua title="control.lua"
CreateThread(function()
    while true do
        Wait(0)
        if IsControlJustPressed(0, 51) then -- INPUT_CONTEXT (E, pad DPAD RIGHT)
            -- your code here
        end
    end
end)
```

Blocking attacks in a safe zone:

```lua title="disable_control.lua"
CreateThread(function()
    while true do
        Wait(0)
        DisableControlAction(0, 24, true) -- INPUT_ATTACK
        if IsDisabledControlJustPressed(0, 24) then
            -- player tried to shoot
        end
    end
end)
```

A rebindable key for your own feature:

```lua title="keymapping.lua"
RegisterCommand("+myres_context", function()
    -- key pressed
end, false)

RegisterCommand("-myres_context", function()
    -- key released
end, false)

RegisterKeyMapping("+myres_context", "Open my menu", "keyboard", "E")
```

## Control index or RegisterKeyMapping?

- **Control indexes** are the game's own actions. Use them to react to or block vanilla input. If a player rebinds a GTA action, the index follows their key. They need a `Wait(0)` loop and you cannot give your feature its own key.
- **RegisterKeyMapping** adds an entry under Settings, Key Bindings, FiveM. Each player can change it, it is saved on their machine, and it needs no loop. Use it for anything your resource adds: menus, radios, emotes.

> [!WARNING]
> The default key of a mapping only applies the first time a player sees it. Changing it in your script later does not move existing players, so choose it carefully.

## Tips

- `DisableControlAction` lasts one frame. Call it every tick.
- While a control is disabled, `IsControlJustPressed` returns false. Use `IsDisabledControlJustPressed` or `IsDisabledControlPressed`.
- `DisableAllControlActions(0)` blocks the whole group; re-enable what you need with `EnableControlAction`.
- If a check does nothing while a pause menu or frontend is open, try input group `2`.

## Shareable links

The URL follows the page: `?q=` for the search, `?key=` for the selected key (`?key=E`, `?key=LSHIFT`, `?key=pad:DPAD RIGHT`) and `?id=` for the open control.

## Limitations

Keyboard keys are the QWERTY defaults and gamepad buttons use Xbox names, as the FiveM docs list them. A player's own bindings may differ. Everything runs in the browser, and key presses are only read while listening is on.

## Related tools

- [Draw Text Colors](/docs/tools/text-colors) (for `~INPUT_CONTEXT~` prompts)
- [Warning Screen Buttons](/docs/tools/warning-buttons)
- [Scaleform Functions](/docs/tools/scaleform-reference)
- [Sound Browser](/docs/tools/sound-browser)

_Last updated: 2026-09-22_

---

## Scaleform Functions

URL: https://fivemad.com/docs/tools/scaleform-reference

Search 471 GTA V scaleform movies and 4,847 functions, see their parameter names, and build a ready Lua call with BeginScaleformMovieMethod and a draw loop.

Scaleform Functions is a reference of GTA V scaleform movies and the functions you can call on them, with their parameter names. Pick a function, fill the parameters, and copy a Lua snippet that loads the movie, calls it and draws it.

## What it is for

Scaleform movies are the Flash UI files GTA V uses for big "mission passed" shards, instructional buttons, phones, computer screens, the minimap and more. Using one from a script means knowing the movie name, the function name and the order of its arguments. This page lists all of that and writes the boilerplate so you can try a message in seconds.

## Quick start

1. The page opens on `MIDSIZED_MESSAGE` with `SHOW_SHARD_MIDSIZED_MESSAGE` selected.
2. Search movie names in the **Movies** tab, or switch to **Functions** to search function names across every movie (type at least 2 characters, for example `SET_TITLE`).
3. Click a movie, then a function in its list.
4. In the **Snippet builder**, check the type of each parameter and type a value.
5. Copy `scaleform.lua`.

## Browsing

| Control | What it does |
| --- | --- |
| **Movies** / **Functions** tabs | Search by movie name, or by function name across all movies. The Functions search also matches a parameter name exactly. |
| Category chips | **All**, frontend, generic, generic_2, heist_mp, minigames, minimap, platform_pc, web. |
| **UPPERCASE functions only** | Hides lowercase functions, which are mostly internal. |
| **Filter functions** | Appears on a movie with more than 8 functions. |

Each movie shows its category, its name (click to copy) and the function count. Functions are listed with their parameter names, for example `SHOW_SHARD_MIDSIZED_MESSAGE(bigText, msgText, colID, useDarkerShard, useCondensedShard)`. The selected movie and function are kept in the URL (`?movie=` and `?fn=`), so you can link someone straight to a function.

## Snippet builder

For every parameter you get a type dropdown and a value field. The type is pre-filled from the parameter name (`useDarkerShard` becomes a bool, `colID` an int, `bigText` a string). Change it if the movie expects something else.

| Type | Native written |
| --- | --- |
| int | `ScaleformMovieMethodAddParamInt` |
| float | `ScaleformMovieMethodAddParamFloat` |
| bool | `ScaleformMovieMethodAddParamBool` |
| string (TextureNameString) | `ScaleformMovieMethodAddParamTextureNameString` |
| string (PlayerNameString) | `ScaleformMovieMethodAddParamPlayerNameString` |
| text (BeginTextCommand...) | `BeginTextCommandScaleformString("STRING")`, `AddTextComponentSubstringPlayerName`, `EndTextCommandScaleformString` |

| Option | What it does | Default |
| --- | --- | --- |
| **Draw fullscreen** | Adds a `DrawScaleformMovieFullscreen` loop after the call. | on |
| **Duration (seconds)** | How long to draw before `SetScaleformMovieAsNoLongerNeeded`. `0` draws forever. | 5 |

Use the text type when you want `~r~` style colour codes or long strings, since the plain string natives do not format.

## Example

What the builder writes for a green midsized shard:

```lua title="scaleform.lua"
local function LoadScaleform(name)
    local handle = RequestScaleformMovie(name)
    local timeout = GetGameTimer() + 5000
    while not HasScaleformMovieLoaded(handle) do
        if GetGameTimer() > timeout then return nil end
        Wait(0)
    end
    return handle
end

CreateThread(function()
    local scaleform = LoadScaleform("MIDSIZED_MESSAGE")
    if not scaleform then return print("Could not load MIDSIZED_MESSAGE") end

    BeginScaleformMovieMethod(scaleform, "SHOW_SHARD_MIDSIZED_MESSAGE")
    ScaleformMovieMethodAddParamTextureNameString("MISSION PASSED") -- bigText
    ScaleformMovieMethodAddParamTextureNameString("You delivered the car") -- msgText
    ScaleformMovieMethodAddParamInt(2) -- colID
    ScaleformMovieMethodAddParamBool(false) -- useDarkerShard
    ScaleformMovieMethodAddParamBool(false) -- useCondensedShard
    EndScaleformMovieMethod()

    local untilTime = GetGameTimer() + 5000
    while GetGameTimer() < untilTime do
        DrawScaleformMovieFullscreen(scaleform, 255, 255, 255, 255, 0)
        Wait(0)
    end
    SetScaleformMovieAsNoLongerNeeded(scaleform)
end)
```

## Tips

- A scaleform only shows while you draw it every frame.
- Call functions after the movie has loaded, or they are dropped.
- Release a movie you no longer need with `SetScaleformMovieAsNoLongerNeeded`.
- `colID` style parameters take HUD colour ids. The [Draw Text Colors](/tools/text-colors) page lists the common HUD colours by name.

> [!WARNING]
> Movies in the **frontend** category (pause menu and similar) usually cannot be drawn with `DrawScaleformMovie`. They are driven through `BeginScaleformMovieMethodOnFrontend` and friends, and are mostly undocumented. The tool shows a warning on those movies.

## Limitations

- Not every listed function does something in game. UPPERCASE functions are the movie's public API and usually work; lowercase ones are internal but sometimes work too.
- Only parameter names are known, not their types or allowed values. Test in game.

Data: Vespura ([tomgrobbe.com](https://tomgrobbe.com/fivem/scaleform/)).

## Related tools

- [Draw Text Colors](/docs/tools/text-colors)
- [Warning Screen Buttons](/docs/tools/warning-buttons)
- [Controls Reference](/docs/tools/controls-reference)
- [Sound Browser](/docs/tools/sound-browser)

_Last updated: 2026-09-22_

---

## Player Stats List

URL: https://fivemad.com/docs/tools/player-stats

Search 3,025 GTA V stat names by name or description, see their type, scope and hash, and copy the right StatGetInt, StatSetInt or StatSetFloat call.

The Player Stats List is a searchable list of 3,025 known GTA V stat names with their data type, whether they are per character or global, and their hash. Pick one and it writes the Lua to read and set it with the native that matches its type.

## What it is for

The most common use on a FiveM server is the skill bars: stamina, strength, lung capacity, shooting, driving and flying. They affect how the player ped actually behaves, and you set them through stats. Beyond those, the list helps when you find a stat name in a script and need its type or hash, or when you want to know whether a stat needs the `MP0_` prefix.

## Quick start

1. Click one of the **Common ones** chips (`STAMINA`, `STRENGTH`, `LUNG_CAPACITY`, `SHOOTING_ABILITY`, `WHEELIE_ABILITY`, `FLYING_ABILITY`, `STEALTH_ABILITY`), or search the list.
2. Pick the **Prefix**: **MP0_** (first character, the default), **MP1_** or **None**.
3. Type the **Value to set**.
4. Copy `stats.lua`.

## Filters

| Control | What it does |
| --- | --- |
| Search box | Matches stat names and descriptions. A leading `MP0_` or `MP1_` in your search is ignored, so pasting a full name works. |
| **Prefix** | The prefix shown and used for per character stats: **MP0_**, **MP1_** or **None**. |
| Type chips | **All types** or one of int, u64, bool, u32, userid, string, s64, float, date, pos, label, packed, each with a count. |
| Scope chips | **All stats**, **Per character (prefixed)**, **Global (no prefix)**. |

The list shows 60 stats at a time. Each row shows the full name (with the prefix greyed out), the description, the type and the hex hash of the full name (click to copy).

## Selected stat

The **Selected stat** panel shows the full name, description, **Type**, **Hash (hex)**, **Hash (signed)**, **Hash (unsigned)** and **Scope**. The hash always matches the prefix you picked, since `MP0_STAMINA` and `MP1_STAMINA` are different stats. If you pick **None** on a per character stat, a warning reminds you that it normally needs a prefix.

**Value to set** is a true / false dropdown for bool stats and a text field for the rest. It is hidden for date, packed and pos stats, which use their own snippet.

## Which native for which type

| Type | Read | Write |
| --- | --- | --- |
| int, u32 | `StatGetInt` | `StatSetInt` |
| s64, u64 | `StatGetInt` (32-bit range) | `StatSetInt`, or `StatSetCurrentPosixTime` for timestamp stats |
| float | `StatGetFloat` | `StatSetFloat` |
| bool | `StatGetBool` | `StatSetBool` |
| string | `StatGetString` | `StatSetString` |
| label | n/a | `StatSetGxtLabel` (a text label key, not free text) |
| userid | `StatGetUserId` | `StatSetUserId` |
| pos | `StatGetPos` | `StatSetPos` (the snippet uses the player's position) |
| date | `StatGetDate` | `StatSetDate` (a 7 int struct, awkward from Lua) |
| packed | `GetPackedStatBoolCode` / `GetPackedStatIntCode` | `SetPackedStatBoolCode` / `SetPackedStatIntCode`, by index not name |

## Examples

What the tool writes for `MP0_STAMINA` with value 100:

```lua title="stats.lua"
local stat = `MP0_STAMINA` -- joaat("MP0_STAMINA")

local ok, value = StatGetInt(stat, -1)
if ok then print("MP0_STAMINA", value) end

-- Last argument = save. On FiveM there is no cloud save, so set it again on every spawn.
StatSetInt(stat, 100, true)
```

Max out every skill bar each time the player spawns:

```lua title="client.lua"
local SKILLS = { "STAMINA", "STRENGTH", "LUNG_CAPACITY", "SHOOTING_ABILITY",
                 "WHEELIE_ABILITY", "FLYING_ABILITY", "STEALTH_ABILITY" }

AddEventHandler("playerSpawned", function()
    for _, name in ipairs(SKILLS) do
        StatSetInt(GetHashKey("MP0_" .. name), 100, true)
    end
end)
```

## Tips

> [!IMPORTANT]
> FiveM has no Rockstar cloud save. Stats live on the client and reset when the game restarts. Store the real values in your own database and set them again on every spawn.

- Most stats only matter to GTA Online's own scripts and do nothing on a FiveM server. The skill stats do work.
- The `save` argument of the setters can stay `true`. It does nothing harmful on FiveM.
- `MPPLY_` stats and other global stats are used without a prefix. Use the **Global (no prefix)** chip to see them.

## Limitations

The list is generated from the game's MP stat definitions and may contain mistakes or stats that no longer exist. Everything runs in your browser.

Data: Vespura ([tomgrobbe.com](https://tomgrobbe.com/fivem/gta-stats/)).

## Related tools

- [joaat Hash Calculator](/docs/tools/hash-calculator)
- [Parachutes & Smoke Trails](/docs/tools/parachutes)
- [Weapon Stats & Components](/docs/tools/weapon-stats)

_Last updated: 2026-09-22_

---

## Parachutes & Smoke Trails

URL: https://fivemad.com/docs/tools/parachutes

Every GTA V parachute canopy tint and smoke trail colour with indices, text labels and RGB values, plus a snippet builder for the parachute natives.

Parachutes & Smoke Trails lists all 14 canopy tints and 8 smoke trail options with their indices, text labels and RGB values. Click a canopy, pick a smoke colour, and copy a snippet that gives the parachute and applies everything to the player.

## What it is for

Skydiving events, BASE jumping jobs, or a store that sells parachute styles all need the tint indices and the natives to apply them. Six of the canopies also need a model swap that is easy to miss. The snippet handles that for you.

## Quick start

1. Click a card under **Canopy tints**. With **Same tint everywhere** on (the default), the main canopy, reserve and pack all follow it.
2. Turn **Smoke trail** on or off and click a colour swatch, or use **Custom** to pick any colour.
3. Copy `parachute.lua` from under the **Snippet builder**.

## Canopy tints

| Index | Name | Label | Model override |
| --- | --- | --- | --- |
| 0 | Rainbow Chute | `PM_TINT0` | |
| 1 | Red Chute | `PM_TINT1` | |
| 2 | Seaside Stripes Chute | `PM_TINT2` | |
| 3 | Widowmaker Chute | `PM_TINT3` | |
| 4 | Patriot Chute | `PM_TINT4` | |
| 5 | Blue Chute | `PM_TINT5` | |
| 6 | Black Chute | `PM_TINT6` | |
| 7 | Hornet Chute | `PM_TINT7` | |
| 8 | Air Force Chute | `PS_CAN_0` | yes |
| 9 | Desert Chute | `PS_CAN_1` | yes |
| 10 | Shadow Chute | `PS_CAN_2` | yes |
| 11 | High Altitude Chute | `PS_CAN_3` | yes |
| 12 | Airborne Chute | `PS_CAN_4` | yes |
| 13 | Sunrise Chute | `PS_CAN_5` | yes |

Each card also shows the description label (`PD_TINT*` or `PSD_CAN_*`), click to copy. Tints 8 to 13 are the San Andreas Flight School canopies and are marked **model override**: they only appear after you swap the canopy model to `pil_p_para_pilot_sp_s`.

## Smoke trail colours

| Name | RGB | Label |
| --- | --- | --- |
| No Smoke Trail | none | `PM_TINT8` |
| Red Smoke Trail | 255, 0, 0 | `PM_TINT9` |
| Orange Smoke Trail | 255, 165, 0 | `PM_TINT10` |
| Yellow Smoke Trail | 255, 255, 0 | `PM_TINT11` |
| Blue Smoke Trail | 0, 0, 255 | `PM_TINT12` |
| Black Smoke Trail | 20, 20, 20 | `PM_TINT13` |
| Crew Smoke Trail | crew colour, pick any RGB | `PM_TINT14` |
| Patriot Smoke Trail | 255, 0, 0 / 255, 255, 255 / 0, 0, 255 | `PM_TINT15` |

Click a swatch in the table to use it in the snippet (it also turns the smoke trail on). Smoke trails are not a tint index: you turn them on and pass any RGB you like. The Patriot trail is three colours, but the native takes one RGB per call, so pick one or cycle them yourself.

## Snippet builder

| Option | What it does | Default |
| --- | --- | --- |
| **Same tint everywhere** | Main, reserve and pack follow the card you click. Changing one of the dropdowns turns it off. | on |
| **Main** / **Reserve** / **Pack** | Tint for each part. | 6 (Black Chute) |
| **Give parachute** | Adds `GiveWeaponToPed` with `gadget_parachute` and `SetPlayerHasReserveParachute`. | on |
| **Smoke trail** | Adds `SetPlayerCanLeaveParachuteSmokeTrail` and the colour. | on, red |

## Example

A Desert Chute (needs the model override) with an orange trail:

```lua title="parachute.lua"
CreateThread(function()
    local player = PlayerId()
    local ped = PlayerPedId()

    GiveWeaponToPed(ped, `gadget_parachute`, 1, false, false)
    SetPlayerHasReserveParachute(player)

    -- tints 8 to 13 only exist on the flight school canopy
    local model = `pil_p_para_pilot_sp_s`
    RequestModel(model)
    while not HasModelLoaded(model) do Wait(0) end
    SetPlayerParachuteModelOverride(player, model)
    SetPlayerReserveParachuteModelOverride(player, model)

    SetPlayerParachuteTintIndex(player, 9) -- Desert Chute
    SetPlayerReserveParachuteTintIndex(player, 9) -- Desert Chute
    SetPlayerParachutePackTintIndex(player, 9) -- Desert Chute

    SetPlayerCanLeaveParachuteSmokeTrail(player, true)
    SetPlayerParachuteSmokeTrailColor(player, 255, 165, 0)
end)
```

## Natives

| Native | What it does |
| --- | --- |
| `SetPlayerParachuteTintIndex(player, tintIndex)` | Canopy tint of the main parachute. |
| `SetPlayerReserveParachuteTintIndex(player, index)` | Canopy tint of the reserve. |
| `SetPlayerParachutePackTintIndex(player, tintIndex)` | Tint of the backpack. |
| `SetPlayerParachuteModelOverride(player, model)` | Swaps the canopy model (needed for 8 to 13). |
| `SetPlayerReserveParachuteModelOverride(player, model)` | Same, for the reserve. |
| `SetPlayerCanLeaveParachuteSmokeTrail(player, enabled)` | Turns the smoke trail on or off. |
| `SetPlayerParachuteSmokeTrailColor(player, r, g, b)` | Smoke colour, 0 to 255 each. |
| `SetPlayerHasReserveParachute(player)` | Gives a reserve chute. |

Click a native name in the tool to copy it.

## Tips

- These natives take the player id (`PlayerId()`), not the ped.
- The labels are text entries. Use `GetLabelText("PM_TINT7")` to show the localised name in a menu.
- Setting an index from 8 to 13 without the model override shows the wrong canopy.

## Limitations

The canopy previews are approximate drawings from the in-game descriptions, not renders. Everything runs in the browser.

Data: Vespura ([vespura.com](https://vespura.com/fivem/parachutes/)).

## Related tools

- [Weapon Stats & Components](/docs/tools/weapon-stats)
- [Player Stats List](/docs/tools/player-stats)
- [Particle Effects List](/docs/tools/particles-list)

_Last updated: 2026-09-22_

---

## Game Damage Events

URL: https://fivemad.com/docs/tools/damage-events

The CEventNetworkEntityDamage payload from gameEventTriggered explained index by index, plus generated clean kill, death and vehicle events for your resource.

Game Damage Events documents the raw `CEventNetworkEntityDamage` payload FiveM hands to scripts, and generates a small resource that turns it into named events like `damage:onPlayerDied` and `damage:onPlayerKilled`. It is for anyone building a kill feed, death screen, bounty system or vehicle damage logic.

## What it is for

FiveM forwards low-level game events to client scripts through `gameEventTriggered`. When a networked entity takes damage, you get `CEventNetworkEntityDamage` with an array of integers and no names. The layout also changed between game builds, which is why many old snippets read the wrong index and silently break. This page tells you which index is which today, and writes the parsing once so every other script can listen to clean events.

## Quick start

1. Open **Raw args** to see the payload layout, or **Event explorer** to see the events the generated code emits.
2. Tick **Include** on the events you want (five are selected by default).
3. Open **Code builder**, set the **Event prefix** and options.
4. Copy each file tab (`client.lua`, `server.lua`, `fxmanifest.lua`) into a new resource, and use `examples.lua` as a starting point for your listeners.

## The raw payload

On game build 2189 and newer, the args are:

| Index | Lua | Name | Type | Status |
| --- | --- | --- | --- | --- |
| 0 | `args[1]` | victim | entity | Reliable |
| 1 | `args[2]` | attacker | entity (-1 or 0 when none) | Reliable |
| 2 | `args[3]` | unknown, likely the damage amount as a raw float | int | Reported |
| 3 | `args[4]` | unknown, added in b2060 | int | Reported |
| 4 | `args[5]` | unknown, added in b2189 | int | Reported |
| 5 | `args[6]` | fatal (1 when it killed or destroyed the victim) | int 0/1 | Reliable |
| 6 | `args[7]` | weaponHash (weapon or cause, such as `WEAPON_RUN_OVER_BY_CAR`, `WEAPON_FALL`) | hash | Reliable |
| 7 | `args[8]` | unknown, non-zero on vehicle collisions | int | Reported |
| 8 | `args[9]` | unknown, non-zero on vehicle collisions | int | Reported |
| 9 | `args[10]` | unknown, 1 on some headshots or collisions | int 0/1 | Varies by build |
| 10 | `args[11]` | read as isMelee or isHeadshot depending on build | int 0/1 | Varies by build |
| 11 | `args[12]` | isMelee or vehicle damage flags (93 tyres, 116 body, 120 windows) | int | Varies by build |
| 12 | `args[13]` | vehicle damage type or hit material | int | Varies by build |

Only victim, attacker, fatal and weapon are safe to rely on. The attacker can be a vehicle when someone was run over.

Before b2060 the layout was two slots shorter: fatal at index 3 and weaponHash at index 4. Older resources still read those and get wrong values on current builds. The **Old layout (before b2060)** panel lists it.

The minimal handler:

```lua
AddEventHandler("gameEventTriggered", function(name, args)
    if name ~= "CEventNetworkEntityDamage" then return end
    local victim, attacker = args[1], args[2]
    local fatal = args[6] == 1
    local weaponHash = args[7]
    print(json.encode(args)) -- dump the rest on your build
end)
```

> [!WARNING]
> The event fires on every client that knows the victim, not only on the victim and the attacker. If ten players are near a fight, all ten get it. Filter on `PlayerPedId()` before you reward a kill.

## Events the generated code emits

All are client events named `<prefix>:<event>`, for example `damage:onPlayerDied`.

| Event | When | Arguments |
| --- | --- | --- |
| `onPlayerDied` | Local player died, any cause. Once per death. | cause, killerServerId, weaponHash, killerEntity |
| `onPlayerKilledByPlayer` | Local player killed by another player (also run over by a player's car). | killerServerId, weaponHash, isMelee, isHeadshot, distance |
| `onPlayerKilledByPed` | Local player killed by an NPC. | killerPed, weaponHash, isMelee |
| `onPlayerKilledByVehicle` | Run over by a vehicle with no player driver. | vehicle, weaponHash |
| `onPlayerKilled` | Local player killed another player (killer side). | victimServerId, weaponHash, isMelee, isHeadshot, distance |
| `onPlayerDamaged` | Local player took damage and survived. Frequent. | attacker, weaponHash, isMelee, attackerServerId |
| `onPedKilledByPlayer` | Local player killed an NPC. | ped, weaponHash, isMelee, isHeadshot |
| `onPedDied` | An NPC died and the local player was not the killer. Every client. | ped, attacker, weaponHash |
| `onVehicleDestroyed` | A vehicle blew up or was wrecked. Every client. | vehicle, attacker, weaponHash, byLocalPlayer |
| `onVehicleDamaged` | A vehicle took damage but survived. Every client, frequent. | vehicle, attacker, weaponHash |
| `onEntityDamaged` | Every raw damage event, untouched, for debugging. | victim, attacker, weaponHash, fatal, args |

`cause` is one of `"player"`, `"ped"`, `"vehicle"`, `"suicide"` or `"environment"`. Selected by default: onPlayerDied, onPlayerKilledByPlayer, onPlayerKilled, onPedKilledByPlayer, onVehicleDestroyed. The **Event explorer** search matches event names, descriptions, groups and argument names, and each card has a ready listener.

In the generated code, melee comes from the weapon group and headshots from `GetPedLastDamageBone` (bone `31086`, the head), not from the unstable slots. Deaths are reported once: shooting a body again does not fire a second death, and deaths that never raised a damage event (fall damage on some builds, `SetEntityHealth(ped, 0)`) are still caught.

## Code builder options

| Option | What it does | Default |
| --- | --- | --- |
| **Events** | Which events to generate. **All** and **None** buttons at the top. | 5 selected |
| **Event prefix** | Prefix for every event name. | `damage` |
| **Debug prints** | Prints every emitted event to the F8 console. | off |
| **Server relay** | Adds `server.lua`: the victim reports its own death, the server checks it and fires `<prefix>:server:playerDied` and `<prefix>:server:playerKilled`. | on |
| **Max kill distance (m)** | Server relay drops kill reports where the killer is further away than this (OneSync). | 1000 |

The server relay checks the payload type and cause, allows one report per player every 3 seconds, makes sure the killer is another connected player, and checks the distance between the two peds.

## Examples

Client side, a kill feed line:

```lua title="killfeed.lua"
AddEventHandler("damage:onPlayerKilled", function(victimServerId, weaponHash, isMelee, isHeadshot, distance)
    local msg = ("You killed %s (%.0fm)%s"):format(GetPlayerName(GetPlayerFromServerId(victimServerId)), distance, isHeadshot and ", headshot" or "")
    print(msg)
end)
```

Server side, with the relay on:

```lua title="server.lua"
AddEventHandler("damage:server:playerDied", function(victim, killer, info)
    print(GetPlayerName(victim), "died", info.cause, killer and GetPlayerName(killer))
end)
```

The manifest the tool writes:

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'
lua54 'yes'

client_script 'client.lua'
server_script 'server.lua'
```

## Limitations

- The server never receives `CEventNetworkEntityDamage` itself. The relay trusts the victim's own report, which is the least abusable direction (a cheater can only lie about their own death), but treat it as a kill feed source, not as proof for bans.
- The unknown slots differ between builds. If you need one, turn on `onEntityDamaged` with **Debug prints** and log the raw table on your server's build.

The idea of named damage events comes from Vespura's [DamageEvents](https://github.com/TomGrobbe/DamageEvents) resource. The Lua here is a separate implementation for current game builds.

## Related tools

- [Weapon Stats & Components](/docs/tools/weapon-stats)
- [joaat Hash Calculator](/docs/tools/hash-calculator)
- [fxmanifest.lua Generator](/docs/tools/fxmanifest-generator)

_Last updated: 2026-09-22_

---

## Animation Browser

URL: https://fivemad.com/docs/tools/animations

Browse every GTA V animation dictionary and clip, search the whole set, watch any of them on a freemode ped and copy ready TaskPlayAnim Lua.

The Animation Browser lists every animation dictionary the game ships and plays them on a freemode ped in your browser, so you can see what a clip does before you put it in a script. It also has a section for synchronised scenes: the pairs of animations that were authored to be played by two peds at the same time.

## The two tabs

| Tab | What it holds |
| --- | --- |
| All animations | Every in-game dictionary and clip in the game, browsable and searchable |
| Synced scenes | Two ped scenes with their props, both peds on one timeline |

## All animations

The first tab is the whole in-game set: 11,273 dictionaries and 97,204 clips, the real names and the real numbers straight out of the game files. You browse it in three steps.

1. Pick a family (heists, ambient and scenarios, movement, vehicles, weapons and combat, nightclub, casino, animals, story mode and the rest). Each one says how many dictionaries and clips it holds.
2. Pick a dictionary. The row shows its clip count and how many of its clips play on a ped.
3. Pick a clip. It starts playing, and you get its length, frames, rate and bone track count plus the Lua.

Search covers all of it. Type two or more letters and every dictionary and clip name is matched at once; words that hit the dictionary name count for every clip in it, so `ornate_bank` gives you the whole Pacific Standard set and `reload pistol` narrows to pistol reloads. Clips that play are listed first.

> [!NOTE]
> Not every clip can run on a ped, and the rows say which and why: `facial or camera` (no body bone moves), `not a ped rig` (it drives a vehicle, a weapon or a prop) and `nothing to watch` (a single pose). Those are still listed with their real facts and their Lua, and the viewer says so instead of showing you the previous animation. Dictionaries for animals are marked too: they only share part of their skeleton with a ped.

The ped follows the dictionary name: a dictionary with `female` in it opens on the female ped, everything else on the male. The **Ped** switch still overrides it.

### Where the heist animations are

The heist dictionaries sit in the catalogue like every other dictionary, under **Heists and robberies**: drilling, cutting, thermal charges, keypads and card swipes, safes, money and gold grabs, carrying, hold ups and crew prep. Typing `drill` finds every drilling clip and `ornate_bank` the whole Pacific Standard set.

## Watching a clip

1. Pick a clip in the list on the left. It downloads on the spot, usually under 10 KB, and starts playing.
2. Drag to orbit the camera, scroll to zoom, and press **Reset view** to go back to the default framing.
3. Use the bar to scrub through the motion, **Speed** to slow it down, and **Loop** to watch it once instead of over and over.
4. **Ped** switches between the male and the female freemode ped.

> [!NOTE]
> Clips that travel (walking in, stepping away) are held on the spot here so you can see them. In the game they move the ped.

The facts under the viewer are the ones you usually need: how long the clip runs, how many frames it has, its rate and how many bones it actually moves. A clip with very few bone tracks only moves part of the body.

## Getting it into your script

Click the dictionary name or the clip name to copy it. Under that, the Lua panel gives you a working block:

```lua title="client.lua"
local dict = "anim@heists@ornate_bank@grab_cash"
local anim = "grab"

RequestAnimDict(dict)
while not HasAnimDictLoaded(dict) do
    Wait(0)
end

TaskPlayAnim(PlayerPedId(), dict, anim, 8.0, -8.0, -1, 1, 0.0, false, false, false)
RemoveAnimDict(dict)
```

The flag and the duration are filled in from the clip: a clip that reads as a loop (`idle`, `loop`, `base`) gets flag `1` and no time limit, anything else gets flag `0` and its own length in milliseconds. There is a one line upper body version below it, for when the ped should keep walking.

For other flag combinations, the [Animation Flags Calculator](/docs/tools/animation-flags-calculator) builds the number.

## Synced scenes

A synchronised scene plays two animations that were made to fit together, so both peds line up exactly: a handshake, a hug, a mugging, a fistfight, a drug deal. The other tab lists them with their category.

- Both peds play on one timeline, so play, pause and scrub move them together.
- **Ped 1** and **Ped 2** pick the model for each side, and **Swap peds** flips them.
- When a scene animates a prop and we have a model for it, the prop is drawn and animated too. When we cannot draw it, the model name is listed as "needs prop" so you still know what to spawn.
- If the two clips are not the same length, the shorter one holds on its last frame. That is what the game does inside a scene, not a bug in the preview.

The Lua panel writes the whole block for a scene: loading the dictionaries, creating any prop, `NetworkCreateSynchronisedScene` at your ped's position and heading, both peds added to it, and the start call.

```lua title="scene.lua"
local scene = NetworkCreateSynchronisedScene(coords.x, coords.y, coords.z, 0.0, 0.0, heading, 2, false, false, 1065353216, 0, 1.0)
NetworkAddPedToSynchronisedScene(ped1, scene, dict, anim1, 1000.0, -1000.0, 16, 16, 1148846080, 0)
NetworkAddPedToSynchronisedScene(ped2, scene, dict, anim2, 1000.0, -1000.0, 16, 16, 1148846080, 0)
NetworkStartSynchronisedScene(scene)
```

> [!TIP]
> The scene is created at a position and a heading, not at a ped. Put it where you want the pair to stand, then attach both peds; the offsets are baked into the animations.

## Sharing a link

The page keeps your selection in the URL, so you can send someone the exact clip or scene:

- `/tools/animations?d=anim@heists@fleeca_bank@drilling&c=drill_straight_idle`
- `/tools/animations?d=amb@world_human_smoking@male@male_a@base&c=base`
- `/tools/animations?tab=scenes&s=<scene id>`

A `?d=&c=` link opens the browser on that dictionary and that clip.

## Limits

- The viewer needs WebGL. On a browser without it the page says so instead of showing an empty box.
- The list covers the in-game dictionaries (`anim/ingame`). Cutscene animations live in the [Cutscene Browser](/tools/cutscenes).
- A clip that does not move enough of the ped's own bones is not played on one; it is listed with its facts and its Lua and says why.
- Facial clips only move face bones, so there is nothing to watch on a preview ped; they are listed and marked.
- Clips that drive a prop, a vehicle or a weapon instead of a body are listed and marked too. You see prop clips running on the prop in a synced scene.

_Last updated: 2026-09-23_

---

## Cutscene Browser

URL: https://fivemad.com/docs/tools/cutscenes

Look up any GTA V cutscene: the real name for RequestCutscene, its actors, length, camera cuts, subtitles and world position, plus a 3D preview of the exported ones.

The Cutscene Browser lists every cutscene this build of GTA V ships and, for a large part of the list, plays a 3D preview of it. It is the quick way to find the cutscene name a script needs, see who is in it and how long it runs, and check what it actually shows before you wire it up.

## What is in the list

Every cutscene is read out of the game's own cutscene files, so each row carries the real data:

- The cutscene name, exactly the string `RequestCutscene` wants.
- How long it runs and how many camera cuts it makes.
- The ped models that act in it, with the character name where it is obvious.
- The props and vehicles the cutscene places.
- How many subtitle lines it has, and the lines themselves for the exported ones.
- The world position and heading the cutscene plays at.

The list is grouped into story missions, story heists, Strangers and Freaks, GTA Online heists, the GTA Online updates and test files. That grouping is read from the cutscene names, because the files themselves do not record which mission they belong to.

## What the preview shows

A cutscene in GTA V is not one animation. It is a set of actors with their own character models and faces, a camera track, props, lighting, audio, subtitles and a piece of the world around it. The preview covers the parts that can honestly be rebuilt in a browser:

- Each actor's real body animation, played on our own freemode ped.
- Every actor standing where the cutscene puts them, relative to each other.
- The props we already have a 3D model for, animated by the cutscene.
- The cutscene's own camera: position, rotation and field of view, with its real cuts.
- The subtitle line that belongs to the current moment.

It does not show the cutscene character models, facial animation or lip sync, lighting or effects, audio, vehicles, or the world the scene plays in. Treat it as a blocking pass, not as the cutscene.

Cutscenes without a preview still show all of their metadata and the Lua. They were left out because they run longer than the export limit, have no ped actor, or are test files.

## Watching one

- **Scene camera** looks through the cutscene's own camera. **Orbit** gives you a free camera you can drag and zoom.
- Scrub the bar to find a moment, change the speed, or turn the loop off to watch it once.
- Each actor has its own male or female ped switch. The animation data is identical on both.
- **Floor** hides the ground plane, **Reset view** puts the orbit camera back.
- The page URL keeps the selected cutscene, so you can link straight to one.

## Playing the real cutscene in game

Click the cutscene name to copy it. The Lua panel gives you the working sequence:

```lua
local scene = "ah_1_int"

RequestCutscene(scene, 8)
while not HasCutsceneLoaded() do
    Wait(0)
end

StartCutscene(0)

while IsCutsceneActive() do
    Wait(0)
end
RemoveCutscene()
```

A few things worth knowing:

- Register an entity **before** `StartCutscene`, never after. The handle string is the model the cutscene expects for that actor, which the actor rows show you next to the character name.
- `SetCutsceneEntityStreamingFlags` and the flags on `RegisterEntityForCutscene` decide how much of the ped the cutscene owns. Flag 64 is the usual "let the cutscene drive it".
- A cutscene streams the world around it. Played somewhere else it will look wrong or hang on a black screen, so warp the player to the coordinates in the panel first.
- Always call `RemoveCutscene` when you are done, or the next request will fail.

## Credits

Every cutscene here is our own extraction from the game files. The public [gta-v-data-dumps](https://github.com/DurtyFree/gta-v-data-dumps) name list was used once, as a cross check on the names we found.

_Last updated: 2026-09-23_

---

## Interiors, IPLs and ymaps

URL: https://fivemad.com/docs/tools/interiors

Find any GTA V MLO interior with a cutaway render, its rooms, portals and entity sets, plus every IPL and ymap name with ready RequestIpl and teleport Lua.

The interiors browser answers the questions you hit when you build anything indoors: which interior is this, where is it, does it load on its own, what is the IPL called, and which entity sets turn the furniture on. It lives under [Assets](/assets) at `/assets/interiors` and has three tabs.

## MLOs

An MLO is a real interior: rooms you can walk through, with portals between them. Every one has a cutaway render so you can recognise it without loading the game.

Each entry shows:

- **Name and hash**, both copyable.
- **Rooms** with their flags and timecycle modifier, so you know which room name to pass to `GetRoomKeyFromEntity` checks.
- **Portals** between rooms.
- **Entity sets**: the optional furniture and clutter an interior can turn on. Copy the name for `EnableInteriorProp`.
- **Where it is placed**: every instance in the world with its coordinates, and a link to the same spot on the [Interactive Map](/docs/tools/interactive-map).
- A badge saying **Loaded by default** or **Needs RequestIpl**.

Under the detail you get ready Lua: a teleport to the interior, the `RequestIpl` call when it needs one, and an entity set block.

## IPLs

The IPL tab is the flat list of map names you can pass to `RequestIpl` and `RemoveIpl`, the ones people usually hunt for on forum threads. Filter to **Needs RequestIpl** to see only the ones a script has to load, and copy the name or the Lua.

```lua title="client.lua"
RequestIpl("v_michael")
-- later
RemoveIpl("v_michael")
```

> [!NOTE]
> Most IPLs are part of the world the game loads on its own. You only need `RequestIpl` for a scripted one, or after something removed it.

## YMAPs

Ymaps are the placement files behind the map. The tab lists every name with what is in it, which is what you want when you are hunting the file that places a prop, or checking that a name you found in an old script still exists.

## Tips

- Search matches names and labels, so `bank`, `mrpd` or `casino` gets you close in one go.
- The tab and the selected item are in the URL (`?t=mlos&id=…`), so a link shares the exact entry.
- An interior that says **Needs RequestIpl** will look empty in game until you load it, which is the usual reason a teleport lands you in a black room.

_Last updated: 2026-09-23_

---

## Ped Decorations

URL: https://fivemad.com/docs/tools/decorations

Find any GTA V tattoo, badge or decal, see it on a ped, and copy the collection and overlay hashes for AddPedDecorationFromHashes.

Ped Decorations lists all 3,373 tattoos, badges and t-shirt decals the game defines, from the base game and every DLC pack. Each one shows its artwork, a picture of it on a freemode ped, and the two hashes you need to apply it.

## What it is for

`AddPedDecorationFromHashes` wants two hashes: a collection and an overlay. Nothing in game tells you what either of them is called, and the names are not guessable (`mpbiker_overlays` plus `MP_MP_Biker_Tat_001_F`). This page is the list, with a picture so you know what you are about to apply.

## Finding a decoration

Type anything into the search box: the overlay name, the shop name the game gives it ("Demon Rider", "Ship Arms"), the collection, or the texture dictionary. Then narrow it down:

| Filter | What it does |
| --- | --- |
| Collection | One DLC pack's overlay file, for example Bikers or Beach Bum |
| Zone | Torso, head and neck, left or right arm, left or right leg |
| Ped | Male, female, or entries that work on either |
| Kind | Tattoo, or badge and decal (t-shirt prints and crew badges) |

Your filters and the decoration you picked live in the address bar, so you can paste a link and the other person lands on the same one.

## The panel

Clicking a picture opens the detail panel. It has:

- **The artwork** on its own, trimmed to the part of the texture sheet that is actually used.
- **The ped picture**: the same decoration drawn on a freemode ped, framed on its zone, so you can see where it lands before you load the game.
- **Overlay, collection, pack, zone, ped and kind**, plus the texture dictionary and texture name.
- **Both hashes** as unsigned, signed and hex, all one click to copy.
- **The shop price**, when the game sells that one in a tattoo shop.
- **Ready Lua**, on four tabs.

## Applying one

```lua title="client.lua"
local ped = PlayerPedId()

-- collection first, then the overlay name
AddPedDecorationFromHashes(ped, `mpbeach_overlays`, `MP_Bea_M_Back_000`)
```

The backticks are FiveM's hash literals. The native wants the joaat of each name, not the string. If backticks are not an option, the panel also gives the plain numbers:

```lua title="client.lua"
AddPedDecorationFromHashes(ped, -1719270477, 1056297333)

-- same thing, hashed at runtime
AddPedDecorationFromHashes(ped, GetHashKey("mpbeach_overlays"), GetHashKey("MP_Bea_M_Back_000"))
```

> [!TIP]
> Store the two strings, not the hashes, in your character data. They are readable in a database dump and you can hash them again any time.

## Taking them off

```lua title="client.lua"
local ped = PlayerPedId()

ClearPedDecorations(ped)            -- everything, scars included
ClearPedDecorationsLeaveScars(ped)  -- keep scars, drop tattoos and decals
```

There is no native for removing a single decoration. Clear them all and reapply the ones you want to keep, which is why most scripts hold the player's tattoo list server side.

## Applying a set

```lua title="client.lua"
local tattoos = {
    { collection = "mpbeach_overlays", overlay = "MP_Bea_M_Back_000" },
    { collection = "mpbiker_overlays", overlay = "MP_MP_Biker_Tat_000_M" },
}

local function applyTattoos(list)
    local ped = PlayerPedId()
    ClearPedDecorations(ped)
    for _, t in ipairs(list) do
        AddPedDecorationFromHashes(ped, GetHashKey(t.collection), GetHashKey(t.overlay))
    end
end

applyTattoos(tattoos)
```

Call that again after every model change, respawn and clothing menu that rebuilds the ped. Decorations do not survive `SetPlayerModel`.

## Things to watch out for

> [!WARNING]
> The order of the two hashes matters. Collection first, overlay second. Swapping them does nothing at all and reports no error.

- **Male and female entries are separate.** Most tattoos ship twice, ending in `_M` and `_F`, with slightly different placement. Applying the male one to a female ped puts it in the wrong place.
- **DLC collections need the game build.** A collection from a newer pack only exists on a server running a build that includes it. Set `sv_enforceGameBuild` accordingly.
- **Crew emblem overlays have no picture.** They point at a texture the game builds at runtime from the player's crew, so there is nothing to show and nothing to extract.
- **A few entries have no ped picture.** They sit outside the parts of the ped we draw, so only the artwork is shown.

## Placing your own artwork

Every panel has a link into the [3D Tattoo Editor](/tools/tattoo-editor) opened at that decoration's zone, position, scale and rotation. Drop your own image on top and you get an overlay that sits exactly where the game tattoo sits.

## Where the data comes from

The collections, placements and hashes are read out of the game's own `PedDecorationCollection` files. The artwork is each decoration's texture, and the ped pictures are rendered by us on our own conversion of the freemode ped. Nothing on this page is taken from another site.

_Last updated: 2026-09-23_

---

## Giveaways

URL: https://fivemad.com/docs/tools/giveaways

How fivemad giveaways work for players: log in with Discord, finish the tasks, enter, and how winners are picked and contacted.

fivemad giveaways are free draws run by FiveM creators: scripts, vehicle packs, MLOs, clothing, server slots, Tebex gift cards and more. You log in with Discord, finish the tasks the host set, enter, and when the timer runs out the winners are picked at random. This page explains everything from the entrant's side.

## Quick start

1. Open [Giveaways](/giveaways) and pick one.
2. Press **Log in with Discord to enter** and approve the login on Discord.
3. Work through the **Tasks** list. Each task shows a tick when it is done.
4. Press **Enter giveaway** once every task is done. The panel changes to **You are in**.
5. Come back after the timer runs out to see the winners.

## Finding a giveaway

The giveaways page has three tabs: **Active**, **Ending soon** and **Ended**. You can filter by prize type (Script, Vehicle pack, MLO, Clothing, Server slot, Tebex gift card, Discord Nitro, Other) and search by name. Each card shows the prize, the host, the time left, the number of entries, winners and tasks.

New giveaways are announced in the fivemad Discord first, so join it if you do not want to miss one.

## Logging in with Discord

Giveaways use your Discord account, so there is no separate fivemad account or password.

- When you log in, Discord asks you to allow fivemad to see your **name and avatar** and **which servers you are in**. That is all the site asks for.
- The server list is how the "join a server" tasks are checked.
- Nothing gets posted for you, and the site cannot read your messages or DMs.
- **Log out** in the header ends your session on fivemad. To remove the app's access completely, open Discord, User Settings, Authorized Apps, and remove it there.

## Task types

A giveaway can have any mix of these tasks, or none at all ("No tasks for this one. Log in and enter.").

| Task | What you see | What you need to do |
| --- | --- | --- |
| Join a Discord server | "Join *server* on Discord" with a **Join** button | Join that server with the same Discord account you logged in with. |
| Have a role | "Have the *role* role in *server*" | Be a member of that server and hold the role. How you get the role is up to the host's server (verification, reacting, levels and so on). |
| Account age | "Discord account at least *N* days old" | Nothing to do: your Discord account must be at least that old. This stops fresh alt accounts. |
| Visit a link | "Visit *name*" with an **Open** button | Open the link (a store page, a video, a forum post). |

**Visit a link** tasks cannot be checked, and the page says so: "We cannot check this one, so opening the link counts." The task is ticked as soon as you press **Open** while logged in.

### When a task is not done

Under an unfinished task you may see:

| Message | What to do |
| --- | --- |
| You are not in this server yet. | Press **Join**, join the server, then come back. |
| You do not have this role yet. | Get the role in that server first. |
| Your Discord account is too new for this giveaway. | Nothing you can do for this giveaway. |
| Log in again so we can check this. | Log out and log in again. |
| Discord did not answer. Try again in a moment. | Wait a little and press **Check again**. |

## Check again

After you join a server in another tab, press **Check again** above the task list. When you switch back to the giveaway tab with a Discord task still open, the page also checks again by itself. Discord can take a few seconds to report a new join, so if a task does not tick right away, wait a moment and press **Check again** once more.

## Entering

The button at the bottom of the panel tells you where you stand:

- **Finish every task to enter**: at least one task is not done yet.
- **Enter giveaway**: everything is done. Press it.
- **You are in**: you entered, with the date. Good luck.
- **Entries open when the giveaway starts.** / **Entries are closed.**: the giveaway has not started or has ended.

The tasks are checked again when you press **Enter giveaway**, so leaving a server right before entering does not work. You can enter each giveaway once. **Copy link** at the bottom of the panel copies the giveaway's link to share.

Your entries are listed on **My entries** (the link at the top of the giveaways page), with the ones you won marked.

## How winners are drawn

- When the timer runs out, winners are picked at random from every valid entry. The number of winners is shown on the giveaway.
- Hosts can have each picked winner checked again at draw time. Anyone who left a required server or lost a required role by then is skipped, and the next random entry is used instead. So stay in the servers until the draw is done.
- The results appear on the giveaway page with the draw date and how many entries were in the draw. If the timer just ran out, the page says the winners are being drawn; reload in a moment.
- If the host has to replace a winner later (for example one who never claimed the prize), the page shows that a winner was replaced and when.
- If nobody entered, there are no winners.

## If you win

The giveaway page shows **You won** when you are logged in, and the giveaway is marked as won on **My entries**. Contact the host to claim your prize; the **Contact** button opens the host's link when they set one. Have your Discord name ready. fivemad does not hand out prizes itself, the host does.

## Tips

- Log in with the Discord account you actually use in those servers. Tasks are checked against that account only.
- Do not leave the host's server right after entering. With the draw re-check on, you would be skipped.
- Times are shown in your own time zone.

## Limitations

- Giveaways are run by their hosts. fivemad checks the tasks and runs the draw, but the prize and its delivery are between you and the host.
- An account that is blocked from giveaways sees "This account cannot join giveaways." at login.
- Pages in other languages have the same giveaways; only the page text is translated.

## Related tools

- [Generators](/docs/tools/generators) and the rest of the [tools overview](/docs/tools) are free to use without logging in.

_Last updated: 2026-09-22_

---


# Tool list

Every tool runs in the browser and is free.

- Interactive Map (https://fivemad.com/tools/interactive-map): Find any spot on the GTA V map, copy exact coordinates as vector3 or vector4, measure distances and drop pins. Switch to 3D to roam the world rendered from the game's own models, with a freecam or on foot.
- Clothing Designer (https://fivemad.com/tools/clothing-designer): A 3D texture editor for FiveM clothing. Drop a .ydd or .ydr with its .ytd files or start from a game template, then paint on the model or on the texture with the UV layout on top. Layers, text, images, shapes, gradients and texture variations, all exported as ready to stream .ytd files.
- Animation Browser (https://fivemad.com/tools/animations): Watch a clip before you write the code. The browser lists every dictionary and clip the game ships, with the real frame count, length and rate, and plays them on our own freemode ped: scrubbing, speed, a male and a female ped and a ready RequestAnimDict plus TaskPlayAnim snippet. The synced scenes tab puts two peds and the scene's prop on one timeline.
- Cutscene Browser (https://fivemad.com/tools/cutscenes): Look up any cutscene before you call RequestCutscene: the real name, how long it runs, the ped models that act in it, the props, the camera cuts, the subtitle lines and where in the world it plays. A large part of the list also has a 3D preview that plays each actor's body animation on our freemode ped and follows the cutscene's own camera.
- YMAP Builder (https://fivemad.com/tools/ymap-builder): Build a map placement file without opening a map editor: paste coordinates from the game or add props one by one, set heading or full rotation, and get CodeWalker-ready .ymap XML with quaternions, entity and streaming extents calculated for you. Import an existing ymap XML to edit it.
- Zone Creator (https://fivemad.com/tools/zone-creator): Draw the zone where it actually is. Click points on the Los Santos map or in the 3D world, set the two heights against the real ground, then copy ready code for ox_lib zones, PolyZone, ox_target or qb-target, or just the points as a Lua table or JSON. Paste an existing zone back in to edit it, and share the whole thing as a link.
- 3D Tattoo Editor (https://fivemad.com/tools/tattoo-editor): Upload a tattoo, pick a zone and position it on mp_m_freemode_01 or mp_f_freemode_01 in 3D. Click the body to place it, fine tune UV position, scale and rotation, then copy the overlay XML or open it in Durty Cloth Tool.
- Objects / Props List (https://fivemad.com/tools/objects-list): Browse every GTA V prop with a rendered picture, readable name, category, tags and its real size in metres. Search by name or tag, paste a hash to find the model it belongs to, and copy a ready CreateObject snippet.
- Screen Effects Browser (https://fivemad.com/tools/screen-effects): Browse all 1,101 timecycle modifiers and 252 animpostfx effects with the exact values they set, our own before and after preview of each one, and ready SetTimecycleModifier and AnimpostfxPlay snippets.
- Ped Decorations (https://fivemad.com/tools/decorations): Browse all 3,373 ped decorations from the base game and every DLC pack: the overlay artwork, the same decoration drawn on a freemode ped so you see where it lands, its collection, zone and gender, and the collection and overlay hashes with ready AddPedDecorationFromHashes Lua.
- Interiors, IPLs and ymaps (https://fivemad.com/assets/interiors): Find the interior you need: 391 MLO archetypes with a rendered cutaway, their rooms, portals, entity sets and timecycle mods, every placed instance with its coordinates, and the full list of IPL and ymap names with ready Lua to load or unload them.
- Minimap Editor (https://fivemad.com/tools/minimap-editor): Give your server its own minimap. Pick a shape or upload your own mask, move and resize it on a real screen, set the border, glow, rings, blip clipping, zoom and HUD colours, and watch it draw over the actual Los Santos map as you edit. Download a complete resource: the mask textures, the Lua that applies every value and a README that explains each one.
- Vehicle Handling Editor (https://fivemad.com/tools/vehicle-handling-editor): Edit 45 common CHandlingData fields plus the flags with sliders and live explanations. Import an existing handling.meta, tweak it and export handling.meta XML or runtime Lua using SetVehicleHandlingFloat.
- Drawable Studio (https://fivemad.com/tools/drawable-studio): Drop a CodeWalker XML export with its textures and get a 3D view of the model in your browser. Check geometry and textures, edit shader parameters and lights, paint straight onto the model, then export the XML, PNG textures or a GLB.
- Particle Effects List (https://fivemad.com/tools/particles-list): Browse all GTA V particle effects with their asset dictionaries and copy a working UseParticleFxAsset + StartParticleFxLoopedOnEntity snippet.
- Sound Browser (https://fivemad.com/tools/sound-browser): Search every known GTA V sound name and sound set, play it right here, and copy a working PlaySoundFrontend or PlaySoundFromCoord snippet. No need to restart the game to find the right beep.
- Texture Editor (https://fivemad.com/tools/texture-editor): Open a CodeWalker .ytd XML export with its DDS files, preview every texture and channel, replace them with PNG or JPG, resize to power of two, pick the compression (DXT1, DXT5, BC7 where possible) and export the new DDS files plus the .ytd XML ready to import.
- Vehicle Sirens Editor (https://fivemad.com/tools/vehicle-sirens): Build and tune emergency lighting: every siren light's colour, rotation, flash and 32-step sequencer pattern with a live preview, BPM and timing, then export carcols.meta. Drop your carcols files to see which siren IDs are taken, free or clashing.
- Model & Hash Browser (https://fivemad.com/tools/model-hash-browser): Browse every GTA V vehicle, ped and weapon with images, spawn names, display names, classes and signed/unsigned/hex hashes. Filter, search and copy in one click.
- Generators (https://fivemad.com/tools/generators): Everything that makes something up for you: a full roleplay character, server names with ready hostname lines, a gang with ranks and turf in Los Santos, and script ideas based on what is being released on forum.cfx.re, each with a technical plan.
- server.cfg Generator (https://fivemad.com/tools/server-cfg-generator): Fill in a form and get a clean, commented server.cfg ready to drop into your FiveM server, including OneSync, endpoints, tags, locale, resources and ACE permissions.
- fxmanifest.lua Generator (https://fivemad.com/tools/fxmanifest-generator): Generate a valid fxmanifest.lua for any FiveM or RedM resource: shared/client/server scripts, NUI page, files, dependencies, exports and lua54.
- Weapons Meta Editor (https://fivemad.com/tools/weapons-meta-editor): Start from the real default weapons.meta of any base game or DLC weapon, tweak damage, range, fire rate, reload, clip size, accuracy and recoil with explanations, compare against the default, and export a clean weapons.meta and fxmanifest for your server.
- YTYP Creator (https://fivemad.com/tools/ytyp-creator): Build CBaseArchetypeDef entries for custom props: name, texture dictionary, LOD distance, flags, physics dictionary and asset type. Drop CodeWalker .ydr XML files and the bounding box, sphere centre and radius are measured from the mesh. Import any default game ytyp as a starting point.
- Vehicle Pack Validator (https://fivemad.com/tools/vehicle-pack-validator): Drop a FiveM vehicle resource folder and get a report: models without handling, handling ids that do not match, missing carcols or carvariations entries, missing .yft/.ytd files, missing _hi models, data_file lines that are wrong or missing, duplicate names and more, each with the fix.
- YMT Creator (https://fivemad.com/tools/ymt-creator): Drop the .ydd and .ytd files of a clothing pack and get the CPedVariationInfo .ymt XML with every component, drawable, texture variation and prop filled in, plus the creature metadata and fxmanifest lines to stream it.
- Inventory Icons (https://fivemad.com/tools/inventory-icons): Pick props from the game or drop your own PNGs, then trim, pad, resize and export a clean icon pack for ox_inventory, qb-inventory or any other inventory, with the matching items list ready to paste.
- Script Thumbnail Creator (https://fivemad.com/tools/script-thumbnail-creator): Drop your script's screenshots, type the name, frameworks and price, pick one of nine layouts and export clean preview images for your forum.cfx.re release, YouTube video, Discord post and Tebex package. Every size from one project, rendered in your browser.
- Snaily Creator (https://fivemad.com/tools/snaily-creator): Build your own version of Snaily, our mascot. Set the colours, pick a mood from happy to furious, add hats, sunglasses, chains, outfits, shell stickers, backdrops and something to hold, then export a transparent PNG or an SVG for your Discord, your server or your release images.
- Crosshair Generator (https://fivemad.com/tools/crosshair-generator): Build the crosshair you want, from a single dot to a cross with a ring, brackets or chevrons, and check it over a dark scene, a light scene and Los Santos. Export a ready to drop NUI overlay resource with fxmanifest and client Lua, a transparent PNG, an SVG, or the cl_crosshair console settings that come closest to your design.
- YTD Optimizer (https://fivemad.com/tools/ytd-optimizer): Drop a stream folder or a pile of .ytd files and optimize them in one go: cap the largest texture size, turn opaque DXT5 into DXT1, fix missing or broken mip chains and see the memory saved per file before you download. Everything runs in your browser.
- Native Audio Builder (https://fivemad.com/tools/native-audio-builder): Drop your sounds and get a complete FiveM resource that plays them as real game audio: the .awc wave bank and .dat54.rel sound data built right here (no CodeWalker step), the data_file lines, and Lua to load the bank and play sounds on the UI, on an entity or at a position, synced if you want. Based on lb-nativeaudio.
- Server Status Checker (https://fivemad.com/tools/server-status-checker): Look up any FiveM server by IP:port or cfx.re join code and see whether it is online, its player list, game build, OneSync, resources and server variables.
- Profiler Analyzer (https://fivemad.com/tools/profiler-analyzer): Record with the built-in FiveM profiler, drop the saved JSON here and get a readable report: time per resource, worst frames, hot threads and events, spikes over time and plain advice on what to fix. Everything is parsed in your browser, nothing is uploaded.
- Cfx Blacklist Checker (https://fivemad.com/tools/cfx-blacklist-checker): Cfx.re blocks some IPs and hosting ranges from running public servers. Paste IPs, host names or cfx.re join codes (up to 20 at once) and see which ones are blacklisted, straight from Cfx's own endpoint.
- Server Status Badge (https://fivemad.com/tools/server-uptime-badge): Generate an auto-updating SVG badge showing your FiveM server's online state and player count. Copy the Markdown, HTML or BBCode and paste it anywhere.
- joaat Hash Calculator (https://fivemad.com/tools/hash-calculator): Compute GTA V / RDR2 joaat hashes (GetHashKey) for any string, in bulk, entirely in your browser. Signed, unsigned and hex output, plus a ready Lua hash table for bulk lists.
- Driving Style Calculator (https://fivemad.com/tools/driving-style-calculator): Combine vehicle driving flags (stop for cars, avoid peds, use shortest path…) into the single integer used by TaskVehicleDriveToCoord, TaskVehicleDriveWander and SetDriveTaskDrivingStyle.
- Animation Flags Calculator (https://fivemad.com/tools/animation-flags-calculator): Pick animation behaviours and get the combined flag integer for TaskPlayAnim / TaskPlayAnimAdvanced, with a ready-to-paste Lua snippet.
- Warning Screen Buttons (https://fivemad.com/tools/warning-buttons): Choose which instructional buttons should appear on a GTA V warning/alert screen and get the exact flag value for SetWarningMessage / SetWarningMessageWithHeader.
- Draw Text Colors (https://fivemad.com/tools/text-colors): Type text with GTA V formatting codes (~r~, ~b~, ~h~, ~n~ …) and see a live preview of how it renders in DrawText, notifications and help text.
- Blip, Marker & Checkpoint Browser (https://fivemad.com/tools/blip-marker-browser): Find the right map blip sprite, blip colour, 3D marker or race checkpoint for your script. Every entry shows its ID and preview, with one-click copy and a ready Lua snippet.
- Weapon Stats & Components (https://fivemad.com/tools/weapon-stats): Look up any GTA V weapon: hashes, weapon group, ammo type, max ammo, damage type, every component/attachment hash and every tint index.
- Controls Reference (https://fivemad.com/tools/controls-reference): Look up any control for IsControlJustPressed and DisableControlAction: index, INPUT_ name, default keyboard key and gamepad button. Press a key on your keyboard to find every control bound to it, and copy a ready snippet or a RegisterKeyMapping alternative.
- Scaleform Functions (https://fivemad.com/tools/scaleform-reference): Search GTA V scaleform movies and the functions you can call on them with BeginScaleformMovieMethod, including known parameter lists.
- Player Stats List (https://fivemad.com/tools/player-stats): Search 3,000+ known GTA Online stat names (MP0_, MP1_ and global) with their data type and hash, ready for StatGetInt / StatSetInt and friends.
- Parachutes & Smoke Trails (https://fivemad.com/tools/parachutes): All parachute pack tints, canopy styles and smoke-trail colours with their indices and RGB values, plus the natives to apply them.
- Game Damage Events (https://fivemad.com/tools/damage-events): Understand the gameEventTriggered / CEventNetworkEntityDamage payload and hook clean onPlayerKilled, onPlayerDied and vehicle-destroyed events in your own resource.

# Dataset list

- Props with pictures (https://fivemad.com/data/props.json): Every GTA V prop model that has a picture, with a readable label, category, tags and its real size in metres. 30,033 rows, 2.6 MB. Shape: rows: [model, label, category, tags, [x,y,z] size in m, minBuild, hasThumb, has3d, hasShot]
- Object model names (https://fivemad.com/data/objects.json): Plain list of object model names, including the map pieces that have no picture. 21,631 rows, 505 KB. Shape: { count, names } where names is one lower case model name per line
- Archetype definitions (https://fivemad.com/data/archetypes.json): The .ytyp archetype of each model: LOD distance, flags, bounding box, texture and physics dictionaries. 33,071 rows, 3.0 MB. Shape: cols lists the column names, rows is an array of arrays in that order
- Vehicles (https://fivemad.com/data/vehicles.json): Every vehicle with its spawn name, display name, manufacturer, class, seats, performance figures and flags. 921 rows, 309 KB. Shape: items: [{ n spawn name, h hash when it differs from joaat(n), l label, m make, c class, t type, d dlc, s seats, sp/ac/br/ag performance, f flags }]
- Peds (https://fivemad.com/data/peds.json): Every ped model with its type and the DLC it came with. 1,109 rows, 68 KB. Shape: items: [{ n model name, h hash when it differs, l label, t ped type, d dlc }]
- Weapons and components (https://fivemad.com/data/weapons.json): Every weapon with its group, ammo type, max ammo, flags, components, tints and liveries. 184 rows, 180 KB. Shape: items: [{ n WEAPON_*, h, l, c group, a ammo, ma max ammo, cp components, ti tints, lv liveries }]
- weapons.meta defaults (https://fivemad.com/data/weapons-meta.json): The game's own weapons.meta values for every weapon, stored as line indices into a shared line table. 594 KB. Shape: { lines, items } where each item's blocks are base 36 indices into lines
- Vehicle siren settings (https://fivemad.com/data/sirens.json): Every carcols siren setting with its lights, sequences and the vehicles that use it. 21 rows, 617 KB. Shape: settings: [{ id, name, lightFalloff*, sirens: [...] }]
- Vehicle reference names (https://fivemad.com/data/vehicle-refs.json): Model, handling, layout, mod kit and audio names read out of the game files, for validating a vehicle resource. 935 rows, 83 KB. Shape: named string arrays (models, handling, layouts, modkits, ...)
- Particle effects (https://fivemad.com/data/particles.json): Every particle effect name grouped by its particle asset (ptfx dictionary). 2,907 rows, 82 KB. Shape: dicts: [{ name, effects: [effect name] }]
- Particle effects with video (https://fivemad.com/data/particle-videos.json): The subset of particle effects that has a recorded preview clip under /media/particles. 2,317 rows, 59 KB. Shape: dicts: [[dict name, [effect name]]]; media id = running index over the whole list
- Frontend sounds (https://fivemad.com/data/sounds.json): Sound names grouped by sound set, with the ones that have an audio preview marked. 2,179 rows, 130 KB. Shape: sets: [{ n set name, s: [[sound name, hash, ...]] }]
- Heist animation clips (https://fivemad.com/data/animations.json): The curated heist dictionaries with their clips, frame counts and lengths. 399 rows, 23 KB. Shape: dicts: [{ d dictionary, g group, c: [[clip, frames, seconds, tracks, bytes]] }]
- Full animation catalogue (https://fivemad.com/data/anim/index.json): Every animation dictionary and clip the game ships. index.json has the totals and families, fam-<id>.json the dictionaries of a family, c-000..127.json the clip rows (shard = FNV-1a of the dictionary name mod 128) and search.txt one line per dictionary. 97,204 rows, 2 KB. Shape: clip row: [name, frames, seconds, tracks, bytes, skip]; bytes > 0 means the clip has a playable file
- Synced scenes (https://fivemad.com/data/synced-scenes.json): Two ped synchronised scenes: which clips play on which ped, and the prop when there is one. 458 rows, 185 KB. Shape: scenes: [{ i id, n name, g group, a: [{ d dict, c clip, p prop clip }] }]
- Cutscenes (https://fivemad.com/data/cutscenes.json): Every cutscene the game ships, with its actors, length, camera cuts, subtitle count and world position. 781 rows, 549 KB. Shape: scenes: [{ n name, t title, g group, d seconds, sc sections, cc camera cuts, o world offset, a actors }]
- Ped decorations (https://fivemad.com/data/decorations.json): Every tattoo, badge and decal the game defines, with its collection, zone, gender and placement. 3,373 rows, 366 KB. Shape: rows: [name, zone index, txd, txt, gender, ...]; collections: [{ n, dlc, l, h collection hash }]
- Timecycle modifiers (https://fivemad.com/data/timecycles.json): Every timecycle modifier with the parameters it sets and where it is defined. 1,101 rows, 453 KB. Shape: mods: [[name, sourceIndex, userFlags, [[paramIndex, valueA, valueB]], usedBy, alsoIn, img, key]]; params names the indices
- animpostfx effects (https://fivemad.com/data/animpostfx.json): Every animpostfx screen effect with its hash, layers and timings. 252 rows, 139 KB. Shape: fx: [{ n name, h hash, pr priority, l layers }]
- MLO interiors (https://fivemad.com/data/mlos.json): Every MLO archetype with its rooms, portals, entity sets, timecycle mods and bounding box. 391 rows, 348 KB. Shape: mlos: [{ n name, h hash, t ytyp, d dlc index, bb bounds, rm rooms, st entity sets, in instances }]
- Placed interiors (https://fivemad.com/data/interiors.json): Each MLO with the IPL that places it and its world position, in a flat shape. 391 rows, 58 KB. Shape: items: [{ name, kind, ipl, dlc, rooms, pos [x,y,z] }]
- IPL names (https://fivemad.com/data/ipls.json): Every IPL name with the DLC it belongs to and where it sits in the world. 10,613 rows, 632 KB. Shape: cols lists the column names, rows is an array of arrays in that order
- ymap files (https://fivemad.com/data/ymaps.json): Every .ymap in the game with its header flags, entity counts and extents. 10,613 rows, 909 KB. Shape: cols lists the column names, rows is an array of arrays in that order
- Blips, markers and blip colours (https://fivemad.com/data/blips.json): Blip sprite ids with their names and preview images, marker types and the blip colour table. 966 rows, 107 KB. Shape: sprites / markers / colors arrays of { id, name, img }
- Checkpoint types (https://fivemad.com/data/checkpoints.json): Every race checkpoint type with its id and a preview image. 50 rows, 24 KB. Shape: checkpoints: [{ id, name, img }]
- Control indices (https://fivemad.com/data/controls.json): Every control index with its INPUT_ name and the default keyboard and pad bindings. 361 rows, 39 KB. Shape: controls: [{ index, name, keyboard, pad, kb, gp }]
- Scaleform movies (https://fivemad.com/data/scaleforms.json): Scaleform movie names with the functions you can call on them and their known parameter names. 471 rows, 192 KB. Shape: movies: [[movie name, category index, [[function name, [param names]]]]]
- Player stats (https://fivemad.com/data/stats.json): Known GTA Online stat names with their data type. 3,025 rows, 213 KB. Shape: stats: [[name, typeIndex, description, ...]]; types names the indices
- forum.cfx.re release trends (https://fivemad.com/data/cfx-trends.json): What the latest batch of forum.cfx.re releases is made of: frameworks, categories, selling points and topics. 250 rows, 24 KB. Shape: { source, totals, frameworks, sellingPoints, categories, topics }