CombatGunSSS

[1.0.3] - 2026-04-09

Added

Action Bar HUD

• New persistent ammo HUD displayed on the action bar while holding any ranged weapon.
• Format: 🔫 <GunName> ▐████████████░░░░▌ 22 / 30 • 90
  • Gun name is colored by rarity: white (common) → aqua (rare) → light purple (epic) → gold (legendary).
  • Visual bar transitions from green (full) to gold (≤ 25%) to red (≤ 10%) as ammo depletes.
  • Reserve count turns red when the player has no reserve ammo left.
• HUD yields automatically to the reload progress bar during active reloads — no visual conflict.
• Immediate update on every shot (no delay waiting for the next tick).
• Configurable via new combatgun.hud config block:
  • enabled (boolean, default true) — toggle the HUD entirely.
  • update_interval_ticks (integer, default 5) — refresh rate in ticks. Lower = smoother, minimum 1.

Auto-Reload When Empty

• New config key combatgun.auto_reload_when_empty (boolean, default true).
• When enabled, CombatGunSSS automatically starts a reload after a gun fires its last round, saving the player from manually pressing [F].
• Auto-reload respects the existing GunReloadEvent — other plugins can still cancel it.
• Set to false for hardcore or manual-reload server modes.

Developer API — GunHitEvent

• New informational event GunHitEvent, fired immediately after a bullet successfully damages a living entity.
• Provides the complete damage pipeline in a single event:
  • getBaseDamage() — damage before falloff and headshot multiplier.
  • getFinalDamage() — damage actually applied after all multipliers.
  • isHeadshot() — whether the hit registered as a headshot.
  • getDistance() — distance in blocks from shooter eye to hit position.
  • getShooter(), getTarget(), getGun() — full context.
• Intended for stat tracking, cosmetic side-effects, or per-hit reward systems. Not cancellable (damage is already done by the time the event fires).

Developer API — GunShootEvent.getBaseDamage()

• New method on the existing GunShootEvent, available pre-shot before any multipliers are applied.
• Returns gun.getDamage() * gun.getProjectileDamageMultiplier().
• Useful for pre-shot checks such as arena minimum-damage caps or logging without recalculating manually.

Changed

• CombatGunAPI — added GunHitEvent to the CUSTOM_EVENTS documentation array and updated Javadoc to list all four custom events with descriptions.
• CombatGunSSSPlugin — registers and stops HudManager; logs HUD: ON/OFF to console on startup.
• GunListener — removed private sendAmmoBar() helper (replaced by HudManager); calls hudManager.sendNow() after each shot for an instant HUD update; applies auto_reload_when_empty config check before triggering reload on empty magazine.

Fixed

• GunHitEvent damage transparency — previously, third-party plugins had no way to observe the actual damage applied by a bullet (only the pre-shot GunShootEvent existed). Final damage, falloff, and headshot calculations were completely opaque after v1.0.2. GunHitEvent closes this gap.

---