Creating a gun requires many steps, from configuring the settings to creating the model.

These are all the fields used by a gun with their description:

• name: The internal, unique identifier for the weapon used in commands (e.g., /qa give cz75). It's recommended to keep this lowercase and without space

• displayname: The name shown on the item in-game. Supports standard Minecraft color codes (e.g., &6).

• id: Used with material and variant to uniquely identify the item type.

  • Minecraft 1.14+: This value corresponds to the CustomModelData tag on the item, used by resource packs to apply the correct model/texture.

  • Minecraft <1.14: This value corresponds to the item's durability/damage value, used by resource packs to apply the correct model/texture.

• variant: An additional identifier used alongside material and id. Allows creating different guns that use the same base material and id/CustomModelData but have different stats or behaviors.

• craftingRequirements: A list of materials required to craft this item using the /qa craft system. Format for each entry: 'MATERIAL_NAME,METADATA/DAMAGE_VALUE,AMOUNT'. (Metadata/Damage value is often 0 for modern versions).

• weapontype: Classifies the weapon. Primarily used for organization and potentially by other plugins or specific features (like weapon limits). Can influence default sounds if weaponsounds isn't set. Valid types are: PISTOL,SMG,RPG,RIFLE,SHOTGUN,FLAMER,SNIPER,BIG_GUN,GRENADES,SMOKE_GRENADES,FLASHBANGS,INCENDARY_GRENADES,MOLOTOV,PROXYMINES,STICKYGRENADE,MINES,MELEE,MISC,AMMO,HELMET,MEDKIT,AMMO_BAG,LAZER,BACKPACK,PARACHUTE,CUSTOM

• weaponsounds: The sound event name(s) played when the weapon is fired. Can be a single string or a list of strings for variety. If omitted, a default sound based on weapontype is used.

• enableIronSights: If true, allows the player to aim down sights. Behavior depends on IronSightsOnRightClick in config.yml. If false, right-click (or the aim key) typically triggers reload.

• ammotype: The internal name of the Ammo item required to reload and fire this weapon. Must match the name field of an ammo configuration file. If omitted or invalid, the gun might have infinite ammo implicitly.

• damage: The base amount of damage each bullet inflicts upon hitting an entity. Headshots may multiply this.

• maxbullets: The maximum number of bullets the weapon can hold in its magazine/chamber.

• price: The cost of the weapon in the /qa shop if enabled.

  • If set to -1 the gun won't show in the shop

• isPrimaryWeapon: Used by the weapon limiter feature (if enabled in config.yml). true classifies it as a primary weapon, false as secondary.

• material: The base Minecraft item material used for this weapon. This affects the item's appearance if no resource pack is used and is crucial for resource packs to target the item. CROSSBOW and BOW allow for charging animations, FISHING_ROD can work for some effects, otherwise DIAMOND_HOE or other tools/items are common.

• invalid: If set to true, QualityArmory will ignore this file and not load the weapon. Useful for temporarily disabling a weapon without deleting the file.

• durability: The total durability points the weapon has if EnableWeaponDurability is true in config.yml. Each shot or configured action consumes durability.

• maxItemStack: The maximum stack size for this item in inventories. Typically 1 for weapons.

• setZoomLevel: Applies a Slowness effect to simulate scope zoom when aiming (if enableIronSights is true). 0 = no zoom, 1 = Slowness I, 2 = Slowness II, etc. Higher values mean more zoom.

• sway: Configures weapon accuracy (spread). Lower values are more accurate.

  • defaultValue: The base sway value when standing still and not aiming/sneaking.

  • defaultMultiplier: A general multiplier applied to sway calculations, potentially affecting how much movement/running impacts accuracy.

  • sneakModifier: If true, sway is affected by the global swayModifier_Sneak from config.yml when the player is sneaking.

  • moveModifier: If true, sway is affected by the global swayModifier_Walk from config.yml when the player is walking.

  • runModifier: If true, sway is affected by the global swayModifier_Run from config.yml when the player is sprinting.

• firerate: For automatic weapons (isAutomatic: true), this controls how many shots are fired per "burst" or firing cycle. Often kept at 1. The actual speed is controlled more by delayForShoot.

• delayForReload: The time in seconds it takes to reload the weapon.

