🔫 CombatGunSSS

!Version !Platform !Java

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.

---

🌟 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!
• 📦 45 Built-in Weapons: 39 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 [F].
• 🎒 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 [F]
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.
• Penetration: Define how many blocks (block_penetration) or entities (entity_penetration) a single bullet can pass through.
• Melee Range: Maximum attack distance for melee weapons (default: 4 blocks).
• Knockback: Push strength for both ranged and melee weapons.

---

📁 Folder Structure

plugins/CombatGunSSS/
├── config.yml              # Main configuration
├── guns/                   # Ranged weapon configs (39 built-in + custom)
│   ├── ak47.yml
│   ├── m4a1.yml
│   └── ...
├── melees/                 # Melee weapon configs (6 built-in + custom)
│   ├── katana.yml
│   ├── knife.yml
│   └── ...
└── README.md

Custom Weapons: Create your own YAML files in guns/ or melees/ folders and run /gun reload.

---

⚒️ Crafting Mechanics

1. Components (The Basics)

Craft raw materials like Steel Ingots, Gun Barrels, and Springs at a standard Crafting Table. These recipes are automatically unlocked in your Vanilla Recipe Book.

2. Assembly (The Advanced)

Place your components into the Mechanical Crafting Table.

• Non-grid-based: Just throw the ingredients into the 21-slot input area.
• Visual Preview: The output slot shows your gun stats before you build it.
• Recipe Guide: Click the Glowing Book icon in the station to browse all weapon requirements.

---

📊 Action Bar HUD

While holding any ranged weapon, CombatGunSSS displays a persistent HUD on your action bar:

🔫 AK47  ▐████████████░░░░▌  22 / 30  •  90

• Gun name is colored by rarity: white (common) → aqua (rare) → light purple (epic) → gold (legendary).
• Visual bar transitions green → gold (≤25%) → red (≤10%) as ammo depletes.
• Reserve count turns red when you have no backup ammo left.
• The HUD automatically yields to the reload progress bar during active reloads.

combatgun:
  hud:
    enabled: true
    update_interval_ticks: 5

🎯 ADS — Aim Down Sights

Enable ADS per gun in its YAML config:

ads:
  enabled: true
  spread_multiplier: 0.35   # 65% tighter accuracy while ADS
  movement_penalty: 0.6     # movement speed while ADS active

Control: Shift+Right-click to toggle ADS on/off. Action bar shows 🎯 ADS [spread ×0.35].

ADS exits automatically when you switch items, teleport, or die. Scopeable sniper rifles use the traditional sneak-to-scope mechanic instead of ADS.

---

🩸 Bleeding

An optional damage-over-time system. When enabled, bullets hitting players have a configurable chance to cause bleeding.

combatgun:
  bleeding:
    enabled: true
    chance: 0.15
    damage_per_second: 1.0
    duration_seconds: 10
    cure_item: bandage

Hold a bandage (crafting component) and press [F] to cure. Bleeding stops automatically on death.

---

🎒 Ammo Pouch

A compressed ammo container that stores hundreds of rounds in a single slot.

/gun givepouch ar_ammo 300 PlayerName

Shift+Right-click to unpack all rounds into your inventory. Surplus rounds are left if the inventory is full.

---

🌐 Multi-Language

Set the active language in config.yml:

combatgun:
  language: vi   # en | vi | (any lang/xx.yml)

Bundled: English (en) and Tiếng Việt (vi). Add a custom translation by placing lang/xx.yml in the plugin data folder and running /gun reload.

---

🔌 Plugin Integrations

PlaceholderAPI

8 real-time placeholders for use in scoreboards, TAB, AdvancedHud, and similar plugins:

Placeholder	Example	Description
%combatgun_gun_name%	AK47	Display name of held gun
%combatgun_gun_id%	ak47	Internal ID of held gun
%combatgun_gun_rarity%	epic	Rarity of held gun
%combatgun_ammo%	24	Current magazine ammo
%combatgun_ammo_max%	30	Magazine capacity
%combatgun_ammo_reserve%	90	Reserve ammo in inventory
%combatgun_is_reloading%	true	Whether player is reloading
%combatgun_is_gun%	true	Whether held item is a gun

Vault Shop

Enable the shop in config.yml, set prices per gun, then players can buy weapons in-game:

