### createAndLoadNewGun

Source: https://wiki.lorenzo0111.me/qualityarmory/developers/api

Creates a new gun configuration file and immediately loads it into the server.

```APIDOC
## createAndLoadNewGun(String name, String displayname, Material material, int id, WeaponType type, WeaponSounds sound, boolean hasIronSights, String ammotype, int damage, int maxBullets, int cost)

### Description
Creates a new gun configuration file (.yml) in the plugins/QualityArmory/newGuns/ directory and immediately attempts to load it into the running server.

### Parameters
- **name** (String) - Internal name for the gun.
- **displayname** (String) - In-game display name.
- **material** (Material) - Base Material for the item.
- **id** (int) - CustomModelData or Durability value.
- **type** (WeaponType) - The WeaponType enum value.
- **sound** (WeaponSounds) - The WeaponSounds enum value.
- **hasIronSights** (boolean) - Whether the gun supports aiming down sights.
- **ammotype** (String) - Internal name of the required Ammo item.
- **damage** (int) - Base damage per bullet.
- **maxBullets** (int) - Magazine capacity.
- **cost** (int) - Price in the /qa shop.

### Returns
- **GunYML** - Object representing the created configuration.
```

--------------------------------

### createNewGunYML

Source: https://wiki.lorenzo0111.me/qualityarmory/developers/api

Creates a new gun configuration object without saving or loading it automatically.

```APIDOC
## createNewGunYML(String name, String displayname, Material material, int id, WeaponType type, WeaponSounds sound, boolean hasIronSights, String ammotype, int damage, int maxBullets, int cost)

### Description
Creates a GunYML object representing a new gun configuration but does not automatically save or load it.

### Parameters
- **name** (String) - Internal name for the gun.
- **displayname** (String) - In-game display name.
- **material** (Material) - Base Material for the item.
- **id** (int) - CustomModelData or Durability value.
- **type** (WeaponType) - The WeaponType enum value.
- **sound** (WeaponSounds) - The WeaponSounds enum value.
- **hasIronSights** (boolean) - Whether the gun supports aiming down sights.
- **ammotype** (String) - Internal name of the required Ammo item.
- **damage** (int) - Base damage per bullet.
- **maxBullets** (int) - Magazine capacity.
- **cost** (int) - Price in the /qa shop.

### Returns
- **GunYML** - Object representing the potential configuration.
```

--------------------------------

### Configure DefaultResourcepack for Auto-Detection

Source: https://wiki.lorenzo0111.me/qualityarmory/config/resourcepack

Defines version-specific resource pack URLs with a required fallback key '0'. Requires ViaVersion to function correctly.

```yaml
# ... other config settings ...

useDefaultResourcepack: true

DefaultResourcepack:
  # Fallback/Default URL (REQUIRED)
  '0': 'https://your-default-pack-url.zip'
  # Pack for 1.19.0 up to (but not including) 1.20.0
  '19': 'https://your-1.19.x-pack-url.zip'
  # Pack specifically for 1.20.0 up to (but not including) 1.20.2
  '20': 'https://your-1.20.0-pack-url.zip'
  # Pack for 1.20.2 up to (but not including) 1.21.0
  '20-2': 'https://your-1.20.2-pack-url.zip'
  # Pack for 1.21.0 and newer (until a higher version is added)
  '21': 'https://your-1.21.x-pack-url.zip'

# ... other config settings ...
```

--------------------------------

### Define Model Placeholders for 1.14+

Source: https://wiki.lorenzo0111.me/qualityarmory/items/model

Configuration values for mapping custom_model_data IDs and model filenames.

```yaml
ID:
This should match the custom_model_data value set in your plugin/mod (e.g., in the YAML config).

MODEL:
Name of your model file (no .json extension).
```

--------------------------------

### sendResourcepack

Source: https://wiki.lorenzo0111.me/qualityarmory/developers/api

Sends the server resource pack to a player with an optional warning.

```APIDOC
## sendResourcepack(Player player, boolean warning)

### Description
Sends the appropriate server resource pack to the player after a configured delay. Uses the multi-version system if enabled.

### Parameters
- **player** (Player) - Required - The player to send the pack to.
- **warning** (boolean) - Required - If true, sends warning messages/titles before sending the pack prompt.
```

--------------------------------

### Define Model Placeholders for 1.9–1.13

Source: https://wiki.lorenzo0111.me/qualityarmory/items/model

Configuration values for calculating damage IDs and specifying model filenames.