• delayForShoot: The minimum time in seconds between consecutive shots (fire rate limiter). Lower values mean faster firing.

• bullets-per-shot: The number of bullets consumed and fired with each shot. Useful for shotguns (e.g., 8), but each projectile calculates damage independently.

• isAutomatic: If true, the weapon can fire continuously when the fire button is held down (respecting delayForShoot). If false, it's semi-automatic (one shot per click).

• maxBulletDistance: The maximum distance (in blocks) a bullet will travel before despawning or stopping calculation.

• unlimitedAmmo: If true, the weapon does not consume ammo and does not need reloading.

• LightLeveOnShoot: If LightAPI is installed, creates a temporary light source with this light level (0-15) at the shooter's location when firing.

• recoil: The magnitude of vertical camera kick applied to the shooter when firing, if enableRecoil is true in config.yml.

• slownessOnEquip: Applies a permanent Slowness effect to the player while holding this weapon. 0 = no effect, 1 = Slowness I, 2 = Slowness II, etc.

• particles: Configures the bullet trail particle effect if enableBulletTrails is true in config.yml.

  • bullet_particle: The name of the particle type to use (from Bukkit Particle enum). REDSTONE is special as it allows custom colors via RGB.

  • bullet_particleR: Red component (0.0-1.0) for REDSTONE particles.

  • bullet_particleG: Green component (0.0-1.0) for REDSTONE particles.

  • bullet_particleB: Blue component (0.0-1.0) for REDSTONE particles.

  • bullet_particleData: Extra data value for certain particle types (often unused, 0).

  • bullet_particleMaterial: For particles like BLOCK_DUST, specifies the material whose texture is used.

• Version_18_Support: A flag potentially used for compatibility adjustments or model selection when ViaVersion/ViaRewind are present, indicating if the model is primarily designed for 1.8 clients.

• ChargingHandler: Specifies a custom Java class (handler) to manage weapon charging behavior (e.g., bows, miniguns). none means no special charging mechanic. Requires custom coding to add new handlers.

• ReloadingHandler: Specifies a custom Java class (handler) to manage weapon reloading behavior (e.g., shotguns reloading one shell at a time). none uses the default magazine reload. Requires custom coding to add new handlers.

• addMuzzleSmoke: If true, spawns a brief smoke particle effect at the barrel when firing.

• drop-glow-color: If set to a valid ChatColor name (e.g., RED, GOLD), makes the dropped item entity glow with that color. none disables the glow.

• headshotMultiplier: The factor by which base damage is multiplied when a headshot occurs. 1.0 means no extra damage.

• weaponsounds_volume: Controls the volume multiplier for the firing sounds (weaponsounds).

• firing_knockback: Applies a knockback force to the shooter when firing. Negative values push backwards.

• KilledByMessage: The custom death message format used when a player is killed by this weapon. Placeholders: %player% (victim), %killer% (attacker), %name% (weapon display name).

• DestructableMaterials: A list of block material names (e.g., GLASS, WHITE_WOOL) that bullets from this specific gun can break. Requires enableExplosionDamage or similar features to be enabled globally or per-weapon. MATERIAL_NAME_HERE is a placeholder.

These are all the fields used by an ammo with their description:

• invalid: If set to true, this ammo configuration file will be skipped during loading. Defaults to false

• name: The internal, unique identifier for this ammo type. Used for referencing this ammo in gun configurations

• displayname: The name shown in-game for the ammo item. Supports color codes (e.g., &f). Defaults to the name if not specified

• lore: A list of strings that will appear as the item's lore (description below the name). Supports color codes

• id: The ammo id, used as durability before Minecraft 1.13 and for custom model data for newer versions

• variant: Used for item variants (e.g., different wood types, potion effects). Defaults to 0

• craftingRequirements: Defines the materials needed to craft this ammo. Each string follows the format MATERIAL_NAME,DATA_VALUE,AMOUNT

• craftingReturnAmount: The quantity of ammo items produced when crafted using the craftingRequirements

• price: The cost to purchase this ammo from the shop. If the price is 0 or less, allowInShop defaults to false. Defaults to 100

• allowInShop: Explicitly sets whether this ammo can be bought in the shop. Defaults to true if price is greater than 0

• maxItemStack: The maximum number of this ammo item that can be held in a single inventory stack