combatgun:
  shop:
    enabled: true
    currency_symbol: "$"
    guns:
      ak47:  700.0
      awm:  2500.0
      knife: 100.0

/gun buy ak47          # purchase for configured price
/gun buy ak47 free     # admin free-give (requires combatgun.admin)

WorldGuard

The custom flag gun-shooting is automatically registered when WorldGuard is present:

/rg flag <region> gun-shooting deny    # block all guns in region
/rg flag <region> gun-shooting allow   # explicitly allow
/rg flag <region> gun-shooting -g      # remove flag (inherit parent)

Falls back to WorldGuard's built-in PVP flag if gun-shooting is not set on a region.

Anti-Cheat (Vulcan / Matrix)

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.

combatgun:
  anticheat:
    exempt_ticks: 3

---

📜 Commands & Permissions

Command	Description	Permission
/gun statsreset <player>	Reset a specific player's stats	combatgun.admin
/gun seasonreset confirm	Wipe ALL player stats (season reset)	combatgun.admin
/gun give <id> [player]	Give a specific weapon	combatgun.admin
/gun giveammo <id> [amt] [player]	Give custom ammunition	combatgun.admin
/gun givepart <id> [amt] [player]	Give crafting components	combatgun.admin
/gun station [player]	Give the Mechanical Crafting Table	combatgun.admin
/gun book [player]	Give the Recipe Guide Book	combatgun.admin
/gun recipe <id>	Show the full crafting chain in chat	combatgun.admin
/gun list [category]	View all loaded weapons	combatgun.admin
/gun inspect [player]	View deep stats of the held weapon	combatgun.admin
/gun reload	Reload all configurations	combatgun.admin
/gun buy <id>	Purchase a weapon (requires Vault)	combatgun.use
/gun givepouch <ammo_id> <amount> [player]	Give an ammo pouch	combatgun.admin

Player Permissions

• combatgun.use — Allows shooting and using guns (default: true)
• combatgun.use.<gun_id> — Per-gun permission node (e.g. combatgun.use.awm)

---

🔧 Configuration Examples

Ranged Weapon (AK47)

name: AK47
category: assault_rifles
ammo_type: ar_ammo
damage: 12
fire_rate: 10.0
magazine_size: 30
reload_time: 2.6
headshot_multiplier: 1.8
damage_falloff_start: 35.0
min_damage_multiplier: 0.5
range: 72.0
block_penetration: 0.8
entity_penetration: 0
recoil:
  pitch: 1.45
  yaw: 0.42
  spread: 0.24
  recovery: 0.80
rarity: rare
custom_model_data: 1001
sound: ENTITY_FIREWORK_ROCKET_BLAST
recipe:
  station: mechanical_crafting_table
  ingredients:
    steel_ingot: 6
    gun_barrel: 1
    spring: 2
    hardwood: 3

Melee Weapon (Katana)

name: Katana
category: melee
ammo_type: none
rarity: epic
damage: 10
fire_rate: 1.35
range: 4.0
knockback: 0.3
sound: ENTITY_PLAYER_ATTACK_CRIT
custom_model_data: 26002
recipe:
  station: mechanical_crafting_table
  ingredients:
    steel_ingot: 10
    carbon_fiber: 2
    leather_strip: 3
    blade_core: 1

---

🔌 Developer API

Custom Events

Event	Cancellable	When it fires
GunShootEvent	✅	Before each shot — cancel or set damage multiplier
GunReloadEvent	✅	When a player starts reloading
GunHitEvent	❌	After damage is applied — full damage pipeline
GunHeadshotEvent	❌	When a shot lands in the head zone
AttachmentApplyEvent	✅	Before an attachment is fitted to a gun
AttachmentRemoveEvent	✅	Before an attachment is removed from a gun

@EventHandler
public void onShoot(GunShootEvent event) {
    if (isInsideArena(event.getShooter()))
        event.setDamageMultiplier(2.0);
}

@EventHandler
public void onReload(GunReloadEvent event) {
    if (isCapturingObjective(event.getPlayer()))
        event.setCancelled(true);
}

@EventHandler
public void onHit(GunHitEvent event) {
    // base damage, final damage, headshot flag, distance
    plugin.getStats().record(
        event.getShooter(), event.getGun().getId(),
        event.getFinalDamage(), event.isHeadshot(), event.getDistance());
}

@EventHandler
public void onHeadshot(GunHeadshotEvent event) {
    event.getShooter().giveExp(5);
}

