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

# 🔫 Weapon Installation Guide

👑 STARBOYCUSTOMS — OFFICIAL DOCUMENTATION

**Simple Installation. Clean Configuration. Ready for FiveM.**

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

This guide will walk you through installing your purchased weapon resource, configuring inventory compatibility, and troubleshooting common issues.

Whether you're installing your first custom weapon or adding to an existing collection, follow the instructions below to get started.

***

### 📦 1. Overview

StarBoyCustoms weapons are designed for straightforward installation on compatible FiveM servers.

Depending on the purchased product, your download may include:

* 🔫 **Weapon Resource Files** — Custom models and associated files.
* 🖼️ **Inventory Icons** — PNG images for supported inventory systems, where supplied.
* ⚙️ **Weapon Metadata** — Configuration files required by the weapon.
* 📁 **Additional Assets** — Textures, components, and other necessary files.
* 📄 **Resource Manifest** — The `fxmanifest.lua` file used by FiveM.

**🎒 ox\_inventory Support**

StarBoyCustoms weapons support integration with ox\_inventory, although individual weapons may require additional configuration.

> 💡 **Important:** Always check your purchased product's documentation for specific weapon identifiers, ammunition types, and additional installation requirements.

***

### 🚀 2. Weapon Installation

#### Step 1 — Download Your Weapon

Download your purchased weapon from the official StarBoyCustoms Tebex store.

Extract the downloaded `.zip` archive using a suitable extraction tool, such as **WinRAR** or **7-Zip**.

Ensure all supplied files have been extracted successfully.

#### Step 2 — Upload the Weapon Resource

Open your FiveM server's `resources` directory.

Drag the extracted weapon resource folder into this directory.

**Example folder structure:**

```
resources/
└── weaponname/
    ├── fxmanifest.lua
    ├── stream/
    └── ...
```

Your actual resource may contain additional files or folders.

**Do not remove or rename any supplied weapon files.**

#### Step 3 — Configure server.cfg

Open your server's `server.cfg` file.

Add the following line:

```cfg
ensure weaponname
```

Replace `weaponname` with the exact name of your weapon's resource folder.

For example, if the resource folder is named `StarBoyAttachRed`, use:

```cfg
ensure StarBoyAttachRed
```

> ⚠️ **Important:** The resource name in your `server.cfg` must match the folder name exactly.

#### Step 4 — Restart Your Server

Save your configuration and restart your FiveM server.

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

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

Additional inventory or framework configuration may be required before players can obtain or equip the weapon.

***

### 🎒 3. ox\_inventory Installation

If your FiveM server uses **ox\_inventory**, you may need to register the custom weapon and install its inventory icon.

#### Step 1 — Locate Your Inventory Configuration

Navigate to:

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

Locate the weapons table.

#### Step 2 — Register Your Custom Weapon

Add an entry using the weapon identifier defined in the supplied metadata.

**Example:**

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

Replace `WEAPON_YOURWEAPON` with your purchased weapon's actual identifier.

If ammunition configuration is required, set `ammoname` to the correct ammunition item registered in your inventory.

**Do not guess the ammunition type.** Refer to the supplied weapon metadata.

> ⚙️ Weight and durability values are examples and can be adjusted to suit your server.

#### Step 3 — Install the Inventory Icon

If your weapon includes an inventory icon, navigate to:

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

Upload the supplied PNG icon.

For example, if the weapon identifier is:

```
WEAPON_YOURWEAPON
```

The corresponding inventory image would commonly be named:

```
weapon_yourweapon.png
```

The image filename must match the naming convention expected by your inventory configuration.

#### Step 4 — Apply Your Changes

Save the updated configuration.

Restart the relevant resources using your server's normal update procedure.

Test the weapon in-game to confirm:

* The weapon is recognised by ox\_inventory.
* The inventory icon displays correctly.
* The weapon can be equipped.
* Ammunition functions correctly, where applicable.

> 💡 Some inventory versions or custom configurations may require additional registration steps.

***

### ⚠️ 4. Important Installation Notes

To avoid common installation problems, follow these recommendations:

* ✅ Keep the original weapon resource folder name.
* ✅ Preserve the supplied file structure.
* ✅ Do not remove or rename weapon metadata.
* ✅ Keep all supplied models and textures together.
* ✅ Use PNG inventory icons where provided.
* ✅ Ensure your `server.cfg` contains the correct resource name.
* ✅ Register the correct weapon identifier in your inventory.
* ✅ Check for any additional dependencies or requirements.
* ✅ Avoid installing duplicate copies of the same weapon resource.

**Always refer to your product-specific documentation if additional setup is required.**

***

### 🛠️ 5. Troubleshooting

#### ❌ Weapon Isn't Loading

**Possible causes:**

* Incorrect resource folder name.
* Missing `fxmanifest.lua`.
* Incorrect `server.cfg` entry.
* Incomplete resource installation.

**Solution:**

Verify that your weapon folder contains its resource manifest and that your configuration includes:

```cfg
ensure weaponname
```

Replace `weaponname` with the actual resource folder name.

Check your server console for errors.

#### ❌ Inventory Icon Isn't Showing

**Possible causes:**

* Incorrect image filename.
* Image placed in the wrong directory.
* Missing inventory image.
* Incorrect inventory configuration.

**Solution:**

Confirm your image is installed in:

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

Check that its filename matches the inventory's expected weapon image name.

Restart the inventory resource if required.

#### ❌ Weapon Is Invisible or Missing Textures

**Possible causes:**

* Missing model or texture files.
* Incorrect metadata references.
* Incomplete resource upload.

**Solution:**

1. Confirm all supplied weapon files are present.
2. Check the resource manifest.
3. Verify that required metadata is loaded.
4. Check model and texture references.
5. Restart the affected resource.

#### ❌ Weapon Cannot Be Equipped

**Possible causes:**

* Missing inventory registration.
* Incorrect weapon identifier.
* Ammunition configuration issues.
* Conflicting weapon definitions.

**Solution:**

Verify the weapon identifier in your inventory configuration matches the supplied metadata.

Check for duplicate registrations and follow your inventory's weapon setup requirements.

#### ❌ Server Console Errors

**Solution:**

Review your server console for the exact error message.

Common issues include incorrect file paths, missing resources, invalid configuration, or incorrectly nested folders.

Keep a copy of the error message when requesting assistance.

***

### 💬 6. Support & Assistance

Need help installing your StarBoyCustoms weapon?

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

#### Before Opening a Support Ticket

Please provide:

* 🔫 Your purchased weapon name.
* ⚙️ Your FiveM framework.
* 🎒 Your inventory system.
* ❗ Relevant server console errors.
* 📸 A screenshot of your weapon resource folder.
* 📝 A brief explanation of the problem.

#### 🔗 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.

For future installation guidance, updates, and assistance, refer to our official documentation and community.

**⭐ STARBOYCUSTOMS**

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

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