```yaml
ID:
Calculated as 0.0161 + (0.006 * index)
(e.g., ID 27 → 0.0167, ID 28 → 0.0173, etc.)

MODEL:
The model file name (without .json)
```

--------------------------------

### Configure QualityArmory Dependency in Build Systems

Source: https://wiki.lorenzo0111.me/qualityarmory/developers/dependency

Add the CodeMC repository and QualityArmory dependency to your project's build configuration.

```xml
<repository>
    <id>codemc-repo</id>
    <url>https://repo.codemc.io/repository/maven-public/</url>
</repository>

<dependency>
    <groupId>me.zombie_striker</groupId>
    <artifactId>QualityArmory</artifactId>
    <version>VERSION</version>
    <scope>provided</scope>
</dependency>
```

```gradle
repositories {
    maven {
        name = "codemc-repo"
        url = "https://repo.codemc.io/repository/maven-public/"
    }
}

dependencies {
    compileOnly 'me.zombie_striker:QualityArmory:VERSION'
}
```

```gradle
repositories {
    maven {
        name = "codemc-repo"
        url = uri("https://repo.codemc.io/repository/maven-public/")
    }
}

dependencies {
    compileOnly("me.zombie_striker:QualityArmory:VERSION")
}
```

--------------------------------

### giveOrDrop

Source: https://wiki.lorenzo0111.me/qualityarmory/developers/api

Gives an item to an entity or drops it if the inventory is full.

```APIDOC
## giveOrDrop(HumanEntity entity, ItemStack item)

### Description
Gives the specified ItemStack to the entity. If their inventory is full, drops the item at their location instead.

### Parameters
- **entity** (HumanEntity) - Required - The entity to receive the item.
- **item** (ItemStack) - Required - The item to give.
```

--------------------------------

### Configure block acceleration reduction

Source: https://wiki.lorenzo0111.me/qualityarmoryvehicles/configuration

Define a list of blocks and their corresponding acceleration reduction values using YAML format.

```yaml
blockAccelerationReduction:
  BLOCK_NAME: 1.0
```

--------------------------------

### Define a Shop Category

Source: https://wiki.lorenzo0111.me/qualityarmory/config/menu

Add a new category to the shop by defining its name, icon, and filter type in the categories section.

```yaml
categories:
  shop:
    explosives:
      name: "&cExplosives"
      icon:
        type: "TNT"
        name: "&c&lExplosives"
        lore:
          - "&7All explosive weapons"
      filter: "MISC" # must be one of: ALL, GUN, AMMO, ARMOR, MISC
```

--------------------------------

### getMaxPagesForGUI()

Source: https://wiki.lorenzo0111.me/qualityarmory/developers/api

Calculates the number of pages needed to display all registered QA items.

```APIDOC
## getMaxPagesForGUI()

### Description
Calculates the number of pages needed to display all registered QA items in the default shop/GUI layout (5 rows of 9 items per page).
```

--------------------------------

### repeat(String string, int times)

Source: https://wiki.lorenzo0111.me/qualityarmory/developers/api

Utility method to repeat a given string multiple times.

```APIDOC
## repeat(String string, int times)

### Description
A simple utility method to repeat a given string multiple times.

### Parameters
- **string** (String) - Required - The string to repeat.
- **times** (int) - Required - The number of times to repeat the string.
```

--------------------------------

### Define a Custom Decorative Item

Source: https://wiki.lorenzo0111.me/qualityarmory/config/menu

Map a custom symbol used in the menu structure to a specific item definition.

```yaml
items:
  custom:
    "*":
      type: "GRAY_STAINED_GLASS_PANE"
      name: "&r"
      lore: []
```

--------------------------------

### Ammo Management Methods

Source: https://wiki.lorenzo0111.me/qualityarmory/developers/api

Methods for querying, adding, and removing ammo from player inventories.

```APIDOC
## Ammo Management

### Methods
- **getAmmoInInventory(Player player, Ammo a, [boolean ignoreBag])**: Returns total ammo count.
- **getAmmoInBag(Player player, Ammo a)**: Returns ammo count stored only in AmmoBags.
- **addAmmoToInventory(Player player, Ammo a, int amount)**: Adds ammo to inventory; returns true if successful.
- **removeAmmoFromInventory(Player player, Ammo a, int amount)**: Removes ammo from inventory; returns true if successful.
- **getBulletsInHand(Player player)**: Returns ammo count from NBT data of held gun.
```

--------------------------------

