# \ud83d\udd2b CombatGunSSS<\/p>\n
\n
\n<\/p>\n
**CombatGunSSS** is a high-performance, feature-rich Minecraft gun plugin designed for modern servers (1.21+). It brings a tactical, realistic combat experience with 45 uniquely configured weapons (39 firearms + 6 melee), advanced crafting mechanics, optimized hitscan technology, a full custom events API, and a growing ecosystem of plugin integrations.<\/p>\n
—<\/p>\n
## \ud83c\udf1f Key Features<\/p>\n
– **\ud83c\udfaf Tactical Combat**: Realistic hitscan mechanics with accurate recoil, bullet spread, and headshot multipliers. —<\/p>\n ## \ud83c\udfae Player Controls<\/p>\n | Action | Control | —<\/p>\n ## \ud83d\udd2b Weapon Categories<\/p>\n ### Ranged Weapons (39) ### Melee Weapons (6) —<\/p>\n ## \ud83d\udd2b Technical Weapon Stats<\/p>\n Every weapon in CombatGunSSS features a deep set of configurable properties:<\/p>\n – **Damage Falloff**: Define exactly at what block distance damage begins to drop (`damage_falloff_start`) and the minimum damage floor (`min_damage_multiplier`). —<\/p>\n ## \ud83d\udcc1 Folder Structure<\/p>\n “` **Custom Weapons**: Create your own YAML files in `guns\/` or `melees\/` folders and run `\/gun reload`.<\/p>\n —<\/p>\n ## \u2692\ufe0f Crafting Mechanics<\/p>\n ### **1. Components (The Basics)** ### **2. Assembly (The Advanced)** —<\/p>\n ## \ud83d\udcca Action Bar HUD<\/p>\n While holding any ranged weapon, CombatGunSSS displays a persistent HUD on your action bar:<\/p>\n “` – **Gun name** is colored by rarity: white (common) \u2192 aqua (rare) \u2192 light purple (epic) \u2192 gold (legendary). “`yaml ## \ud83c\udfaf ADS \u2014 Aim Down Sights<\/p>\n Enable ADS per gun in its YAML config:<\/p>\n “`yaml **Control**: Shift+Right-click to toggle ADS on\/off. Action bar shows `\ud83c\udfaf ADS [spread \u00d70.35]`.<\/p>\n ADS exits automatically when you switch items, teleport, or die. Scopeable sniper rifles use the traditional sneak-to-scope mechanic instead of ADS.<\/p>\n —<\/p>\n ## \ud83e\ude78 Bleeding<\/p>\n An optional damage-over-time system. When enabled, bullets hitting players have a configurable chance to cause bleeding.<\/p>\n “`yaml Hold a **bandage** (crafting component) and press `[F]` to cure. Bleeding stops automatically on death.<\/p>\n —<\/p>\n ## \ud83c\udf92 Ammo Pouch<\/p>\n A compressed ammo container that stores hundreds of rounds in a single slot.<\/p>\n “` Shift+Right-click to unpack all rounds into your inventory. Surplus rounds are left if the inventory is full.<\/p>\n —<\/p>\n ## \ud83c\udf10 Multi-Language<\/p>\n Set the active language in `config.yml`:<\/p>\n “`yaml Bundled: **English** (`en`) and **Ti\u1ebfng Vi\u1ec7t** (`vi`). Add a custom translation by placing `lang\/xx.yml` in the plugin data folder and running `\/gun reload`.<\/p>\n — ### PlaceholderAPI<\/p>\n 8 real-time placeholders for use in scoreboards, TAB, AdvancedHud, and similar plugins:<\/p>\n | Placeholder | Example | Description | ### Vault Shop<\/p>\n Enable the shop in `config.yml`, set prices per gun, then players can buy weapons in-game:<\/p>\n “`yaml “` ### WorldGuard<\/p>\n The custom flag `gun-shooting` is automatically registered when WorldGuard is present:<\/p>\n “` Falls back to WorldGuard’s built-in `PVP` flag if `gun-shooting` is not set on a region.<\/p>\n ### Anti-Cheat (Vulcan \/ Matrix)<\/p>\n Auto-detected. When present, players are exempted from motion checks for `anticheat.exempt_ticks` ticks after each shot to prevent recoil from triggering false positives.<\/p>\n “`yaml —<\/p>\n ## \ud83d\udcdc Commands & Permissions<\/p>\n | Command | Description | Permission | ### Player Permissions —<\/p>\n ## \ud83d\udd27 Configuration Examples<\/p>\n ### Ranged Weapon (AK47) ### Melee Weapon (Katana) —<\/p>\n ## \ud83d\udd0c Developer API<\/p>\n ### Custom Events<\/p>\n | Event | Cancellable | When it fires | “`java @EventHandler @EventHandler @EventHandler ### API Instance<\/p>\n “`java \/\/ Query guns \/\/ Create items \/\/ Check items \/\/ Player state \/\/ Hook state —<\/p>\n ## \ud83d\ude80 Installation<\/p>\n 1. Download the `CombatGunSSS-2.0.6.jar`. ### Requirements —<\/p>\n ## \ud83d\udccb Changelog<\/p>\n See [CHANGELOG.md](CHANGELOG.md) for the full version history.<\/p>\n **2.0.6** \u2014 Bug-fix release: 4 bugs fixed **2.0.5** \u2014 Developer API & architecture release: 4 new additions, 1 improvement **2.0.4** \u2014 Stability & performance release: 2 bug-fixes, 3 improvements **2.0.3** \u2014 Bug-fix release: 7 bugs fixed **2.0.2** \u2014 Hotfix: Fixed NPE when shooting caused by GunListener trying to cache HudManager before it was initialized \u2014 resolved using lazy access.<\/p>\n **2.0.1** \u2014 Hotfix: plugin crash on startup isolated; `StatsManager`\/`HookManager` failures degrade gracefully; `Material.GRAY_DYE` compile fix; null-safety throughout.<\/p>\n **2.0.0** \u2014 Weapon attachments (silencer, scope, extended mag, grip); throwable items (frag, smoke, flashbang); kill stats & leaderboard (SQLite); 4 new PlaceholderAPI placeholders.<\/p>\n **1.2.0** \u2014 ADS (Aim Down Sights) per-gun toggle; Ammo Pouch compressed item (`\/gun givepouch`); Bleeding DoT on player hit with bandage cure; Multi-language i18n (`lang\/en.yml`, `lang\/vi.yml`).<\/p>\n **1.1.0** \u2014 PlaceholderAPI expansion (8 placeholders); Vault shop (`\/gun buy`); WorldGuard `gun-shooting` custom flag for region protection; Vulcan & Matrix anti-cheat exemptions on recoil; central `HookManager`; `softdepend` in `plugin.yml`.<\/p>\n **1.0.3** \u2014 Persistent action bar HUD (rarity-colored name, visual ammo bar, reserve count); auto-reload when empty (toggleable); new `GunHitEvent` exposing full damage pipeline; `GunShootEvent.getBaseDamage()` for pre-shot checks.<\/p>\n **1.0.2** \u2014 Custom events API; friendly fire toggle; toggleable effects + `sound_volume`; custom kill messages; `AmmoManager` memory leak fix; reload cancel on teleport\/world change; `GunData` Builder pattern.<\/p>\n **1.0.1** \u2014 Recipe Book registration fix; ammo type disambiguation fix; double-click exploit fix; debug spam removed.<\/p>\n —<\/p>\n ## \ud83d\udd0d Troubleshooting<\/p>\n * Fixed in **2.0.6** \u2014 team detection now uses the main scoreboard instead of each player’s personal view * Check `combatgun.use` permission is granted to players * Make sure you have the correct ammo type in your inventory (e.g. AR ammo for assault rifles) * Run `\/gun reload` to re-register vanilla recipes * This warning appears when your `config.yml` has a lower `config-version` than the plugin expects. * Added in **2.0.4** \u2014 guns with invalid configs now log a clear per-field error instead of loading silently. * Fixed in **2.0.4** \u2014 a `kills DESC` index is now created automatically on the SQLite database. * Fixed in **2.0.3** \u2014 update the plugin * Fixed in **2.0.3** \u2014 reload task now runs every 2 ticks instead of 1 (50% less CPU, same reload duration) * Fixed in **2.0.3** \u2014 crouching player hitbox now calculated correctly * Fixed in **2.0.3** \u2014 `BleedingManager` now uses wall-clock time instead of tick counting * Fixed in **2.0.1** \u2014 startup errors are now isolated per manager * Fixed in **2.0.2** \u2014 lazy HudManager access prevents NPE at startup * Ensure Vulcan or Matrix is listed in `softdepend` (already done automatically) * Install PlaceholderAPI and run `\/papi reload` * Make sure an economy plugin (EssentialsX, CMI, etc.) is installed alongside Vault * Never use `\/reload` \u2014 always do a full server restart * Place the file inside `plugins\/CombatGunSSS\/guns\/` (ranged) or `melees\/` (melee) —<\/p>\n ## \u2753 FAQ<\/p>\n ### Does this work on Spigot?<\/p>\n No \u2014 CombatGunSSS requires **Paper 1.21+**. Spigot lacks several API features used internally.<\/p>\n ### Can I add my own guns?<\/p>\n Yes. Create a new `.yml` file in `plugins\/CombatGunSSS\/guns\/` following the same format as the built-in weapon files, then run `\/gun reload`.<\/p>\n ### Can I disable specific guns?<\/p>\n Simply delete or remove the gun’s YAML file from the `guns\/` folder and run `\/gun reload`. Players holding that gun will keep the item but it won’t function.<\/p>\n ### Does it support multiple worlds?<\/p>\n Yes. Configure a world whitelist or blacklist under `combatgun.worlds` in `config.yml`.<\/p>\n ### Is it laggy on large servers?<\/p>\n CombatGunSSS uses hitscan (ray-trace, not projectile entities), so it is significantly lighter than projectile-based gun plugins. Heavy effects like bullet trails can be toggled off in `config.yml` under `combatgun.effects`.<\/p>\n ### Can I disable the crafting system?<\/p>\n Yes \u2014 simply don’t give players the Mechanical Crafting Table or Recipe Book. Use `\/gun give` for admin distribution. Vanilla workbench recipes can also be disabled per-item.<\/p>\n ### Do I need a Resource Pack?<\/p>\n No. The plugin works without a resource pack. However, each gun has a `custom_model_data` value pre-configured for you to link 3D models if you have a pack.<\/p>\n ### Can I disable bleeding or the Ammo Pouch?<\/p>\n Yes. Set `combatgun.bleeding.enabled: false` or `combatgun.ammo_pouch.enabled: false` in `config.yml`.<\/p>\n ### Does it support ZombieApocalypseSSS?<\/p>\n Yes \u2014 CombatGunSSS is the recommended gun companion for ZombieApocalypseSSS. Guns deal full damage to all zombie types and trigger the noise \/ aggro system automatically.<\/p>\n ### Can other plugins listen to gun events?<\/p>\n Yes. Four custom events are exposed via the API: `GunShootEvent` (cancellable), `GunReloadEvent` (cancellable), `GunHitEvent`, and `GunHeadshotEvent`. See the [Developer API](#-developer-api) section.<\/p>\n ### How do I give guns without the shop?<\/p>\n Use `\/gun give —<\/p>\n Developed with \u2764\ufe0f by **Duong2012G**.<\/p>\n —<\/p>\n > [!NOTE] > [!TIP] Adds 45 unique guns to Minecraft, each with custom damage, recoil, fire rate, and reload mechanics, enhancing combat with balanced gameplay, multiple weapon types, and flexible customization for varied playstyles<\/p>\n","protected":false},"featured_media":44324,"template":"","meta":{"_minecraft_slug":"combatgunsss","_minecraft_project_id":"BSt2YZOI","_minecraft_author":"Duong2012G","_minecraft_license":"Apache-2.0","_minecraft_downloads":307,"_minecraft_follows":3,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"combatgunsss.zip","_minecraft_size_bytes":81752593,"_minecraft_version_count":11,"_minecraft_updated_at":"2026-05-16T11:47:59.372100Z","_minecraft_date_created":"2026-04-04T01:45:35.908029Z","_minecraft_date_modified":"2026-05-14T11:37:16.435691Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/combatgunsss","_minecraft_icon_attachment_id":44324,"_minecraft_imported_at":"2026-06-02T02:24:47+00:00","_minecraft_import_hash":"438b3003bea10cc3c74ff11164e1d023","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[124,88,126,866,127,128,129],"mod_loader":[130,132,133,134],"minecraft_version":[62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-44323","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-bukkit","mod_category-equipment","mod_category-management","mod_category-minigame","mod_category-paper","mod_category-purpur","mod_category-spigot","mod_loader-bukkit","mod_loader-paper","mod_loader-purpur","mod_loader-spigot","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\n– **\u2694\ufe0f Melee System**: Left-click melee combat with range check, knockback, and separate cooldown system.
\n– **\ud83d\udee1\ufe0f Advanced Penetration**: Projectiles can pass through “soft” blocks and multiple entities based on individual gun stats.
\n– **\ud83e\ude78 Progressive Damage**: Distance-based **Damage Falloff** and configurable **Knockback** intensities.
\n– **\ud83d\udee0\ufe0f Two-Tier Crafting System**:
\n – **Vanilla Workbench**: Craft basic components with official **Recipe Book** support.
\n – **Mechanical Crafting Table**: A custom 21-slot industrial GUI for assembling advanced firearms.
\n– **\ud83d\udcc2 Interactive Recipe Browser**: Built-in visual guide inside the Mechanical Crafting Table \u2014 no commands needed!
\n– **\ud83d\udce6 45 Built-in Weapons**: 39 ranged guns + 6 melee weapons with burst-fire, shotgun pellets, and melee logic.
\n– **\ud83d\udcc9 Durability System**: Weapons can have limited usage and require repairs (fully configurable).
\n– **\ud83d\udcca Persistent HUD**: Real-time action bar showing gun name (rarity-colored), visual ammo bar, current\/max ammo, and reserve count.
\n– **\ud83d\udd04 Auto-Reload**: Automatically reloads after firing the last round (toggleable).
\n– **\ud83d\uddfa\ufe0f WorldGuard Integration**: Block gun use inside protected regions with a custom `gun-shooting` flag.
\n– **\ud83d\udcb0 Vault Shop**: Players purchase weapons via `\/gun buy
\n– **\ud83d\udccb PlaceholderAPI**: 8 real-time placeholders for scoreboards, HUDs, and TAB plugins.
\n– **\ud83c\udfaf ADS (Aim Down Sights)**: Per-gun aim-down-sights system. Shift+Right-click to toggle \u2014 reduces spread and applies movement penalty.
\n– **\ud83e\ude78 Bleeding**: Optional damage-over-time on bullet hit. Cured by holding a bandage and pressing `[F]`.
\n– **\ud83c\udf92 Ammo Pouch**: Compressed ammo bag. Shift+Right-click to unpack into inventory. Give via `\/gun givepouch`.
\n– **\ud83c\udf10 Multi-Language (i18n)**: All messages live in `lang\/en.yml` or `lang\/vi.yml`. Add your own translation file.
\n– **\ud83d\udee1\ufe0f Anti-Cheat**: Automatic exemptions for Vulcan and Matrix to prevent recoil false-positives.
\n– **\ud83d\udd0c Developer API**: Full custom events \u2014 `GunShootEvent`, `GunReloadEvent`, `GunHitEvent`, `GunHeadshotEvent`.
\n– **\ud83e\udd1d Friendly Fire Control**: Toggle friendly fire on\/off with scoreboard team or permission-group detection.
\n– **\ud83c\udfa8 Toggleable Effects**: Every particle and sound effect can be individually enabled\/disabled. Includes a master `sound_volume` control.
\n– **\ud83d\udc80 Custom Kill Messages**: Death messages show killer name, weapon name (colored by rarity), and headshot indicator.<\/p>\n
\n| :— | :— |
\n| **Shoot** | `Right Click` |
\n| **Reload** | `Swap Hand Key [F]` |
\n| **Melee Attack** | `Left Click` |
\n| **Buy a weapon** | `\/gun buy
\n| **Crafting** | `Right Click` on Mechanical Crafting Table |<\/p>\n
\n– **Assault Rifles**: AK47, M4A1, SCAR, AUG, FAMAS, G36, Groza, AN94, M14, ParaFAL, XM8, Kingfisher
\n– **SMGs**: MP5, P90, Vector, Bizon, UMP, Thompson, MAC-10, MP40, VSS, CG15
\n– **Snipers**: AWM, M24, Kar98k, M82B, M107, VSK94
\n– **Shotguns**: M1014, SPAS-12, MAG-7, M1887, M590, Trogon
\n– **Pistols**: Desert Eagle, G18, USP, M1917, M1873, M500<\/p>\n
\n– **Bat**: Common, fast swing
\n– **Knife**: Common, highest attack speed
\n– **Pan**: Rare, defensive knockback
\n– **Parang**: Rare, balanced damage\/speed
\n– **Katana**: Epic, high damage
\n– **Scythe**: Legendary, maximum damage<\/p>\n
\n– **Recoil & Spread**: Independent **Pitch** (vertical) and **Yaw** (horizontal) kick per shot, plus **Movement Spread** penalties while moving or jumping.
\n– **Burst Fire**: Configure weapons to fire multiple rounds per trigger pull (`burst_count`) with custom delays.
\n– **Shotgun Logic**: Support for multiple projectiles per shot (`projectiles_per_shot`) with per-pellet damage calculation.
\n– **Durability**: Set a maximum usage limit (`max_durability`). Weapons will break and become unusable until repaired.
\n– **Penetration**: Define how many blocks (`block_penetration`) or entities (`entity_penetration`) a single bullet can pass through.
\n– **Melee Range**: Maximum attack distance for melee weapons (default: 4 blocks).
\n– **Knockback**: Push strength for both ranged and melee weapons.<\/p>\n
\nplugins\/CombatGunSSS\/
\n\u251c\u2500\u2500 config.yml # Main configuration
\n\u251c\u2500\u2500 guns\/ # Ranged weapon configs (39 built-in + custom)
\n\u2502 \u251c\u2500\u2500 ak47.yml
\n\u2502 \u251c\u2500\u2500 m4a1.yml
\n\u2502 \u2514\u2500\u2500 …
\n\u251c\u2500\u2500 melees\/ # Melee weapon configs (6 built-in + custom)
\n\u2502 \u251c\u2500\u2500 katana.yml
\n\u2502 \u251c\u2500\u2500 knife.yml
\n\u2502 \u2514\u2500\u2500 …
\n\u2514\u2500\u2500 README.md
\n“`<\/p>\n
\nCraft raw materials like **Steel Ingots**, **Gun Barrels**, and **Springs** at a standard Crafting Table. These recipes are automatically unlocked in your **Vanilla Recipe Book**.<\/p>\n
\nPlace your components into the **Mechanical Crafting Table**.
\n– **Non-grid-based**: Just throw the ingredients into the 21-slot input area.
\n– **Visual Preview**: The output slot shows your gun stats before you build it.
\n– **Recipe Guide**: Click the **Glowing Book** icon in the station to browse all weapon requirements.<\/p>\n
\n\ud83d\udd2b AK47 \u2590\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2591\u2591\u2591\u2591\u258c 22 \/ 30 \u2022 90
\n“`<\/p>\n
\n– **Visual bar** transitions green \u2192 gold (\u226425%) \u2192 red (\u226410%) as ammo depletes.
\n– **Reserve count** turns red when you have no backup ammo left.
\n– The HUD automatically yields to the reload progress bar during active reloads.<\/p>\n
\ncombatgun:
\n hud:
\n enabled: true
\n update_interval_ticks: 5
\n“`<\/p>\n
\nads:
\n enabled: true
\n spread_multiplier: 0.35 # 65% tighter accuracy while ADS
\n movement_penalty: 0.6 # movement speed while ADS active
\n“`<\/p>\n
\ncombatgun:
\n bleeding:
\n enabled: true
\n chance: 0.15
\n damage_per_second: 1.0
\n duration_seconds: 10
\n cure_item: bandage
\n“`<\/p>\n
\n\/gun givepouch ar_ammo 300 PlayerName
\n“`<\/p>\n
\ncombatgun:
\n language: vi # en | vi | (any lang\/xx.yml)
\n“`<\/p>\n
\n## \ud83d\udd0c Plugin Integrations<\/p>\n
\n| :— | :— | :— |
\n| `%combatgun_gun_name%` | `AK47` | Display name of held gun |
\n| `%combatgun_gun_id%` | `ak47` | Internal ID of held gun |
\n| `%combatgun_gun_rarity%` | `epic` | Rarity of held gun |
\n| `%combatgun_ammo%` | `24` | Current magazine ammo |
\n| `%combatgun_ammo_max%` | `30` | Magazine capacity |
\n| `%combatgun_ammo_reserve%` | `90` | Reserve ammo in inventory |
\n| `%combatgun_is_reloading%` | `true` | Whether player is reloading |
\n| `%combatgun_is_gun%` | `true` | Whether held item is a gun |<\/p>\n
\ncombatgun:
\n shop:
\n enabled: true
\n currency_symbol: “$”
\n guns:
\n ak47: 700.0
\n awm: 2500.0
\n knife: 100.0
\n“`<\/p>\n
\n\/gun buy ak47 # purchase for configured price
\n\/gun buy ak47 free # admin free-give (requires combatgun.admin)
\n“`<\/p>\n
\n\/rg flag
\n\/rg flag
\n\/rg flag
\n“`<\/p>\n
\ncombatgun:
\n anticheat:
\n exempt_ticks: 3
\n“`<\/p>\n
\n| :— | :— | :— |
\n| `\/gun statsreset
\n| `\/gun seasonreset confirm` | Wipe ALL player stats (season reset) | `combatgun.admin` |
\n| `\/gun give
\n| `\/gun giveammo
\n| `\/gun givepart
\n| `\/gun station [player]` | Give the Mechanical Crafting Table | `combatgun.admin` |
\n| `\/gun book [player]` | Give the Recipe Guide Book | `combatgun.admin` |
\n| `\/gun recipe
\n| `\/gun list [category]` | View all loaded weapons | `combatgun.admin` |
\n| `\/gun inspect [player]` | View deep stats of the held weapon | `combatgun.admin` |
\n| `\/gun reload` | Reload all configurations | `combatgun.admin` |
\n| `\/gun buy
\n| `\/gun givepouch
\n– `combatgun.use` \u2014 Allows shooting and using guns (default: `true`)
\n– `combatgun.use.
\n“`yaml
\nname: AK47
\ncategory: assault_rifles
\nammo_type: ar_ammo
\ndamage: 12
\nfire_rate: 10.0
\nmagazine_size: 30
\nreload_time: 2.6
\nheadshot_multiplier: 1.8
\ndamage_falloff_start: 35.0
\nmin_damage_multiplier: 0.5
\nrange: 72.0
\nblock_penetration: 0.8
\nentity_penetration: 0
\nrecoil:
\n pitch: 1.45
\n yaw: 0.42
\n spread: 0.24
\n recovery: 0.80
\nrarity: rare
\ncustom_model_data: 1001
\nsound: ENTITY_FIREWORK_ROCKET_BLAST
\nrecipe:
\n station: mechanical_crafting_table
\n ingredients:
\n steel_ingot: 6
\n gun_barrel: 1
\n spring: 2
\n hardwood: 3
\n“`<\/p>\n
\n“`yaml
\nname: Katana
\ncategory: melee
\nammo_type: none
\nrarity: epic
\ndamage: 10
\nfire_rate: 1.35
\nrange: 4.0
\nknockback: 0.3
\nsound: ENTITY_PLAYER_ATTACK_CRIT
\ncustom_model_data: 26002
\nrecipe:
\n station: mechanical_crafting_table
\n ingredients:
\n steel_ingot: 10
\n carbon_fiber: 2
\n leather_strip: 3
\n blade_core: 1
\n“`<\/p>\n
\n| :— | :—: | :— |
\n| `GunShootEvent` | \u2705 | Before each shot \u2014 cancel or set damage multiplier |
\n| `GunReloadEvent` | \u2705 | When a player starts reloading |
\n| `GunHitEvent` | \u274c | After damage is applied \u2014 full damage pipeline |
\n| `GunHeadshotEvent` | \u274c | When a shot lands in the head zone |
\n| `AttachmentApplyEvent` | \u2705 | Before an attachment is fitted to a gun |
\n| `AttachmentRemoveEvent` | \u2705 | Before an attachment is removed from a gun |<\/p>\n
\n@EventHandler
\npublic void onShoot(GunShootEvent event) {
\n if (isInsideArena(event.getShooter()))
\n event.setDamageMultiplier(2.0);
\n}<\/p>\n
\npublic void onReload(GunReloadEvent event) {
\n if (isCapturingObjective(event.getPlayer()))
\n event.setCancelled(true);
\n}<\/p>\n
\npublic void onHit(GunHitEvent event) {
\n \/\/ base damage, final damage, headshot flag, distance
\n plugin.getStats().record(
\n event.getShooter(), event.getGun().getId(),
\n event.getFinalDamage(), event.isHeadshot(), event.getDistance());
\n}<\/p>\n
\npublic void onHeadshot(GunHeadshotEvent event) {
\n event.getShooter().giveExp(5);
\n}
\n“`<\/p>\n
\nCombatGunAPI api = CombatGunAPI.getInstance();<\/p>\n
\nGunData gun = api.getGun(“ak47”);
\nCollection
\nItemStack gunItem = api.createGunItem(“ak47”);
\nItemStack ammo = api.createAmmoItem(“ar_ammo”, 30);<\/p>\n
\nboolean isGun = api.isGun(item);
\nString gunId = api.getGunId(item);<\/p>\n
\nboolean isReloading = api.isReloading(player.getUniqueId());<\/p>\n
\nboolean shopEnabled = plugin.getHookManager().getVaultHook().isEnabled();
\nboolean wgActive = plugin.getHookManager().getWorldGuardHook().isAvailable();
\n“`<\/p>\n
\n2. Drop it into your server’s `plugins` folder.
\n3. (Optional) Install any soft-depend plugins you want: PlaceholderAPI, Vault, WorldGuard, Vulcan, Matrix.
\n4. Restart the server to generate default configurations.
\n5. (Optional) Add a Resource Pack to see 3D gun models.<\/p>\n
\n– **Server**: Paper\/Spigot 1.21+
\n– **Java**: 21 or higher
\n– **Required dependencies**: None (standalone plugin)
\n– **Optional dependencies**: PlaceholderAPI, Vault + economy plugin, WorldGuard, Vulcan, Matrix<\/p>\n
\n– Fixed friendly-fire scoreboard team detection using player scoreboard instead of main scoreboard \u2014 could allow friendly-fire bypass
\n– Fixed `recentDamage` memory leak: entries now removed on player quit and death events
\n– Fixed shared `static Random` contention: replaced with `ThreadLocalRandom.current()` (per-thread, no lock, better entropy)
\n– Fixed async SQLite connection safety: `incrementGunKill()` and `getGunKills()` now synchronized alongside `flushBuffer()`<\/p>\n
\n– New `AttachmentApplyEvent` and `AttachmentRemoveEvent` (cancellable) \u2014 fired on `\/gun attach` and `\/gun detach`
\n– New `DamageCalculator` utility class \u2014 centralises all damage math extracted from `GunListener` (headshots, falloff, spread, pellets)
\n– New `kills_by_gun_detail` SQLite table (schema v3) \u2014 per-kill log with timestamp, weapon, headshot flag
\n– New commands: `\/gun statsreset
\n– `GunListener` God Class partially refactored \u2014 4 methods delegate to `DamageCalculator`<\/p>\n
\n– Fixed thread-safety data race in `StatsManager` stat buffer (ConcurrentHashMap)
\n– Fixed silent loading of invalid gun configs (YAML validation with clear per-field errors)
\n– `StatsManager` leaderboard query optimized with a `kills DESC` index (schema migration v2)
\n– Shop price reads now cached in memory; invalidated on `\/gun reload`
\n– Config version detection warns admins when `config.yml` is outdated after an update<\/p>\n
\n– Ammo Pouch no longer loses items when the inventory is full
\n– Reload task CPU usage reduced by 50% (changed from 1 tick to 2 tick interval)
\n– `isHeadshot()` now works accurately when the player is crouching
\n– `craftFromStation()` properly rolls back ingredients if crafting fails
\n– `BleedingManager` now uses wall-clock time for accurate damage even during server lag
\n– `applyRecoil()` is now fully null-safe
\n– Fixed race condition in `onItemHeldChange`<\/p>\nFriendly fire still occurring despite being disabled<\/b><\/summary>\n
\n* Ensure teams are set up with `\/team add
\n* Test with `combatgun.team_provider: scoreboard` in `config.yml`<\/p>\n<\/details>\nGuns not working \/ can’t shoot<\/b><\/summary>\n
\n* Make sure the world is not blacklisted in `config.yml`
\n* If using WorldGuard, check if the region has `gun-shooting deny`
\n* Try `\/gun give ak47` and test in a clean area
\n* Use Paper \u2014 Spigot is not supported<\/p>\n<\/details>\nAmmo not found \/ can’t reload<\/b><\/summary>\n
\n* Craft ammo at a Vanilla Crafting Table or Mechanical Crafting Table
\n* Check `ammo_type` in the gun’s YAML matches a defined ammo type in `config.yml`
\n* Run `\/gun reload` after editing configs<\/p>\n<\/details>\nRecipes not showing in crafting table<\/b><\/summary>\n
\n* Give yourself the Recipe Guide Book: `\/gun book`
\n* Ensure the ingredient IDs in the gun YAML match those defined in `config.yml`<\/p>\n<\/details>\nConsole warning: “config.yml is OUTDATED”<\/b><\/summary>\n
\n* Back up your current `config.yml`, delete it, and restart the server to regenerate a fresh one.
\n* Then manually copy over your custom settings (world lists, shop prices, effects, etc.) from the backup.
\n* The plugin loads normally even with an outdated config \u2014 default values are used for missing keys.<\/p>\n<\/details>\nGun config not loading \/ “config validation failed” warning<\/b><\/summary>\n
\n* Check the listed fields: `damage`, `fire_rate`, `magazine_size`, `reload_time` must all be greater than 0.
\n* `burst_count` must be at least 1. `name` cannot be blank.
\n* Fix the values in the gun’s YAML and run `\/gun reload`.<\/p>\n<\/details>\nLeaderboard (`\/gun leaderboard`) is slow on large servers<\/b><\/summary>\n
\n* The migration runs once on first startup of 2.0.4. If you still experience slowness, ensure the server was fully restarted (not `\/reload`).<\/p>\n<\/details>\nAmmo Pouch destroying items when inventory is full<\/b><\/summary>\n
\n* Partial unpacks now save remaining ammo back into the pouch instead of destroying it<\/p>\n<\/details>\nReload taking wrong amount of time \/ inconsistent<\/b><\/summary>\n
\n* If still wrong, check `reload_time` in the gun’s YAML (in seconds)<\/p>\n<\/details>\nHeadshots not registering correctly<\/b><\/summary>\n
\n* Headshot detection uses the top 20% of the entity hitbox, adjusted for crouch state<\/p>\n<\/details>\nBleeding damage lower than configured<\/b><\/summary>\n
\n* Damage is now accurate even under server lag<\/p>\n<\/details>\nPlugin crashes on startup<\/b><\/summary>\n
\n* Check console for `[CombatGunSSS]` error lines indicating which manager failed
\n* Common cause: corrupted `config.yml` or invalid gun YAML syntax
\n* Fix the config, then restart (do not use `\/reload`)<\/p>\n<\/details>\nNullPointerException when shooting<\/b><\/summary>\n
\n* If persisting: check that `HookManager` is not null in the stack trace and update to latest version<\/p>\n<\/details>\nAnti-cheat flagging recoil movement<\/b><\/summary>\n
\n* Increase `combatgun.anticheat.exempt_ticks` in `config.yml` (default: `3`)
\n* The plugin auto-detects and registers exemptions via reflection \u2014 no API jar needed<\/p>\n<\/details>\nPlaceholderAPI placeholders showing as raw text<\/b><\/summary>\n
\n* Ensure PlaceholderAPI is loaded before CombatGunSSS (restart, not `\/reload`)
\n* Test with `\/papi parse me %combatgun_gun_name%`<\/p>\n<\/details>\nVault shop not working<\/b><\/summary>\n
\n* Set `combatgun.shop.enabled: true` in `config.yml`
\n* Confirm the gun ID exists in `combatgun.shop.guns` price list
\n* Use `\/gun buy \/reload breaks the plugin<\/b><\/summary>\n
\n* Use `\/gun reload` to hot-reload gun configs, language files, and settings without restarting<\/p>\n<\/details>\nCustom gun YAML not loading<\/b><\/summary>\n
\n* Run `\/gun reload` \u2014 check console for warnings about your file
\n* Ensure required fields are present: `name`, `category`, `ammo_type`, `damage`, `magazine_size`
\n* YAML is whitespace-sensitive \u2014 use a validator like yaml.org\/start.html<\/p>\n<\/details>\n
\n> This plugin is built on the **Paper\/Spigot 1.21** API and requires **Java 21** or higher.<\/p>\n
\n> For support and updates, check the repository or contact the developer.<\/p>\n","protected":false},"excerpt":{"rendered":"