• material: The Bukkit Material name for the item used as ammo (e.g., PHANTOM_MEMBRANE, IRON_NUGGET)

• skull_owner: If material is PLAYER_HEAD, this sets the head's owner by player name

• skull_owner_custom_url: If material is PLAYER_HEAD, this sets the head's skin using a Base64 texture URL

• piercingSeverity: Multiplier applied to the base gun damage

These are all the fields used by an armor with their description:

• invalid: If set to true, this armor configuration file will be skipped during loading. Defaults to false

• name : The internal, unique identifier for this armor piece

• displayname: The name shown in-game for the armor item. Supports color codes (e.g., &6). Defaults to the name with white color if not specified

• lore: A list of strings that will appear as the item's lore (description below the name). Supports color codes

• id: The armor id, used as durability before Minecraft 1.13 and for custom model data for newer versions

• variant: Used for item variants. Defaults to 0

• craftingRequirements: Defines the materials needed to craft this armor. Each string follows the format MATERIAL_NAME,DATA_VALUE,AMOUNT

• price: The cost to purchase this armor from the shop. If the price is 0 or less, allowInShop defaults to false. Defaults to 100

• allowInShop: Explicitly sets whether this armor can be bought in the shop

• MiscType: Specifies the type of item. For armor, this should be HELMET

• minProtectionHeight: The minimum Y-coordinate relative to the player's feet where the helmet provides protection

• maxProtectionHeight: The maximum Y-coordinate relative to the player's feet where the helmet provides protection

• protection The amount of armor points this item provides. Defaults to 0. This value is used to add the generic.armor attribute modifier to the item

• material: The Bukkit Material name for the item used as armor. Defaults to DIAMOND_AXE if not specified

The me.zombie_striker.qg.api.QualityArmory class provides static methods for interacting with the QualityArmory plugin, allowing other plugins to access information about guns, ammo, armor, and miscellaneous items, as well as perform actions like giving items or checking player states.

Core Item Management & Creation

• 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: Internal name for the gun (used in commands).

    • displayname: In-game display name (supports color codes).

    • material: Base Material for the item.

    • id: CustomModelData (1.14+) or Durability (<1.14) value.

    • type: The WeaponType enum value (e.g., PISTOL, RIFLE).

    • sound: The WeaponSounds enum value for firing.

    • hasIronSights: true if the gun should support aiming down sights.

    • ammotype: Internal name of the required Ammo item.

    • damage: Base damage per bullet.

    • maxBullets: Magazine capacity.

    • cost: Price in the /qa shop.

  • Returns: A GunYML object representing the created configuration (allows further modification before saving, though this method saves immediately).

  • Note: Creates a file and schedules a task to load it.

• 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. You would need to call methods on the returned GunYML object to save it.

  • Parameters: Same as createAndLoadNewGun.

  • Returns: A GunYML object representing the potential configuration.

• registerNewUsedExpansionItem(Material used, int id)

  • Description: Registers a specific Material/ID combination as being used by an expansion pack or addon. This helps prevent ID conflicts when QualityArmory searches for available IDs. Assumes variant 0.

  • Parameters:

    • used: The Material used by the expansion item.

    • id: The CustomModelData/Durability value used.

• registerNewUsedExpansionItem(Material used, int id, int var)

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

  • Parameters:

    • used: The Material used by the expansion item.

    • id: The CustomModelData/Durability value used.

    • var: The variant value used.

• registerNewUsedExpansionItem(MaterialStorage ms)

  • Description: Registers a MaterialStorage object (which encapsulates Material, ID, and Variant) as being used by an expansion pack or addon.

  • Parameters:

    • ms: The MaterialStorage object representing the item.

Retrieving Registered Items

• 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 (like medkits, ammo bags).

• 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 (often castable to a specific type like AmmoBag) associated with the given ItemStack, or null if it's not a QA misc item.

• getCustomItem(ItemStack is): Returns the CustomBaseObject (Gun, Ammo, Armor, or Misc) 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 (checks main hand and off-hand for iron sights), or null.

Checking Item Types

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

• isCustomItem(ItemStack is, int dataOffset): Checks if the item would be a custom item if its CustomModelData/Durability were offset by dataOffset. Useful for checking durability changes.

