> For the complete documentation index, see [llms.txt](https://visionstore.gitbook.io/visionstore-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://visionstore.gitbook.io/visionstore-docs/scripts/badges/installation.md).

# Installation

Get Vision Badges Creator running on your server in a few minutes.

## Requirements

| Resource                                               | Required | Notes                                                                                                                                          |
| ------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **OneSync**                                            | ✅ Yes    | The server reads player positions and routing buckets itself.                                                                                  |
| [**ox\_lib**](https://github.com/overextended/ox_lib)  | ✅ Yes    | Callbacks, menus, progress bar, `[E]` prompt.                                                                                                  |
| [**oxmysql**](https://github.com/overextended/oxmysql) | ✅ Yes    | Issued badges, photos, numbers and Studio changes.                                                                                             |
| Framework                                              | Optional | qbx\_core, qb-core, es\_extended or ox\_core, detected automatically. Standalone works too.                                                    |
| Inventory                                              | Optional | ox\_inventory, qs-inventory, qb-inventory / ps-inventory / lj-inventory. Without one, badges live in the database and are shown with `/badge`. |
| Target                                                 | Optional | ox\_target or qb-target. Without one, desks use a built-in ox\_lib `[E]` prompt.                                                               |

## Install

{% stepper %}
{% step %}

### Add the resource

Download the asset from [portal.cfx.re](https://portal.cfx.re) and put the `vision_badges` folder in your `resources` folder (directly, or inside a category such as `resources/[vision]/vision_badges`).

{% hint style="warning" %}
Keep the folder name **exactly** `vision_badges`. The ox\_inventory item calls the export `vision_badges.useBadge`, and that name is the folder name.
{% endhint %}
{% endstep %}

{% step %}

### Start it in server.cfg

Start it **after** your framework, inventory and target resource. They are detected once, when Vision Badges Creator starts; anything that starts later is not seen.

```properties
ensure ox_lib
ensure oxmysql
ensure qbx_core          # or qb-core / es_extended / ox_core (or nothing: standalone)
ensure ox_inventory      # or qs-inventory / qb-inventory / ps-inventory / lj-inventory (or nothing)
ensure ox_target         # or qb-target (or nothing: built-in [E] prompt)
ensure vision_badges
```

{% endstep %}

{% step %}

### Database

Nothing to do: the four tables are created on the first start.

| Table                  | Holds                                                                     |
| ---------------------- | ------------------------------------------------------------------------- |
| `vision_badges`        | One row per issued badge, with its photo. The row id is the badge serial. |
| `vision_badge_numbers` | Each person's permanent badge number per number pool.                     |
| `vision_badge_types`   | Badge types created or edited in the Badge Studio.                        |
| `vision_badge_desks`   | Desks created or edited in the Badge Studio.                              |

If your database user can't create tables, the console prints `could not create the badge tables: ...`. Import `install/vision_badges.sql` yourself and restart the resource.
{% endstep %}

{% step %}

### The badge item

**One item, `vision_badge`, carries every badge type.** A new badge never needs a new item. Pick your inventory:

{% tabs %}
{% tab title="ox\_inventory" %}

1. Paste the entry from `install/ox_inventory_items.lua` into `ox_inventory/data/items.lua`, inside the returned table.
2. Copy **every** file in `install/images/` to `ox_inventory/web/images/`.
3. Restart the server.

```lua
['vision_badge'] = {
    label = 'Badge',
    weight = 100,
    stack = false,
    close = true,
    consume = 0,
    description = 'An identification badge. Use it to show it to the people around you.',
    server = {
        export = 'vision_badges.useBadge',
    },
},
```

With ox\_inventory each badge sets the item's label, icon and tooltip itself: a police badge shows as "Police Badge" with the police icon and a tooltip with the holder's name, rank, number and issue date.

| Image                 | Used by                    |
| --------------------- | -------------------------- |
| `vision_badge.png`    | The item itself (fallback) |
| `badge_police.png`    | `police`                   |
| `badge_sheriff.png`   | `sheriff`                  |
| `badge_state.png`     | `sasp`                     |
| `badge_federal.png`   | `fbi`                      |
| `badge_medical.png`   | `ems`                      |
| `badge_fire.png`      | `fire`                     |
| `badge_justice.png`   | `doj`                      |
| `badge_press.png`     | `press`                    |
| `badge_corporate.png` | `mechanic`                 |
| {% endtab %}          |                            |

{% tab title="qb / ps / lj-inventory" %}

1. Paste the entry from `install/qb_items.lua` into `qb-core/shared/items.lua`.
2. Copy `install/images/vision_badge.png` into your inventory's image folder (for example `qb-inventory/html/images/`).
3. Restart. The script registers the usable item by itself.

```lua
vision_badge = {
    name = 'vision_badge',
    label = 'Badge',
    weight = 100,
    type = 'item',
    image = 'vision_badge.png',
    unique = true,
    useable = true,
    shouldClose = true,
    description = 'An identification badge. Use it to show it to the people around you.',
},
```

These inventories can't change an item's label or icon per badge, so **every badge shows as "Badge"** in the inventory. When used, each badge still shows its own design.
{% endtab %}

{% tab title="qs-inventory" %}

1. Paste the entry from `install/qb_items.lua` (shown in the previous tab) into `qs-inventory/shared/items.lua`.
2. Copy `install/images/vision_badge.png` into qs-inventory's image folder.
3. Restart. The script registers the usable item by itself.

Every badge shows as "Badge" in the inventory; each still shows its own design when used.
{% endtab %}

{% tab title="No inventory" %}
Nothing to install. Badges are stored only in the database and players show them with **`/badge`**.
{% endtab %}
{% endtabs %}

If the item is missing, the console tells you at start:

```
[vision_badges] item "vision_badge" is not registered in ox_inventory - see install/ (badges using it cannot be issued)
```

{% endstep %}

{% step %}

### Give admins access

Admins open the Badge Studio, can issue every badge, and can use `/issuebadge` anywhere. The simplest way is the ace from `Config.Admin.ace`:

```properties
add_ace group.admin vision_badges.admin allow
add_principal identifier.license:YOUR_LICENSE group.admin
```

Players in a framework admin group (`admin`, `god`, `superadmin` by default) also count. See [General settings](/visionstore-docs/scripts/badges/configuration/general.md#admins).
{% endstep %}

{% step %}

### Check the console

Start the server. You should see:

```
[vision_badges] v1.0.0 ready | framework: qbx | inventory: ox_inventory | 9 badge types | 2 desks
```

Check that the framework and inventory are the ones you run. Then follow the [Quick start](/visionstore-docs/scripts/badges/quick-start.md).
{% endstep %}
{% endstepper %}

{% hint style="info" %}
**Want to force a framework, inventory or target?** Set `Config.Framework`, `Config.Inventory` or `Config.Target` in `config/config.lua` instead of `'auto'`. See [General settings](/visionstore-docs/scripts/badges/configuration/general.md#integrations).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://visionstore.gitbook.io/visionstore-docs/scripts/badges/installation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.