### Configure Single Custom Resource Pack URL

Source: https://wiki.lorenzo0111.me/qualityarmory/config/resourcepack

Forces all players to use a single resource pack URL regardless of their Minecraft version.

```yaml
# ... other config settings ...

useDefaultResourcepack: false
DefaultResourcepackOverride: true

DefaultResourcepack: 'https://your-single-custom-pack-url.zip'

# ... other config settings ...
```

--------------------------------

### getIronSightsItemStack()

Source: https://wiki.lorenzo0111.me/qualityarmory/developers/api

Returns the specific ItemStack used to represent the aiming-down-sights view.

```APIDOC
## getIronSightsItemStack()

### Description
Returns the specific `ItemStack` used to represent the aiming-down-sights view.
```

--------------------------------

### Item Retrieval Methods

Source: https://wiki.lorenzo0111.me/qualityarmory/developers/api

Methods for retrieving collections or individual instances of registered items.

```APIDOC
## getGuns()
Returns an Iterator<Gun> for all loaded guns.

## getAmmo()
Returns an Iterator<Ammo> for all loaded ammo types.

## getMisc()
Returns an Iterator<CustomBaseObject> for all loaded miscellaneous items.

## getArmor()
Returns an Iterator<ArmorObject> for all loaded armor pieces.

## getCustomItems()
Returns an Iterator<CustomBaseObject> containing all loaded guns, ammo, armor, and misc items combined.

## getCustomItemsAsList()
Returns a List<CustomBaseObject> containing all loaded guns, ammo, armor, and misc items combined.

## getGun(ItemStack is)
Returns the Gun object associated with the given ItemStack, or null if it's not a QA gun.

## getAmmo(ItemStack is)
Returns the Ammo object associated with the given ItemStack, or null if it's not QA ammo.

## getArmor(ItemStack is)
Returns the ArmorObject associated with the given ItemStack, or null if it's not QA armor.

## getMisc(ItemStack is)
Returns the CustomBaseObject associated with the given ItemStack, or null if it's not a QA misc item.

## getCustomItem(ItemStack is)
Returns the CustomBaseObject associated with the given ItemStack, or null if it's not a QA item.

## getCustomItem(Material material, int data, int variant)
Returns the CustomBaseObject matching the specified Material, CustomModelData/Durability, and Variant, or null.

## getCustomItem(MaterialStorage material)
Returns the CustomBaseObject matching the specified MaterialStorage, or null.

## getGunByName(String name)
Returns the Gun object with the matching internal name, or null.

## getAmmoByName(String name)
Returns the Ammo object with the matching internal name, or null.

## getArmorByName(String name)
Returns the ArmorObject with the matching internal name, or null.

## getMiscByName(String name)
Returns the CustomBaseObject (Misc) with the matching internal name, or null.

## getCustomItemByName(String name)
Returns the CustomBaseObject (any type) with the matching internal name, or null.

## getGunInHand(@NotNull HumanEntity entity)
Returns the Gun the player is effectively holding, or null.
```

--------------------------------

### Configure Custom Model Data for Minecraft 1.14+

Source: https://wiki.lorenzo0111.me/qualityarmory/items/model

Use the custom_model_data tag in item JSON files to register new models in modern Minecraft versions.

```json
{
    "predicate": {
        "custom_model_data": 66
    },
    "model": "item/stengun"
},
{
    "predicate": {
        "custom_model_data": 67
    },
    "model": "item/m32a1"
},
{
    "predicate": {
        "custom_model_data": 68
    },
    "model": "item/aiming"
}
```

```json
{
    "predicate": {
        "custom_model_data": ID
    },
    "model": "item/MODEL"
}
```

--------------------------------

### getCustomItemAsItemStack(CustomBaseObject obj)

Source: https://wiki.lorenzo0111.me/qualityarmory/developers/api

Returns a fresh ItemStack representation of the given CustomBaseObject.

```APIDOC
## getCustomItemAsItemStack(CustomBaseObject obj)

### Description
Returns a fresh `ItemStack` representation of the given `CustomBaseObject`. Returns `null` if the input object is `null`.

### Parameters
- **obj** (CustomBaseObject) - Required - The custom object to convert.
```

--------------------------------

### Define Plugin Dependency in plugin.yml

Source: https://wiki.lorenzo0111.me/qualityarmory/developers/dependency

Specify QualityArmory as a required or optional dependency in your plugin.yml file to control load order.

