CombatGunSSS

# 🔫 CombatGunSSS !(https://img.shields.io/badge/Version-2.3.0-blue.svg) !(https://img.shields.io/badge/Platform-Paper%20/%20Spigot-green.svg) !(https://img.shields.io/badge/Java-21-red.svg) **CombatGunSSS** is a high-performance, feature-rich Minecraft gun plugin designed for modern servers (1.21+). It brings a tactical, realistic combat experience with 46 uniquely configured weapons (40 firearms + 6 melee), advanced crafting mechanics, optimized hitscan technology, a full custom events API, and a growing ecosystem of plugin integrations. --- ## 🌟 Key Features - **🎯 Tactical Combat**: Realistic hitscan mechanics with accurate recoil, bullet spread, and headshot multipliers. - **⚔️ Melee System**: Left-click melee combat with range check, knockback, and separate cooldown system. - **🛡️ Advanced Penetration**: Projectiles can pass through "soft" blocks and multiple entities based on individual gun stats. - **🩸 Progressive Damage**: Distance-based **Damage Falloff** and configurable **Knockback** intensities. - **🛠️ Two-Tier Crafting System**: - **Vanilla Workbench**: Craft basic components with official **Recipe Book** support. - **Mechanical Crafting Table**: A custom 21-slot industrial GUI for assembling advanced firearms. - **📂 Interactive Recipe Browser**: Built-in visual guide inside the Mechanical Crafting Table — no commands needed! Browse by **Gun**, **Melee**, or **Ammo** category tabs to quickly find what you want to craft. - **📦 46 Built-in Weapons**: 40 ranged guns + 6 melee weapons with burst-fire, shotgun pellets, and melee logic. - **📉 Durability System**: Weapons can have limited usage and require repairs (fully configurable). - **📊 Persistent HUD**: Real-time action bar showing gun name (rarity-colored), visual ammo bar, current/max ammo, and reserve count. - **🔄 Auto-Reload**: Automatically reloads after firing the last round (toggleable). - **🗺️ WorldGuard Integration**: Block gun use inside protected regions with a custom `gun-shooting` flag. - **💰 Vault Shop**: Players purchase weapons via `/gun buy <id>` using server economy. - **📋 PlaceholderAPI**: 8 real-time placeholders for scoreboards, HUDs, and TAB plugins. - **🎯 ADS (Aim Down Sights)**: Per-gun aim-down-sights system. Shift+Right-click to toggle — reduces spread and applies movement penalty. - **🩸 Bleeding**: Optional damage-over-time on bullet hit. Cured by holding a bandage and pressing ``. - **🎒 Ammo Pouch**: Compressed ammo bag. Shift+Right-click to unpack into inventory. Give via `/gun givepouch`. - **🌐 Multi-Language (i18n)**: All messages live in `lang/en.yml` or `lang/vi.yml`. Add your own translation file. - **🛡️ Anti-Cheat**: Automatic exemptions for Vulcan and Matrix to prevent recoil false-positives. - **🔌 Developer API**: Full custom events — `GunShootEvent`, `GunReloadEvent`, `GunHitEvent`, `GunHeadshotEvent`. - **🤝 Friendly Fire Control**: Toggle friendly fire on/off with scoreboard team or permission-group detection. - **🎨 Toggleable Effects**: Every particle and sound effect can be individually enabled/disabled. Includes a master `sound_volume` control. - **💀 Custom Kill Messages**: Death messages show killer name, weapon name (colored by rarity), and headshot indicator. --- ## 🎮 Player Controls | Action | Control | | :--- | :--- | | **Shoot** | `Right Click` | | **Reload** | `Swap Hand Key ` | | **Melee Attack** | `Left Click` | | **Buy a weapon** | `/gun buy <id>` | | **Crafting** | `Right Click` on Mechanical Crafting Table | --- ## 🔫 Weapon Categories ### Ranged Weapons (39) - **Assault Rifles**: AK47, M4A1, SCAR, AUG, FAMAS, G36, Groza, AN94, M14, ParaFAL, XM8, Kingfisher - **SMGs**: MP5, P90, Vector, Bizon, UMP, Thompson, MAC-10, MP40, VSS, CG15 - **Snipers**: AWM, M24, Kar98k, M82B, M107, VSK94 - **Shotguns**: M1014, SPAS-12, MAG-7, M1887, M590, Trogon - **Pistols**: Desert Eagle, G18, USP, M1917, M1873, M500 ### Melee Weapons (6) - **Bat**: Common, fast swing - **Knife**: Common, highest attack speed - **Pan**: Rare, defensive knockback - **Parang**: Rare, balanced damage/speed - **Katana**: Epic, high damage - **Scythe**: Legendary, maximum damage --- ## 🔫 Technical Weapon Stats Every weapon in CombatGunSSS features a deep set of configurable properties: - **Damage Falloff**: Define exactly at what block distance damage begins to drop (`damage_falloff_start`) and the minimum damage floor (`min_damage_multiplier`). - **Recoil & Spread**: Independent **Pitch** (vertical) and **Yaw** (horizontal) kick per shot, plus **Movement Spread** penalties while moving or jumping. - **Burst Fire**: Configure weapons to fire multiple rounds per trigger pull (`burst_count`) with custom delays. - **Shotgun Logic**: Support for multiple projectiles per shot (`projectiles_per_shot`) with per-pellet damage calculation. - **Durability**: Set a maximum usage limit (`max_durability`). Weapons will break and become unusable until repaired. - **Penet