• isCustomItemNextId(ItemStack is): Checks if an item with the next sequential CustomModelData/Durability value (same material) is a registered QA item.

• isGun(ItemStack is): Returns true if the ItemStack is a registered QA gun.

• isAmmo(ItemStack is): Returns true if the ItemStack is a registered QA ammo type.

• isArmor(ItemStack is): Returns true if the ItemStack is a registered QA armor piece.

• isMisc(ItemStack is): Returns true if the ItemStack is a registered QA miscellaneous item.

• isAmmoBag(ItemStack is): Returns true if the ItemStack is a registered QA miscellaneous item that is specifically an AmmoBag.

• isIronSights(ItemStack is): Returns true if the ItemStack represents the temporary item shown when aiming down sights.

Player Interaction & State

• sendResourcepack(final Player player, final boolean warning)

  • Description: Sends the appropriate server resource pack to the player after a configured delay (SecondsTillRPIsSent). Uses the multi-version system if enabled.

  • Parameters:

    • player: The player to send the pack to.

    • warning: If true, sends warning messages/titles before sending the pack prompt.

  • Note: Schedules tasks. Relies on config.yml settings for URLs, delays, and behavior. Requires ViaVersion for version detection if Auto-Detect-Resourcepack is true.

• allowGunsInRegion(Location loc)

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

  • Parameters:

    • loc: The Location to check.

  • Returns: true if allowed, false otherwise. Returns true if no protection hooks deny it or if hooks fail.

• sendHotbarGunAmmoCount(final Player p, final CustomBaseObject gun, ItemStack usedItem, boolean reloading)

  • Description: Sends the ammo count/status message above the player's hotbar. Uses the format defined in config.yml.

  • Parameters:

    • p: The player to send the message to.

    • gun: The Gun or AttachmentBase object being used.

    • usedItem: The ItemStack representing the gun in the player's hand.

    • reloading: true if the player is currently reloading this weapon.

• sendHotbarGunAmmoCount(final Player p, final CustomBaseObject gun, ItemStack usedItem, boolean reloading, int currentAmountInGun, int maxAmount)

  • Description: Sends the ammo count/status message above the player's hotbar, allowing manual specification of current/max ammo (useful for custom reload handlers).

  • Parameters:

    • p: The player.

    • gun: The Gun or AttachmentBase.

    • usedItem: The ItemStack.

    • reloading: true if reloading.

    • currentAmountInGun: The current ammo count to display.

    • maxAmount: The maximum ammo capacity to display.

• getAmmoInInventory(Player player, Ammo a)

  • Description: Calculates the total amount of a specific Ammo type the player has in their main inventory, including amounts stored in AmmoBag items. Returns 99999 if the player is in Creative mode.

  • Parameters:

    • player: The player whose inventory to check.

    • a: The Ammo type to count.

  • Returns: The total count of the specified ammo.

• getAmmoInInventory(Player player, Ammo a, boolean ignoreBag)

  • Description: Calculates the amount of a specific Ammo type the player has. Can optionally ignore ammo bags.

  • Parameters:

    • player: The player.

    • a: The Ammo type.

    • ignoreBag: If true, does not count ammo inside AmmoBag items.

  • Returns: The total count of the specified ammo.

• getAmmoInBag(@NotNull Player player, Ammo a)

  • Description: Calculates the total amount of a specific Ammo type stored only within AmmoBag items in the player's inventory.

  • Parameters:

    • player: The player.

    • a: The Ammo type.

  • Returns: The total count within ammo bags.

• addAmmoToInventory(Player player, Ammo a, int amount)

  • Description: Attempts to add the specified amount of ammo to the player's inventory, stacking with existing ammo items first, then filling empty slots.

  • Parameters:

    • player: The player.

    • a: The Ammo type to add.

    • amount: The quantity to add.

  • Returns: true if all ammo was successfully added, false if there wasn't enough space.

• removeAmmoFromInventory(Player player, Ammo a, int amount)

  • Description: Attempts to remove the specified amount of ammo from the player's inventory, taking from main inventory stacks first, then from AmmoBag items if necessary. Does nothing if the player is in Creative mode.

  • Parameters:

    • player: The player.

    • a: The Ammo type to remove.

    • amount: The quantity to remove.

  • Returns: true if the specified amount was successfully removed, false if the player didn't have enough ammo.

