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

# 📦 Weapon Pack Installation Guide

Multiple Weapons. One Resource. Simple Installation.

***

**Multiple Weapons. One Resource. Simple Installation.**

Welcome to the official **StarBoyCustoms Weapon Pack Installation Guide**.

This guide will walk you through installing your purchased weapon pack, setting up inventory icons, configuring your FiveM server, and troubleshooting common installation issues.

Our weapon packs are designed to make adding multiple custom weapons to your server as straightforward as possible.

**🚀 DOWNLOAD. INSTALL. CONFIGURE. PLAY.**

***

### 📦 1. Overview

StarBoyCustoms Weapon Packs contain multiple custom weapons bundled together into a single FiveM resource.

Each pack is designed for straightforward installation while keeping its required files organised in one location.

Depending on the purchased product, your download may include:

* 🔫 **Multiple Custom Weapons** — A selection of weapons included in your purchased pack.
* 🖼️ **Inventory Icons** — Pre-named icons for supported inventory systems.
* ⚙️ **Weapon Metadata** — Files required to register and configure the included weapons.
* 🎨 **Custom Models & Textures** — Weapon models, materials, and visual assets.
* 📁 **Additional Resource Files** — Supporting files required for the pack.
* 📄 **Resource Manifest** — The `fxmanifest.lua` file used by FiveM.

#### 🎒 Inventory Compatibility

Supplied inventory icons are pre-named for **ox\_inventory** and may also be used with QBCore, ESX, or other inventory systems.

Additional inventory registration may be required depending on your server configuration.

> 💡 **Important:** This guide covers weapon packs supplied as a single resource. If your purchased collection contains multiple individual resource folders, follow its product-specific installation instructions instead.

***

### 🚀 2. Weapon Pack Installation

Follow these steps to install your purchased Weapon Pack.

#### Step 1 — Download Your Weapon Pack

Download your purchased resource from the official **StarBoyCustoms Tebex Store**.

Extract the downloaded `.zip` archive using one of the following:

* Windows Extract
* WinRAR
* 7-Zip

Once extracted, locate the complete weapon pack resource folder.

**Keep the original folder structure intact.**

#### Step 2 — Upload the Weapon Pack

Navigate to your FiveM server's resource directory:

```
resources/
```

Upload the complete weapon pack folder.

We recommend organising custom weapons inside a dedicated category folder.

**Recommended folder structure:**

```
resources/
└── [weapons]/
    └── weaponpackname/
        ├── fxmanifest.lua
        ├── stream/
        ├── data/
        └── ...
```

The actual folder structure may vary depending on the purchased pack.

**⚠️ Do not split the pack into separate resources unless the product documentation specifically instructs you to do so.**

#### Step 3 — Configure server.cfg

Open your server's configuration file:

```
server.cfg
```

Add the following line:

```cfg
ensure weaponpackname
```

Replace `weaponpackname` with the exact name of your purchased resource folder.

**Example:**

```cfg
ensure starboy_weaponpack
```

> ⚠️ **Important:** The resource name must match your actual folder name exactly, including capital letters where applicable.

#### Step 4 — Restart Your Server

Save your `server.cfg` and restart your FiveM server.

Alternatively, use your server console:

```cfg
refresh
ensure weaponpackname
```

Run these as two separate commands.

Check your server console to confirm that the resource starts without errors.

✅ **Your weapon pack resource should now be loaded.**

Some weapons may still require inventory registration or ammunition configuration before players can use them.

***

### 🖼️ 3. Inventory Icon Installation

StarBoyCustoms Weapon Packs include inventory icons intended to help identify the included weapons.

The supplied icons are pre-named for ox\_inventory, so renaming should not normally be required.

#### 🎒 ox\_inventory

**Step 1 — Open Your Inventory Resource**

Locate your installed `ox_inventory` folder.

**Step 2 — Navigate to the Images Directory**

```
ox_inventory/web/images/
```

**Step 3 — Upload Your Icons**

Copy all supplied PNG inventory icons into the images folder.

Keep the original filenames unless your inventory configuration requires a different naming convention.

**Step 4 — Verify Your Weapon Registration**

For weapons that require registration, open:

```
ox_inventory/data/weapons.lua
```

Ensure each custom weapon uses the correct identifier from its supplied metadata.

**Example:**

```lua
['WEAPON_YOURWEAPON'] = {
    label = 'StarBoyCustoms Weapon',
    weight = 1000,
    durability = 0.1,
    -- ammoname = 'YOUR_AMMO_ITEM',
},
```

Replace `WEAPON_YOURWEAPON` with the actual weapon identifier.

Set `ammoname` to the correct ammunition item where required.

> 💡 **Important:** Inventory icons and weapon registration are separate requirements. Uploading an icon alone does not register a weapon.

***

### ⚙️ 4. QBCore, ESX & Custom Inventories

If your server uses a different inventory system, the supplied icons may still be compatible.

#### QBCore Inventories

1. Locate your inventory's image directory.
2. Upload the supplied PNG icons.
3. Register the custom weapons according to your inventory's requirements.
4. Confirm the item names and image filenames match.
5. Configure ammunition and other required settings.

Some QBCore inventories may require shared item definitions or additional weapon registration.

#### ESX Inventories

1. Identify whether your server uses native ESX weapon loadouts or a separate inventory.
2. Follow the registration requirements of your installed system.
3. Upload inventory icons where supported.
4. Configure the supplied weapon identifiers.
5. Restart the relevant resources.

#### Custom Inventory Systems

For other inventory systems, refer to their official documentation.

**Example image filename:**

```
weaponname.png
```

**Corresponding item name:**

```
weaponname
```

