> 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/configuration/weapons.md). # Weapons Add-on weapons, extra slots, descriptions, calibers and the blacklist in config/weapons.lua. Every base-game weapon is already in: **95 weapons and 414 parts**, with every attachment slot, factory part and tint palette. You only need `config/weapons.lua` for add-on weapons, extra descriptions and to hide weapons. {% hint style="success" %} Got an add-on pack? Let the helper write these entries for you: [Add-on weapons](/visionstore-docs/scripts/weaponhub/guides/add-on-weapons.md). {% endhint %} ## How it fits together Three things decide what a player can fit on a gun: 1. **The weapon's attach points.** The parts GTA allows on that model, grouped by bone (`WAPScop`, `WAPSupp`, `WAPClip`...). Only one part can sit on a bone. Some parts are fitted by GTA itself (the *factory* part, for example the standard magazine). 2. **ox\_inventory items.** An attachment is an item such as `at_scope_medium`. Its `client.component` list in `ox_inventory/data/weapons.lua` names the GTA components it can become. 3. **ox\_inventory's rule:** when a gun is drawn, an item becomes the **first** component in its list that this weapon takes. So `at_scope_medium` is the medium scope on a carbine rifle and the MK II medium scope on a carbine MK II. The hub reads all three, so what it offers is exactly what ox\_inventory fits when the gun is drawn. ## Add-on weapons Inside `Config.Weapons = { ... }`: ```lua Config.Weapons = { ['WEAPON_MYRIFLE'] = { tints = 'mk2', optic = { 'COMPONENT_MYRIFLE_SCOPE', 'COMPONENT_MYRIFLE_HOLO' }, magazine = { 'COMPONENT_MYRIFLE_CLIP_02', factory = 'COMPONENT_MYRIFLE_CLIP_01' }, muzzle = { { component = 'COMPONENT_MYRIFLE_SUPP', item = 'at_suppressor_heavy' } }, finish = { 'COMPONENT_MYRIFLE_CAMO' }, }, } ``` | Key | Meaning | | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `optic`, `muzzle`, `barrel`, `underbarrel`, `magazine`, `stock`, `tactical`, `finish` | One slot of that category: a list of GTA component names (as in the pack's meta files) | | `factory = '...'` | The part GTA fits by itself. It needs no item and shows as "Factory part" | | `bone = 'WAPScop'` | The attach bone. Optional: with it, the callout points at the real spot on the model | | `{ component = '...', item = '...' }` | Pin a part to one item when several items could fit it. The item's `client.component` list must contain the part | | `tints` | `'standard'` (8), `'mk2'` (32) or a palette of your own (see [Tints and camo colours](/visionstore-docs/scripts/weaponhub/configuration/colors.md)) | | `group` | `'pistol'`, `'smg'`, `'rifle'`, `'mg'`, `'shotgun'`, `'sniper'`, `'heavy'`, `'melee'`: the label and description shown | | `clip` | Magazine size shown | | `hud` | `{ damage, speed, capacity, accuracy, range }` (0 to 100), the weapon-wheel stats | | `slots` | More than one slot of a category (see below) | The weapon itself must be an ox\_inventory weapon item (`Weapons = { ['WEAPON_MYRIFLE'] = { ... } }`), as for any add-on weapon on ox\_inventory. ### Camo colours on add-on parts Parts in a `finish` slot whose name contains `_CAMO` take MK II camo colours automatically. Mark any other part with `livery = true`: ```lua finish = { { component = 'COMPONENT_MYRIFLE_SKIN', livery = true } }, ``` ### Two slots of the same category For example a scope and a separate rail sight: ```lua ['WEAPON_MYRIFLE'] = { optic = { bone = 'WAPScop', 'COMPONENT_MYRIFLE_SCOPE' }, slots = { { category = 'optic', bone = 'WAPScop_2', 'COMPONENT_MYRIFLE_RDS' }, }, }, ``` ### Extra parts on base-game weapons An entry for a base-game weapon **adds** parts, merged into the existing slot of that category: ```lua ['WEAPON_CARBINERIFLE'] = { optic = { 'COMPONENT_MY_ADDON_SCOPE' } }, ``` ## Slots and categories | Category | Tab in the hub | Typical bones | Contains | | ------------- | ------------------ | ------------------------ | ------------------------------------------------------------- | | `optic` | Optics | `WAPScop`, `WAPScop_2` | Scopes, sights, rails | | `muzzle` | Muzzle | `WAPSupp`, `WAPSupp_2` | Suppressors, muzzle brakes, compensators | | `barrel` | Barrel | `WAPBarrel` | Heavy barrels | | `underbarrel` | Underbarrel | `WAPGrip`, `WAPGrip_2` | Grips | | `magazine` | Magazine | `WAPClip` | Extended clips, drums, MK II special ammunition | | `stock` | Stock | `WAPStck` | Stocks | | `tactical` | Flashlight & Laser | `WAPFlshLasr`, `WAPFlsh` | Flashlights, rail covers | | `finish` | Finish | `gun_root`, `WAPCamo` | Luxury and special finishes, MK II camos, MK II pistol slides | Finish slots are labelled **Special Finish**, **Camo** and **Slide**. Points that share a bone are one slot: fitting a part replaces whatever sat there, and GTA's factory part comes back when it is removed. ## Descriptions and extra stats ```lua Config.WeaponInfo = { ['WEAPON_CARBINERIFLE'] = { description = 'Standard issue patrol rifle.', caliber = '5.56x45mm', stats = { recoil = 62, mobility = 58 }, }, } ``` Damage, fire rate, accuracy, range and capacity come from the game (the weapon-wheel values). GTA has no recoil or mobility value, so those bars only appear when you set them (0 to 100). Without a `description`, the weapon group's text from the locale file is shown. `Config.WeaponInfo` is empty by default. ## Calibers The caliber shown for each ox\_inventory ammo item: ```lua Config.Calibers = { ['ammo-9'] = '9x19mm', ['ammo-45'] = '.45 ACP', ['ammo-rifle'] = '5.56x45mm', ['ammo-rifle2'] = '7.62x39mm', ['ammo-shotgun'] = '12 Gauge', ['ammo-sniper'] = '7.62x51mm', ['ammo-heavysniper'] = '.50 BMG', ['ammo-22'] = '.22 LR', ['ammo-38'] = '.38 Special', ['ammo-44'] = '.44 Magnum', ['ammo-50'] = '.50 AE', ['ammo-musket'] = '.69 Musket Ball', ['ammo-flare'] = 'Flare', ['ammo-emp'] = 'EMP Charge', ['ammo-firework'] = 'Firework', ['ammo-rocket'] = 'Rocket', ['ammo-grenade'] = '40mm Grenade', } ``` A `caliber` in `Config.WeaponInfo` wins over this list. ## Blacklist Weapons that never open in the hub: ```lua Config.Blacklist = { WEAPON_PETROLCAN = true, WEAPON_HAZARDCAN = true, WEAPON_FERTILIZERCAN = true, WEAPON_HACKINGDEVICE = true, WEAPON_METALDETECTOR = true, WEAPON_DIGISCANNER = true, WEAPON_FIREEXTINGUISHER = true, } ``` Throwables (`throwable = true` in ox\_inventory) never open in the hub either. {% hint style="info" %} Restart the resource after editing. Mistakes such as an unknown category, a palette that doesn't exist, or a part no item can fit are printed in the server console. {% 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/configuration/weapons.md?ask=&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.