• getBulletsInHand(Player player): Returns the current ammo count stored in the NBT data of the gun item the player is holding.

• isOverLimitForPrimaryWeapons(Gun g, Player p)

  • Description: Checks if adding the specified gun (g) would put the player (p) over the primary or secondary weapon limit configured in config.yml (if the limiter is enabled).

  • Parameters:

    • g: The Gun being checked.

    • p: The player.

  • Returns: true if the player is already at or above the limit for that weapon type (primary/secondary), false otherwise.

• 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: The HumanEntity (usually a Player) to give the item to.

    • item: The ItemStack to give.

Item & Utility Methods

• getCustomItemAsItemStack(String name): Retrieves a CustomBaseObject by its internal name and returns a fresh ItemStack representation of it.

• getCustomItemAsItemStack(CustomBaseObject obj): Returns a fresh ItemStack representation of the given CustomBaseObject. Returns null if the input object is null.

• getIronSightsItemStack(): Returns the specific ItemStack used to represent the aiming-down-sights view.

• findSafeSpot(ItemStack newItem, boolean findHighest, boolean allowPockets): Searches for an unused CustomModelData/Durability value for the given item's Material, starting from the item's current value and searching up (findHighest = true) or down (findHighest = false). allowPockets determines if it searches for any gap or just the absolute highest/lowest used ID. Primarily for internal use or advanced item creation.

• findSafeSpot(Material newItemtype, int startingData, boolean findHighest, boolean allowPockets): Same as above, but takes Material and starting data directly.

• findSafeSpotVariant(ItemStack newItem, boolean findHighest): Searches for an unused Variant value for the given item's Material and CustomModelData/Durability, starting from 0 and searching up (findHighest = true) or down (findHighest = false).

• findSafeSpotVariant(Material newItemtype, int startingData, boolean findHighest): Same as above, but takes Material and data directly.

• getMaxPagesForGUI(): 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): A simple utility method to repeat a given string multiple times. Used internally for formatting reload progress bars.

This is the documentation of the main configuration, also known as config.yml. Below you can find a list of all the options that you can configure and their explanation.

• ENABLE-DEBUG: false - Toggles detailed debug messages in the console. Useful for troubleshooting.

• language: en - Sets the language file used for plugin messages (e.g., en for English).

• FriendlyFireEnabled: false - If true, allows players on the same team or party to damage each other with guns.

• KickPlayerIfDeniedResourcepack: false - If true, players who decline the server resource pack prompt will be kicked.

• useDefaultResourcepack: true - If true, the plugin uses its built-in default resource pack URLs. If false, it uses the URLs specified in DefaultResourcepackOverride.

• EnableWeaponDurability: false - If true, QualityArmory weapons will lose durability when used.

• BulletDetection.step: 0.1 - Controls the distance interval (in blocks) for checking bullet collisions. Smaller values are more accurate but may use more server resources.

• BlockBullets.door: false - If true, bullets will be stopped by door blocks.

• BlockBullets.halfslabs: false - If true, bullets will be stopped by half-slab blocks.

• BlockBullets.leaves: false - If true, bullets will be stopped by leaf blocks.

• BlockBullets.water: false - If true, bullets will be stopped upon entering water blocks.

• BlockBullets.glass: false - If true, bullets will be stopped by glass blocks.

• enableInteract.Chests: false - If true, allows players to open chests while holding a QualityArmory weapon.

• overrideAnvil: false - If true, replaces the standard anvil interface with the QualityArmory crafting bench when interacting with an anvil.

• showPossibleCrashHelpMessage: true - If true, displays a message suggesting /qa getResourcepack if a player might be experiencing client crashes due to the resource pack.

• anticheatFix: false - Enables specific adjustments intended to improve compatibility with some anti-cheat plugins.

• verboseItemLogging: false - If true, prints detailed information to the console during the loading of guns, ammo, and other items.

• enable_permssionsToShoot: false - If true, players require the permission qualityarmory.shoot.<gun_name> to fire specific guns.

• sendOnJoin: true - If true, automatically prompts players to download the resource pack when they join the server.

• sendTitleOnJoin: false - If true, displays a title message related to the resource pack when players join.

• SecondsTillRPIsSent: 5.0 - The delay in seconds after a player joins before the resource pack prompt is sent (if sendOnJoin is true).