API Instance

CombatGunAPI api = CombatGunAPI.getInstance();

// Query guns
GunData gun              = api.getGun("ak47");
Collection<GunData> all  = api.getAllGuns();

// Create items
ItemStack gunItem         = api.createGunItem("ak47");
ItemStack ammo            = api.createAmmoItem("ar_ammo", 30);

// Check items
boolean isGun             = api.isGun(item);
String  gunId             = api.getGunId(item);

// Player state
boolean isReloading       = api.isReloading(player.getUniqueId());

// Hook state
boolean shopEnabled       = plugin.getHookManager().getVaultHook().isEnabled();
boolean wgActive          = plugin.getHookManager().getWorldGuardHook().isAvailable();

---

🚀 Installation

1. Download the CombatGunSSS-2.1.0.jar.
2. Drop it into your server's plugins folder.
3. (Optional) Install any soft-depend plugins you want: PlaceholderAPI, Vault, WorldGuard, Vulcan, Matrix.
4. Restart the server to generate default configurations.
5. (Optional) Add a Resource Pack to see 3D gun models.

Requirements

• Server: Paper/Spigot 1.21+
• Java: 21 or higher
• Required dependencies: None (standalone plugin)
• Optional dependencies: PlaceholderAPI, Vault + economy plugin, WorldGuard, Vulcan, Matrix

---

📋 Changelog

See CHANGELOG.md for the full version history.

2.1.0 — Bug-fix release: 8 bugs fixed

• Fixed StatsManager.flushBuffer() race condition — kill data silently lost under concurrent load
• Fixed ThrowableManager tasks not cancelled on plugin disable — IllegalPluginAccessException on every disable
• Fixed clearAds() removing scope slowness incorrectly
• Fixed all ReloadManager messages bypassing i18n (hardcoded English shown to vi servers)
• Fixed BleedingManager and ThrowableManager using Math.random() instead of ThreadLocalRandom
• Fixed AttachmentManager and GunListener duplicate import statements
• Fixed getRecentDamage() exposing mutable map reference; added safe getDamageRecord() lookup

2.0.6 — Bug-fix release: 4 bugs fixed

• Fixed friendly-fire scoreboard team detection using player scoreboard instead of main scoreboard — could allow friendly-fire bypass
• Fixed recentDamage memory leak: entries now removed on player quit and death events
• Fixed shared static Random contention: replaced with ThreadLocalRandom.current() (per-thread, no lock, better entropy)
• Fixed async SQLite connection safety: incrementGunKill() and getGunKills() now synchronized alongside flushBuffer()

🔍 Troubleshooting

Friendly fire still occurring despite being disabled

• Fixed in 2.0.6 — team detection now uses the main scoreboard instead of each player's personal view
• Ensure teams are set up with /team add <name> and players added with /team join <name> <player>
• Test with combatgun.team_provider: scoreboard in config.yml

Guns not working / can't shoot

• Check combatgun.use permission is granted to players
• Make sure the world is not blacklisted in config.yml
• If using WorldGuard, check if the region has gun-shooting deny
• Try /gun give ak47 and test in a clean area
• Use Paper — Spigot is not supported

Ammo not found / can't reload

• Make sure you have the correct ammo type in your inventory (e.g. AR ammo for assault rifles)
• Craft ammo at a Vanilla Crafting Table or Mechanical Crafting Table
• Check ammo_type in the gun's YAML matches a defined ammo type in config.yml
• Run /gun reload after editing configs

Recipes not showing in crafting table

• Run /gun reload to re-register vanilla recipes
• Give yourself the Recipe Guide Book: /gun book
• Ensure the ingredient IDs in the gun YAML match those defined in config.yml

Console warning: "config.yml is OUTDATED"

• This warning appears when your config.yml has a lower config-version than the plugin expects.
• Back up your current config.yml, delete it, and restart the server to regenerate a fresh one.
• Then manually copy over your custom settings (world lists, shop prices, effects, etc.) from the backup.
• The plugin loads normally even with an outdated config — default values are used for missing keys.

Gun config not loading / "config validation failed" warning

• Added in 2.0.4 — guns with invalid configs now log a clear per-field error instead of loading silently.
• Check the listed fields: damage, fire_rate, magazine_size, reload_time must all be greater than 0.
• burst_count must be at least 1. name cannot be blank.
• Fix the values in the gun's YAML and run /gun reload.

