CombatGunSSS

[1.0.2] - 2026-04-07

Added

Developer API — Custom Events

• GunShootEvent (cancellable) — fired before every ranged shot. Other plugins can cancel the shot entirely or modify damage via setDamageMultiplier(double). Useful for anti-cheat integration, zone-based restrictions, or temporary power-up effects.
• GunReloadEvent (cancellable) — fired when a player starts a reload. Cancel to block reloading in specific zones or game states (e.g., "no reload during objective capture").
• GunHeadshotEvent (informational) — fired on every confirmed headshot. Provides shooter, target, gun data, and final damage for kill-feed plugins, stat trackers, or custom rewards.

Friendly Fire Control

• New config keys combatgun.friendly_fire (boolean, default true) and combatgun.team_provider (string).
  • scoreboard mode — uses vanilla Minecraft scoreboard teams (/team add …). Players sharing a team cannot shoot each other when friendly fire is off.
  • permission_group mode — players sharing any combatgun.team.<n> permission node are considered teammates.
  • Both ranged shots and melee attacks respect the friendly-fire setting.

Toggleable Effects

• New combatgun.effects config block. Every visual and audio effect can now be enabled or disabled individually without recompiling:
  • bullet_trail, muzzle_flash, hit_particles, block_impact, headshot_particles
  • gun_sound, melee_sound, melee_particles
  • sound_volume — master volume multiplier for all gun sounds (0.0 – 2.0, default 1.5)
• Disabling heavy effects (bullet trails, muzzle flash) can meaningfully reduce particle load on high-population servers.

Kill / Death Messages

• Gun kills now override the vanilla death message with a formatted line showing killer name, weapon name (colored by rarity), and a ☠ HEADSHOT prefix when applicable.
• Implemented via a short-lived DamageRecord map (TTL 5 seconds) that links the last gun shot to the subsequent death event — no false attribution on delayed deaths.

Fixed

Memory Leak in AmmoManager

• lastShot and lastMeleeAttack were plain HashMap entries that were only removed when clearPlayer() was called on a clean quit or death. Players who disconnected via server crash, network drop, or /kick left stale entries that accumulated indefinitely.
• Fix: Added AmmoManager.pruneStale(long olderThan) and a periodic async scheduler in onEnable() that calls it every 2 minutes, removing any entry whose timestamp is older than 60 seconds.

getMeleeCooldownRemaining Always Returned Wrong Value

• The zero-argument overload getMeleeCooldownRemaining(UUID) contained a hardcoded cooldownMs = 1000 with a comment acknowledging the bug. It would always calculate the remaining cooldown against 1 second regardless of the actual weapon's fire rate.
• Fix: Removed the broken zero-argument overload entirely. Only the correct getMeleeCooldownRemaining(UUID, long weaponCooldownMs) overload is retained. All callers already passed the weapon cooldown.

Reload Not Cancelled on Teleport / World Change

• When a player teleported or changed worlds while a reload was in progress, the reload BukkitRunnable continued executing in the background. If the reload completed, ammo was consumed and applied to the gun even though the player was now in a different (possibly gun-banned) world.
• Fix: Added cancelReload(player, false) calls to both onTeleport and onChangedWorld event handlers, matching the existing behaviour of onDeath and onQuit.

isMelee() Could Throw NullPointerException

• GunData.isMelee() evaluated "none".equalsIgnoreCase(ammoType). If a gun's YAML omitted ammo_type entirely, ammoType was null and this call threw an NPE silently swallowed by the YAML loader, causing the weapon to not load.
• Fix: isMelee() is now a stored boolean field derived at construction time. It is true when category == "melee" OR ammoType is null, blank, or "none".

Refactored

GunData — Builder Pattern

• Replaced the 27-parameter constructor with a fluent GunData.Builder. Every field has a sensible default so callers only set what differs. This prevents silent argument-order bugs (two adjacent double fields are indistinguishable to the compiler in a positional constructor).
• GunManager.parseGun() updated to use the builder; all other call sites remain source-compatible.

Bullet Trail — Adaptive Density + Lighter Particle

• Trail step count now scales with distance: steps = distance < 20 ? distance × 2 : distance × 0.8, capped at 40. Previously always min(60, distance × 2) which produced up to 80 particles on sniper shots.
• Switched from Particle.SMOKE to Particle.DUST (small grey, 0.3f radius) — lighter on client render without a visible quality difference at combat distances.

---