• enableBulletTrails: true - If true, displays particle trails following bullets.

• BulletTrailsSpacing: 0.5 - The distance (in blocks) between particles in a bullet trail.

• enableIgnoreArmorProtection: false - If true, bullets ignore the protection value of armor worn by the target.

• enableIgnoreUnbreakingChecks: false - If true, the Unbreaking enchantment on items is ignored when calculating durability loss (if EnableWeaponDurability is true).

• enableIgnoreSkipForBasegameItems: false - A legacy or internal setting likely related to how the plugin handles interactions with vanilla Minecraft items.

• Items.enable_Unbreaking: true - If true, makes QualityArmory items inherently unbreakable, regardless of the EnableWeaponDurability setting.

• enableReloadingOnDrop: false - If true, allows players to reload by pressing their drop key (default 'Q') while holding a gun.

• enableReloadingWhenSwapToOffhand: true - If true, allows players to reload by pressing their swap-to-offhand key (default 'F') while holding a gun.

• enableReloadOnlyWhenSwapToOffhand: false - If true, reloading is only possible using the swap-to-offhand key ('F'), disabling other methods like right-click (if applicable).

• allowGunHitEntities: false - If true, allows guns to register melee damage when hitting entities directly.

• showOutOfAmmoOnTitle: false - If true, displays a large title message on the screen when the player tries to shoot with an empty gun.

• showReloadingTitle: false - If true, displays a large title message on the screen while the player is reloading.

• showAmmoInXPBar: false - If true, displays the current gun's ammo count in the player's experience bar.

• perWeaponPermission: false - If true, requires players to have individual permissions (qualityarmory.use.<item_name>) to use each specific gun, ammo, or misc item.

• useMoveForRecoil: true - If true, recoil is simulated by directly moving the player's camera view. If false, other methods might be used.

• enableExplosionDamage: false - If true, explosions caused by QualityArmory projectiles can destroy blocks.

• enableExplosionDamageDrop: false - If true and enableExplosionDamage is true, blocks destroyed by explosions will drop their corresponding items.

• enablePrimaryWeaponLimiter: false - If true, enforces limits on the number of primary and secondary weapons a player can carry simultaneously.

• weaponlimiter_primaries: 2 - The maximum number of items classified as 'primary' weapons a player can carry if the limiter is enabled.

• weaponlimiter_secondaries: 2 - The maximum number of items classified as 'secondary' weapons a player can carry if the limiter is enabled.

• enableCrafting: true - Enables the /qa craft command and the crafting system for QualityArmory items.

• enableShop: true - Enables the /qa shop command and the GUI shop for buying QualityArmory items.

• AUTO-UPDATE: true - If true, the plugin will attempt to automatically download and install updates on server start.

• Swap-Reload-and-Shooting-Controls: false - If true, swaps the default mouse button actions (e.g., makes right-click shoot and left-click aim/reload).

• Order-Shop-By-Price: false - If true, items listed in the /qa shop GUI will be sorted by their configured price.

• enable_lore_gun-info_messages: true - If true, displays weapon statistics like damage, ammo type, etc., in the item's lore text.

• enable_lore_control-help_messages: true - If true, displays basic control instructions (e.g., "[LMB] Shoot") in the item's lore text.

• Enable_Headshot_Instantkill: true - If true, landing a headshot on a player or mob results in an instant kill.

• Enable_Headshot_Notification_Sound: true - If true, plays a sound effect to the shooter when they successfully land a headshot.

• Headshot_Notification_Sound: entity.experience_orb.pickup - The specific sound event name to play for a headshot notification.

• Enable_Headshot_Sounds: true - If true, enables additional sounds related to headshots (e.g., impact/gore sounds).

• Headshot_Blacklist: [] - A list of entity types (e.g., ZOMBIE, PLAYER) that are immune to the special effects of headshots (like instant kill).

• Enable_AutoArm_Grenades: false - If true, grenades are automatically armed when thrown, bypassing the need to manually "pull the pin" first.

• gravityConstantForDropoffCalculations: 0.05 - The value representing gravity's effect used in calculating bullet trajectory and drop-off.

• allowGunReload: true - A master switch to enable or disable all gun reloading mechanics.