Leaderboard (`/gun leaderboard`) is slow on large servers

• Fixed in 2.0.4 — a kills DESC index is now created automatically on the SQLite database.
• The migration runs once on first startup of 2.0.4. If you still experience slowness, ensure the server was fully restarted (not /reload).

Ammo Pouch destroying items when inventory is full

• Fixed in 2.0.3 — update the plugin
• Partial unpacks now save remaining ammo back into the pouch instead of destroying it

Reload taking wrong amount of time / inconsistent

• Fixed in 2.0.3 — reload task now runs every 2 ticks instead of 1 (50% less CPU, same reload duration)
• If still wrong, check reload_time in the gun's YAML (in seconds)

Headshots not registering correctly

• Fixed in 2.0.3 — crouching player hitbox now calculated correctly
• Headshot detection uses the top 20% of the entity hitbox, adjusted for crouch state

Bleeding damage lower than configured

• Fixed in 2.0.3 — BleedingManager now uses wall-clock time instead of tick counting
• Damage is now accurate even under server lag

Plugin crashes on startup

• Fixed in 2.0.1 — startup errors are now isolated per manager
• Check console for [CombatGunSSS] error lines indicating which manager failed
• Common cause: corrupted config.yml or invalid gun YAML syntax
• Fix the config, then restart (do not use /reload)

NullPointerException when shooting

• Fixed in 2.0.2 — lazy HudManager access prevents NPE at startup
• If persisting: check that HookManager is not null in the stack trace and update to latest version

Anti-cheat flagging recoil movement

• Ensure Vulcan or Matrix is listed in softdepend (already done automatically)
• Increase combatgun.anticheat.exempt_ticks in config.yml (default: 3)
• The plugin auto-detects and registers exemptions via reflection — no API jar needed

PlaceholderAPI placeholders showing as raw text

• Install PlaceholderAPI and run /papi reload
• Ensure PlaceholderAPI is loaded before CombatGunSSS (restart, not /reload)
• Test with /papi parse me %combatgun_gun_name%

Vault shop not working

• Make sure an economy plugin (EssentialsX, CMI, etc.) is installed alongside Vault
• Set combatgun.shop.enabled: true in config.yml
• Confirm the gun ID exists in combatgun.shop.guns price list
• Use /gun buy <id> free (admin) to test without balance requirement

/reload breaks the plugin

• Never use /reload — always do a full server restart
• Use /gun reload to hot-reload gun configs, language files, and settings without restarting

Custom gun YAML not loading

• Place the file inside plugins/CombatGunSSS/guns/ (ranged) or melees/ (melee)
• Run /gun reload — check console for warnings about your file
• Ensure required fields are present: name, category, ammo_type, damage, magazine_size
• YAML is whitespace-sensitive — use a validator like yaml.org/start.html

---

❓ FAQ

Does this work on Spigot?

No — CombatGunSSS requires Paper 1.21+. Spigot lacks several API features used internally.

Can I add my own guns?

Yes. Create a new .yml file in plugins/CombatGunSSS/guns/ following the same format as the built-in weapon files, then run /gun reload.

Can I disable specific guns?

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.

Does it support multiple worlds?

Yes. Configure a world whitelist or blacklist under combatgun.worlds in config.yml.

Is it laggy on large servers?

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.

Can I disable the crafting system?

Yes — 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.

Do I need a Resource Pack?

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.

Can I disable bleeding or the Ammo Pouch?

Yes. Set combatgun.bleeding.enabled: false or combatgun.ammo_pouch.enabled: false in config.yml.

Does it support ZombieApocalypseSSS?

Yes — CombatGunSSS is the recommended gun companion for ZombieApocalypseSSS. Guns deal full damage to all zombie types and trigger the noise / aggro system automatically.

Can other plugins listen to gun events?

Yes. Four custom events are exposed via the API: GunShootEvent (cancellable), GunReloadEvent (cancellable), GunHitEvent, and GunHeadshotEvent. See the Developer API section.

How do I give guns without the shop?

Use /gun give <id> [player] (requires combatgun.admin). Example: /gun give awm Steve.

---

Developed with ❤️ by Duong2012G.

---

[!NOTE] This plugin is built on the Paper/Spigot 1.21 API and requires Java 21 or higher.

[!TIP] For support and updates, check the repository or contact the developer.