🔫 CombatGunSSS

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

@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

Download the CombatGunSSS-1.1.0.jar.
Drop it into your server's plugins folder.
(Optional) Install any soft-depend plugins you want: PlaceholderAPI, Vault, WorldGuard, Vulcan, Matrix.
Restart the server to generate default configurations.
(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.0.3 — Bug-fix release: 7 bugs fixed

Ammo Pouch no longer loses items when the inventory is full
Reload task CPU usage reduced by 50% (changed from 1 tick to 2 tick interval)
isHeadshot() now works accurately when the player is crouching
craftFromStation() properly rolls back ingredients if crafting fails
BleedingManager now uses wall-clock time for accurate damage even during server lag
applyRecoil() is now fully null-safe
Fixed race condition in onItemHeldChange

2.0.2 — Hotfix: Fixed NPE when shooting caused by GunListener trying to cache HudManager before it was initialized — resolved using lazy access.

2.0.1 — Hotfix: plugin crash on startup isolated; StatsManager/HookManager failures degrade gracefully; Material.GRAY_DYE compile fix; null-safety throughout.

2.0.0 — Weapon attachments (silencer, scope, extended mag, grip); throwable items (frag, smoke, flashbang); kill stats & leaderboard (SQLite); 4 new PlaceholderAPI placeholders.

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

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

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

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

1.0.1 — Recipe Book registration fix; ammo type disambiguation fix; double-click exploit fix; debug spam removed.

🔍 Troubleshooting

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

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.

CombatGunSSS