• Auto-Detect-Resourcepack: true - If true, the plugin attempts to automatically select the correct resource pack version based on the detected Minecraft server version.

• ManuallyOverrideTo_1_8_systems: false - If true, forces the plugin to use item models and mechanics designed for Minecraft 1.8, overriding auto-detection.

• ManuallyOverrideTo_1_13_systems: false - If true, forces the plugin to use item models and mechanics designed for Minecraft 1.9-1.13, overriding auto-detection.

• ManuallyOverrideTo_1_14_systems: false - If true, forces the plugin to use item models (like Crossbow) and mechanics designed for Minecraft 1.14+, overriding auto-detection.

• unknownTranslationKeyFixer: false - If true, attempts to apply fixes for potential issues related to missing or incorrect translation keys in item names or lore.

• Enable_Creation_Of_Default_Files: true - If true, the plugin will automatically generate default configuration files (like for guns, ammo, etc.) in its folder if they are missing.

• EnableGlowEffects: false - If true, enables glowing effects on certain items or potentially entities under specific conditions.

• Break-Block-Texture-If-Shot: true - If true, displays block breaking particle effects when a block is hit by a bullet.

• enableRecoil: true - Enables or disables the visual recoil effect when firing weapons.

• experimental.BulletWounds.InitialBloodLevel: 1500.0 - The starting value for the internal "blood level" tracker used by the experimental bleeding system.

• experimental.BulletWounds.BloodIncreasePerSecond: 0.01 - Likely represents the rate at which the "blood level" decreases per second when bleeding (needs verification, name is counter-intuitive).

• experimental.BulletWounds.Medkit_Heal_Bloodloss_Rate: 0.05 - The rate at which using a medkit counteracts bleeding or restores the "blood level".

• experimental.BulletWounds.enableBleeding: false - Enables the experimental system where players can suffer from bleeding after being shot, potentially requiring a medkit.

• disableHotbarMessages.OutOfAmmo: false - If true, prevents the "Out of Ammo" message from appearing above the hotbar.

• disableHotbarMessages.Shoot: false - If true, prevents the ammo count message from appearing above the hotbar when shooting.

• disableHotbarMessages.Reload: false - If true, prevents the "Reloading..." message from appearing above the hotbar.

• automaticallyReloadGunWhenOutOfAmmo: false - If true, the gun will automatically begin reloading as soon as the player tries to fire with no ammo left.

• generalModifiers.sway.Run: 1.3 - A multiplier affecting the amount of weapon sway while the player is running.

• generalModifiers.sway.Walk: 1.5 - A multiplier affecting the amount of weapon sway while the player is walking.

• generalModifiers.sway.Ironsights: 0.8 - A multiplier affecting the amount of weapon sway while the player is aiming down sights (values < 1 reduce sway).

• generalModifiers.sway.Sneak: 0.7 - A multiplier affecting the amount of weapon sway while the player is sneaking (values < 1 reduce sway).

• deathmessages.enable: true - If true, enables custom death messages indicating kills made with QualityArmory weapons.

• impenetrableEntityTypes: [ARROW] - A list of entity types that bullets cannot pass through (e.g., arrows, potentially other projectiles).

• DefaultResourcepackOverride: false - If true, forces the plugin to use the resource pack URL(s) defined under DefaultResourcepack instead of its internal defaults.

• IronSightsOnRightClick: false - If true, aiming down sights (iron sights) is activated by right-clicking instead of the default (usually sneaking).

• SwapSneakToSingleFire: false - If true, changes the control for single-fire mode on automatic weapons to Sneak + Left-Click.

• DestructableMaterials: [MATERIAL_NAME_HERE] - A list of material names (e.g., GLASS, WHITE_WOOL) that can be broken by bullets if enableExplosionDamage is appropriately configured or via specific weapon properties.

• RegenDestructableBlocksAfter: -1 - The time in server ticks after which a block destroyed by a QualityArmory weapon/explosion will regenerate. -1 disables regeneration.

• overrideAttackSpeed: true - If true (primarily for 1.14+), overrides the default item attack speed attribute, potentially allowing faster firing rates.

• enable_lore_gun-info_messages: true - If true, displays weapon statistics like damage, ammo type, etc., in the item's lore text.

• enable_lore_gun-bullets: false - If true, displays the bullet amount in the item's lore text. This will make the gun go "up and down" when shooting.