The image filename should follow the convention expected by your inventory.

> ⚠️ **Important:** Inventory configuration differs between systems. Do not assume that every inventory uses identical item definitions or weapon registration methods.

***

### 📁 5. Correct Resource Structure

One of the most common installation problems is an incorrectly nested resource folder.

#### ✅ Correct Installation

```
resources/
└── [weapons]/
    └── starboy_weaponpack/
        ├── fxmanifest.lua
        ├── stream/
        └── data/
```

The resource manifest is directly inside the weapon pack folder.

#### ❌ Incorrect Installation

```
resources/
└── [weapons]/
    └── starboy_weaponpack/
        └── starboy_weaponpack/
            ├── fxmanifest.lua
            ├── stream/
            └── data/
```

The extra nested folder may prevent FiveM from recognising the resource correctly.

**Always ensure `fxmanifest.lua` is located at the root of the resource folder being started.**

***

### ⚠️ 6. Important Installation Notes

To avoid installation problems, follow these recommendations:

* ✅ Keep the original weapon pack folder name.
* ✅ Preserve the supplied folder structure.
* ✅ Keep all weapon models, textures, and metadata together.
* ✅ Do not rename supplied inventory icons unnecessarily.
* ✅ Ensure `fxmanifest.lua` is directly inside the resource folder.
* ✅ Match your `server.cfg` entry to the resource folder name.
* ✅ Install any dependencies specified by the product.
* ✅ Configure weapon identifiers and ammunition where required.
* ✅ Avoid duplicate weapon resources or inventory registrations.

**Always check your purchased pack's documentation for additional requirements.**

***

### 🧪 7. Installation Checklist

Before making your weapon pack available on your server, verify the following:

* Weapon Pack archive extracted successfully.
* Complete resource folder uploaded.
* Original file structure preserved.
* `fxmanifest.lua` located correctly.
* Correct `ensure` entry added to `server.cfg`.
* Resource starts without console errors.
* Required inventory icons installed.
* Weapon identifiers registered where necessary.
* Ammunition configured according to the supplied metadata.
* All included weapons tested in-game.

Once these checks are complete, your Weapon Pack should be ready for use.

***

### 🛠️ 8. Troubleshooting

#### ❌ Weapon Pack Isn't Loading

**Possible causes:**

* Incorrect resource folder name.
* Missing `fxmanifest.lua`.
* Incorrect `server.cfg` entry.
* Nested resource folders.

**Solutions:**

1. Check the resource folder structure.
2. Confirm `fxmanifest.lua` is present.
3. Verify the `ensure` entry.
4. Check your server console for errors.

#### ❌ Inventory Icons Aren't Showing

**Possible causes:**

* Icons placed in the wrong directory.
* Incorrect image filenames.
* Missing inventory configuration.

**Solutions:**

1. Locate your inventory's configured image folder.
2. Confirm all supplied icons are installed.
3. Check that filenames match the inventory's expected naming convention.
4. Restart or reload the inventory where required.

#### ❌ Some Weapons Are Missing

**Possible causes:**

* Incomplete resource upload.
* Missing models or metadata.
* Incorrect weapon registration.

**Solutions:**

1. Verify all original files are present.
2. Check the resource manifest.
3. Confirm the missing weapons are registered correctly.
4. Review your server console for errors.

#### ❌ Weapons Are Invisible or Missing Textures

**Possible causes:**

* Missing model or texture files.
* Incorrect resource paths.
* Incomplete installation.

**Solutions:**

1. Confirm all supplied assets are present.
2. Verify model and texture references.
3. Check the resource manifest.
4. Restart the affected resource.

#### ❌ Weapons Cannot Be Equipped

**Possible causes:**

* Missing inventory registrations.
* Incorrect weapon identifiers.
* Ammunition configuration issues.
* Conflicting weapon definitions.

**Solutions:**

1. Verify the weapon identifiers.
2. Check inventory registration requirements.
3. Confirm ammunition settings.
4. Remove duplicate or conflicting registrations.

#### ❌ Server Console Errors

Review the full error message displayed in your server console.

Check for missing dependencies, invalid resource paths, incorrectly nested folders, and incomplete uploads.

Save the error message when requesting assistance.

***

### 💬 9. Support & Assistance

Having trouble installing your StarBoyCustoms Weapon Pack?

Our official support community is available to help with installation and configuration issues.

#### Before Opening a Support Ticket

Please provide:

* 📦 Your purchased Weapon Pack name
* ⚙️ Your FiveM framework
* 🎒 Your inventory system
* ❗ Full server console error
* 📸 Screenshot of your weapon pack folder
* 🖼️ Screenshot of your inventory configuration, if applicable
* 📝 A description of the problem

Providing this information helps our support team understand your issue.

#### 🔗 Official Links

💬 **Discord Support**<br>

{% embed url="<https://discord.gg/43Fuyt6KP5>" %}

🛒 **Official Tebex Store**<br>

{% embed url="<https://starboycustoms.tebex.io>" %}

▶️ **Official YouTube**<br>

{% embed url="<https://www.youtube.com/@OfficialStarBoyCustoms>" %}

***

### 👑 Thank You for Choosing StarBoyCustoms!

We appreciate your support and hope you enjoy your new custom weapon collection.

Our goal is to make installing and managing StarBoyCustoms resources as straightforward as possible.

**📦 MULTIPLE WEAPONS. ONE RESOURCE. SIMPLE INSTALLATION.**

#### ⭐ STARBOYCUSTOMS

**YOUR SERVER. YOUR WORLD. YOUR WAY.**

👑 **PREMIUM QUALITY. THE STARBOY STANDARD.**