```yaml
# Use this if QualityArmory is required
depend: [QualityArmory]
# Use this if QualityArmory is optional
softdepend: [QualityArmory]
```

--------------------------------

### Configure Model Predicate for Minecraft 1.9–1.13

Source: https://wiki.lorenzo0111.me/qualityarmory/items/model

Use this structure to define custom model predicates within the diamond_axe.json file for older Minecraft versions.

```json
{
    "predicate": {
        "damaged": 0,
        "damage": 0.0161
    },
    "model": "item/aa12"
},
```

```json
{
    "predicate": {
        "damaged": 0,
        "damage": ID
    },
    "model": "item/MODEL"
}
```

--------------------------------

### sendHotbarGunAmmoCount

Source: https://wiki.lorenzo0111.me/qualityarmory/developers/api

Displays ammo status above the player's hotbar.

```APIDOC
## sendHotbarGunAmmoCount(Player p, CustomBaseObject gun, ItemStack usedItem, boolean reloading, [int currentAmountInGun], [int maxAmount])

### Description
Sends the ammo count/status message above the player's hotbar. Supports automatic detection or manual specification of ammo counts.

### Parameters
- **p** (Player) - Required - The player to send the message to.
- **gun** (CustomBaseObject) - Required - The Gun or AttachmentBase object.
- **usedItem** (ItemStack) - Required - The item in hand.
- **reloading** (boolean) - Required - Reloading status.
- **currentAmountInGun** (int) - Optional - Current ammo count.
- **maxAmount** (int) - Optional - Maximum ammo capacity.
```

--------------------------------

### getCustomItemAsItemStack(String name)

Source: https://wiki.lorenzo0111.me/qualityarmory/developers/api

Retrieves a CustomBaseObject by its internal name and returns a fresh ItemStack representation.

```APIDOC
## getCustomItemAsItemStack(String name)

### Description
Retrieves a `CustomBaseObject` by its internal name and returns a fresh `ItemStack` representation of it.

### Parameters
- **name** (String) - Required - The internal name of the custom item.
```

--------------------------------

### allowGunsInRegion

Source: https://wiki.lorenzo0111.me/qualityarmory/developers/api

Checks if gun usage is permitted at a specific location.

```APIDOC
## allowGunsInRegion(Location loc)

### Description
Checks with registered protection hooks (like WorldGuard) if PvP or gun usage is allowed at the specified location.

### Parameters
- **loc** (Location) - Required - The Location to check.

### Returns
- **boolean** - true if allowed, false otherwise.
```

--------------------------------

### Item Type Validation Methods

Source: https://wiki.lorenzo0111.me/qualityarmory/developers/api

Methods to check the classification of an ItemStack within the QualityArmory system.

```APIDOC
## isCustomItem(ItemStack is)

### Description
Returns true if the ItemStack is any registered QA item (Gun, Ammo, Armor, Misc, or registered Expansion item).

## isCustomItem(ItemStack is, int dataOffset)

### Description
Checks if the item would be a custom item if its CustomModelData/Durability were offset by dataOffset.

## isCustomItemNextId(ItemStack is)

### Description
Checks if an item with the next sequential CustomModelData/Durability value (same material) is a registered QA item.

## isGun(ItemStack is)

### Description
Returns true if the ItemStack is a registered QA gun.

## isAmmo(ItemStack is)

### Description
Returns true if the ItemStack is a registered QA ammo type.

## isArmor(ItemStack is)

### Description
Returns true if the ItemStack is a registered QA armor piece.

## isMisc(ItemStack is)

### Description
Returns true if the ItemStack is a registered QA miscellaneous item.

## isAmmoBag(ItemStack is)

### Description
Returns true if the ItemStack is a registered QA miscellaneous item that is specifically an AmmoBag.

## isIronSights(ItemStack is)

### Description
Returns true if the ItemStack represents the temporary item shown when aiming down sights.
```

--------------------------------

### registerNewUsedExpansionItem

Source: https://wiki.lorenzo0111.me/qualityarmory/developers/api

Registers items used by expansion packs to prevent ID conflicts.

```APIDOC
## registerNewUsedExpansionItem

### Description
Registers a Material/ID/Variant combination as being used by an expansion pack or addon.

### Overloads
- **registerNewUsedExpansionItem(Material used, int id)**: Assumes variant 0.
- **registerNewUsedExpansionItem(Material used, int id, int var)**: Explicitly defines variant.
- **registerNewUsedExpansionItem(MaterialStorage ms)**: Uses a MaterialStorage object.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.