> 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/guides/add-on-weapons.md).

# Add-on weapons

Turn an add-on weapon pack into config entries with one command, and give every part an item.

Base-game weapons need nothing. For an add-on pack, the included helper `tools/addon-to-config.js` reads the pack's `.meta` files and writes the `config/weapons.lua` entries for every weapon in it: slots, factory parts, tint palette, group, magazine size and weapon-wheel stats. Nothing in the resource is changed.

{% hint style="info" %}
The weapon itself must already be an ox\_inventory weapon item (`Weapons = { ['WEAPON_RAVEN_AR'] = { ... } }` in `ox_inventory/data/weapons.lua`), as for any add-on weapon on ox\_inventory.
{% endhint %}

## With the helper

{% stepper %}
{% step %}

### Install Node.js

The helper needs [Node.js](https://nodejs.org) 16 or newer, on the PC where you run it.
{% endstep %}

{% step %}

### Run it on the pack

From the `vision_weaponhub` folder:

```bash
node tools/addon-to-config.js "C:/server/resources/[weapons]/my_weapon_pack" --ox "C:/server/resources/[ox]/ox_inventory/data/weapons.lua"
```

* Give one or more pack folders. Every `*.meta` file inside them is read.
* `--ox` (optional) checks which parts already have an ox\_inventory item.
  {% endstep %}

{% step %}

### Paste the output

| File                           | What to do with it                                                                                |
| ------------------------------ | ------------------------------------------------------------------------------------------------- |
| `tools/out/addon_weapons.lua`  | Paste the entries inside `Config.Weapons = { ... }` in `config/weapons.lua`                       |
| `tools/out/addon_ox_items.lua` | With `--ox`: every part no item can fit yet, with the item to add it to, or a ready-made new item |
| {% endstep %}                  |                                                                                                   |

{% step %}

### Restart

`restart ox_inventory` if you changed items, then `restart vision_weaponhub`. Any part that still has no item is printed in the server console.
{% endstep %}
{% endstepper %}

Example output:

```lua
-- my_weapon_pack/meta/raven_ar/raven_ar_weapons.meta
['WEAPON_RAVEN_AR'] = {
    group = 'rifle',
    clip = 30,
    hud = { damage = 32, speed = 72, capacity = 40, accuracy = 45, range = 45 },
    optic = { bone = 'WAPScop', 'raven_ar_scope2', factory = 'raven_ar_scope1' },
    muzzle = { bone = 'WAPSupp', 'raven_ar_supp', 'raven_ar_muzzle2', factory = 'raven_ar_muzzle1' },
    underbarrel = { bone = 'WAPGrip', 'raven_ar_afgrip' },
    magazine = { bone = 'WAPClip', 'raven_ar_mag2', factory = 'raven_ar_mag1' },
    tactical = { bone = 'WAPFlshLasr', 'raven_ar_flsh' },
    finish = { bone = 'Gun_Root', 'raven_ar_camo1', 'raven_ar_camo2' },
},
```

{% hint style="success" %}
Tested on a 30-weapon pack: 158 slots and 176 parts, written in under a second.
{% endhint %}

## By hand

Prefer to write it yourself? A weapon takes a few lines in `config/weapons.lua`:

```lua
['WEAPON_MYRIFLE'] = {
    tints = 'mk2',
    optic = { 'COMPONENT_MYRIFLE_SCOPE' },
    magazine = { 'COMPONENT_MYRIFLE_CLIP_02', factory = 'COMPONENT_MYRIFLE_CLIP_01' },
    finish = { 'COMPONENT_MYRIFLE_CAMO' },
},
```

Every key is explained in [Weapons](/visionstore-docs/scripts/weaponhub/configuration/weapons.md#add-on-weapons).

## Giving a part an item

A part can only be fitted when an ox\_inventory item resolves to it. You have two options.

{% tabs %}
{% tab title="Add it to an existing item" %}
Put the component name in the item's `client.component` list in `ox_inventory/data/weapons.lua`:

```lua
['at_scope_medium'] = {
    label = 'Medium Scope',
    type = 'sight',
    client = {
        component = {
            `COMPONENT_AT_SCOPE_MEDIUM`,
            `COMPONENT_AT_SCOPE_MEDIUM_MK2`,
            `COMPONENT_MYRIFLE_SCOPE`,      -- added
        },
    },
},
```

One item serves every weapon.
{% endtab %}

{% tab title="Make a new item" %}

```lua
['at_myrifle_holo'] = {
    label = 'MyRifle Holo Sight',
    type = 'sight',
    weight = 150,
    client = { component = { `COMPONENT_MYRIFLE_HOLO` }, usetime = 2500 },
},
```

Add an image `at_myrifle_holo.png` to `ox_inventory/web/images/`.
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
On one weapon, an item can only ever be **one** part: the first in its list that the weapon takes. If a weapon has two scopes, give the second one its own item. `tools/out/addon_ox_items.lua` handles this for you.
{% endhint %}

## Extra tints

If the pack ships more tints than GTA's 8 or 32, describe them in a palette: see [Your own palettes](/visionstore-docs/scripts/weaponhub/configuration/colors.md#your-own-palettes).


---

# 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/guides/add-on-weapons.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.