> 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/weaponhub/installation.md).

# Installation

Get Vision Weapon Hub running on your server in about ten minutes.

## Requirements

| Resource                                                          | Required | Notes                                                                                                             |
| ----------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| **OneSync**                                                       | ✅ Yes    | Server-side position checks. Enabled in `server.cfg` or txAdmin.                                                  |
| [**ox\_lib**](https://github.com/overextended/ox_lib)             | ✅ Yes    | Callbacks, notifications, prompts.                                                                                |
| [**ox\_inventory**](https://github.com/overextended/ox_inventory) | ✅ Yes    | Attachments are ox\_inventory items. Installed parts, tint and camo colour are stored on the weapon.              |
| Framework                                                         | Optional | qbx\_core, qb-core, es\_extended or ox\_core, detected automatically (money, jobs, admins). Standalone works too. |
| Target                                                            | Optional | ox\_target or qb-target. Without one, an ox\_lib `[E] Weapon Workshop` prompt is shown.                           |
| [Node.js](https://nodejs.org) 16+                                 | Optional | Only on your PC, to run the add-on weapon helper.                                                                 |

## Install

{% stepper %}
{% step %}

### Add the resource

Download the asset from [portal.cfx.re](https://portal.cfx.re) and put the `vision_weaponhub` folder in your `resources` folder (for example `resources/[weapons]/vision_weaponhub`).

{% hint style="warning" %}
Keep the folder name **exactly** `vision_weaponhub`. The admin permission, the event names and the exports use it.
{% endhint %}
{% endstep %}

{% step %}

### Add the attachment items

ox\_inventory ships items for most GTA attachments (`at_scope_medium`, `at_suppressor_light`...). Some base-game parts have no item: MK II special ammunition, MK II pistol slide finishes, the rail cover and a few rare finishes. `install/ox_inventory_items.lua` adds **22 items** for them.

1. Open `ox_inventory/data/weapons.lua`.
2. Find the `Components = {` table (the `at_...` items).
3. Paste the contents of `install/ox_inventory_items.lua` inside it, for example right after `['at_skin_patriotic'] = { ... },`.
4. Copy `install/images/*.png` to `ox_inventory/web/images/`.

There are **92 icons**: the 22 new items plus every stock attachment item. If you already have images you prefer for some stock items, skip those files.

| New items                                                                                                                  | For                                                  |
| -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `at_ammo_tracer`, `at_ammo_incendiary`, `at_ammo_armorpiercing`, `at_ammo_fmj`, `at_ammo_hollowpoint`, `at_ammo_explosive` | MK II special ammunition (fitted as a magazine)      |
| `at_skin_camo_slide` ... `at_skin_patriotic_slide` (11)                                                                    | MK II pistol slide finishes                          |
| `at_railcover`                                                                                                             | The carbine rifle's rail cover                       |
| `at_scope_sniper`                                                                                                          | The large scope of the sniper rifle and heavy sniper |
| `at_skin_etched`, `at_skin_security_alt`, `at_skin_heavyrifle`                                                             | Finishes ox\_inventory has no item for               |

Each entry looks like this:

```lua
['at_ammo_explosive'] = {
    label = 'Explosive Rounds',
    type = 'magazine',
    weight = 200,
    client = {
        component = {
            `COMPONENT_HEAVYSNIPER_MK2_CLIP_EXPLOSIVE`,
            `COMPONENT_PUMPSHOTGUN_MK2_CLIP_EXPLOSIVE`,
        },
        usetime = 2500,
    },
},
```

Give the items to players however you like: a shop, crafting, loot. They are normal items.

{% hint style="info" %}
The hub checks this for you on start. If parts still have no item, the server console prints a warning such as `12 base-game attachments have no ox_inventory item yet`.
{% endhint %}
{% endstep %}

{% step %}

### The "Customize" button (optional)

Adds **Customize** to the right-click menu of every gun in ox\_inventory. In `ox_inventory/data/weapons.lua`:

1. Change the first line `return {` to `local data = {`.
2. Paste the block between the two `CUT HERE` lines of `install/ox_inventory_button.lua` at the very end of the file. It ends with `return data`.
3. Restart ox\_inventory.

```lua
-- Vision Weapon Hub: "Customize" in every gun's right-click menu.
if not IsDuplicityVersion() then
	local label = 'Customize'
	local skip = {
		WEAPON_PETROLCAN = true, WEAPON_HAZARDCAN = true, WEAPON_FERTILIZERCAN = true,
		WEAPON_FIREEXTINGUISHER = true, WEAPON_HACKINGDEVICE = true, WEAPON_DIGISCANNER = true,
		WEAPON_METALDETECTOR = true,
	}

	for name, weapon in pairs(data.Weapons) do
		if not weapon.throwable and not skip[name] then
			weapon.buttons = weapon.buttons or {}
			weapon.buttons[#weapon.buttons + 1] = {
				label = label,
				action = function(slot)
					TriggerEvent('vision_weaponhub:openFromInventory', slot)
				end,
			}
		end
	end
end

return data
```

What the button does is set by `Config.InventoryButton` (see [General settings](/visionstore-docs/scripts/weaponhub/configuration/general.md#inventory-button)): by default it only works next to a workbench, and sends the player a waypoint otherwise.
{% endstep %}

{% step %}

### Start it in server.cfg

Add it **after** your framework, ox\_inventory and target:

```properties
ensure ox_lib
ensure ox_inventory
ensure ox_target          # or qb-target, optional
ensure vision_weaponhub

# admins: /weaponhub and /weaponhub_here
add_ace group.admin vision_weaponhub.admin allow
```

Admins are also recognised through the groups in `Config.Admin.groups` (see [General settings](/visionstore-docs/scripts/weaponhub/configuration/general.md#admins)).
{% endstep %}

{% step %}

### Check your framework

Open `config/config.lua`:

```lua
Config.Framework = 'auto'       -- 'auto' | 'qbx' | 'qb' | 'esx' | 'ox' | 'standalone'
Config.Target = 'auto'          -- 'auto' | 'ox_target' | 'qb-target' | 'textui'
```

With `auto`, the first running one is used: qbx\_core, qb-core, es\_extended, ox\_core, then standalone. Here is what the hub uses on each:

{% tabs %}
{% tab title="Qbox" %}

* **Jobs / gangs:** every job and gang the character holds (multi-job).
* **Money:** `cash` and `bank`.
* **Admins:** the ace `admin` / `group.admin` and your `Config.Admin.groups`.
  {% endtab %}

{% tab title="QBCore" %}

* **Jobs / gangs:** the player's job and gang.
* **Money:** `cash` and `bank`.
* **Admins:** `QBCore.Functions.HasPermission` with `Config.Admin.groups`.
  {% endtab %}

{% tab title="ESX" %}

* **Jobs:** the player's job.
* **Money:** the `money` account (cash) and `bank`.
* **Admins:** `xPlayer.getGroup()` must be in `Config.Admin.groups`.
  {% endtab %}

{% tab title="ox\_core" %}

* **Jobs:** the character's groups.
* **Money:** cash is the ox\_inventory `money` item, bank is the character's account.
* **Admins:** aces.
  {% endtab %}

{% tab title="Standalone" %}

* **Jobs:** the ace `vision_weaponhub.job.<name>` (grade 0), or ox\_inventory's own groups.
* **Money:** the ox\_inventory `money` item, for both cash and bank.
* **Admins:** aces.

```properties
add_ace identifier.license:abc123 vision_weaponhub.job.police allow
```

The console prints `no framework found: running standalone` on start.
{% endtab %}
{% endtabs %}

Every framework also accepts the ace `vision_weaponhub.admin`.
{% endstep %}

{% step %}

### Restart and test

Restart the server (or `ensure vision_weaponhub` and `restart ox_inventory`) and watch the console for warnings. Then follow the [Quick start](/visionstore-docs/scripts/weaponhub/quick-start.md).
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**Updating ox\_inventory** replaces `data/weapons.lua`. Paste the items (step 2) and the button (step 3) again afterwards. The images in `web/images` stay unless you replace that folder.
{% 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/weaponhub/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.