Welcome to QualityArmory (QA). Here you will learn how to customize the plugin and create your own guns.

With QualityArmory you have unlimited possibilities, the only limit is your creativity.

The plugin does not require any other dependency, after downloading the plugin, you are ready to use it.

Compatibilities

You can install these plugins to add additional features to the plugin

• Others plugins are also supported but not listed here

This guide explains how to configure QualityArmory to send the correct resource pack to your players.

Basic Setup & Auto-Detection (Recommended):

• useDefaultResourcepack: true: Keep this true when using the auto-detection system. It tells the plugin to use the URLs defined under the DefaultResourcepack: section below.

• DefaultResourcepack:: This section defines the different resource pack URLs for various Minecraft versions.

  • You must have an entry with the key "0". This is the fallback URL used if no specific version matches or if the player's version cannot be detected.

  • Add entries for specific Minecraft versions using the format "minor" or "minor-patch". The plugin will select the highest version entry that is less than or equal to the player's version.

  • Keys should be strings (use quotes).

Example DefaultResourcepack Section:

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

How it works with the example:

• Player joins with 1.18.2 -> Gets the '0' pack.

• Player joins with 1.19.4 -> Gets the '19' pack.

• Player joins with 1.20.1 -> Gets the '20' pack.

• Player joins with 1.20.4 -> Gets the '20-2' pack.

• Player joins with 1.21.0 -> Gets the '21' pack.

Manual Override (Alternative - Not Recommended unless needed):

• If you don't want auto-detection or don't have ViaVersion, you can force the plugin to use one specific set of models/systems.

• Set Auto-Detect-Resourcepack: false.

• Set one of the following to true:

  • ManuallyOverrideTo_1_8_systems: true (For 1.8 style models/mechanics)

  • ManuallyOverrideTo_1_13_systems: true (For 1.9-1.13 style models/mechanics)

  • ManuallyOverrideTo_1_14_systems: true (For 1.14+ style models/mechanics)

• In this case, the plugin will use the fallback '0' URL from DefaultResourcepack. This setup is less flexible and generally only used for troubleshooting or specific server setups.

Using a Single Custom URL (Simple):

• If you only have one resource pack URL you want everyone to use, regardless of version:

• Set useDefaultResourcepack: false.

• Set DefaultResourcepackOverride: true.

• Define your single URL under DefaultResourcepack: :

# ... other config settings ...

useDefaultResourcepack: false
DefaultResourcepackOverride: true

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

# ... other config settings ...

I suggest watching a tutorial on YouTube to learn how to create a model, here is a suggested one:

Choosing a Model Editor

• For Simple Models: MrCrayfish’s Model Creator works well for basic guns.

Exporting the Model

1. Build your gun model in BlockBench.

2. Export it as a .json file once complete.

3. Name the file the same as the gun (e.g., ak47.json). This keeps things organized and makes it easier to update models later.

   • Note: From Minecraft 1.12+, filenames must be all lowercase

Adding Iron Sights

If you want to add iron sights:

• Set first-person off-hand display values — QA uses off-hand for scoping, but it appears in the right hand.

• Also define the third-person display values for proper iron sight positioning.

• You can use existing models in the pack as references to copy values or setups.

Integrating the Model in Resource Packs

Minecraft 1.9 – 1.13

You’ll need to modify the diamond_axe.json file at /assets/minecraft/models/item/diamond_axe.json

Find the JSON object structure that looks like this:

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

Insert a new entry after the closing }, like so:

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

Replace the placeholders:

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)

Minecraft 1.14+

In 1.14+, Mojang introduced the custom_model_data tag — a cleaner way to add models. You can modify /assets/minecraft/models/item/crossbow.json and add a new entry:

Here’s an example structure:

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

Add your custom gun model:

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

Replace the placeholders:

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).

In order to use the QualityArmory API you need to add the plugin as a dependency. Replace VERSION with the latest version:

Java Dependency

<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>

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

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

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

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

Plugin Dependency

Add the plugin as a dependency to your plugin by editing the plugin.yml file by including the following line under the depend section:

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

This ensures that your plugin will load after QualityArmory. If your plugin requires specific features from QualityArmory at runtime, remember to also use appropriate checks in your code to confirm that QualityArmory is enabled.