CombatGunSSS

[2.0.5] - 2026-04-26

Added

AttachmentApplyEvent and AttachmentRemoveEvent — Developer API

• Two new cancellable events fire when a player attaches or removes an attachment from a gun.
• AttachmentApplyEvent — fired before fitAttachment() writes the PDC key. Provides getPlayer(), getGunData(), getIncoming() (attachment being fitted), and getReplacedAttachment() (previously occupied slot, or null). Cancellable — cancel to block the attachment action.
• AttachmentRemoveEvent — fired before removeAttachment() clears the PDC key. Provides getPlayer(), getGunData(), getSlot(), and getRemoved() (the attachment being stripped). Cancellable — cancel to block the removal.
• AttachmentManager.fitAttachment(Player, ItemStack, GunData, String) — new overload that fires the apply event. The no-player overload is retained for internal use.
• AttachmentManager.removeAttachment(Player, ItemStack, GunData, AttachmentType) — new overload that fires the remove event.
• Example use-cases: locking legendary weapons from modification, auto-returning detached attachments to the player's inventory, logging equipment changes, restricting attachments in specific regions.

DamageCalculator — Centralised Damage Math Utility

• New util/DamageCalculator.java extracts all damage-pipeline calculations from GunListener, making them independently testable and accessible to add-on plugins.
• Static methods:
  • baseDamage(GunData, double eventMult) — gun damage × projectile multiplier × event multiplier.
  • falloffMultiplier(GunData, double dist) — linear range-based damage reduction from damageFalloffStart to min floor.
  • headshotMultiplier(GunData, boolean headshot) — returns headshotMultiplier or 1.0.
  • finalDamage(GunData, double dist, boolean headshot, double eventMult) — full pipeline in one call.
  • isHeadshot(double hitY, double baseY, double height, boolean crouching) — single source of truth for headshot detection, accounting for crouch state.
  • effectiveSpread(GunData, double scopeSpread, boolean scoped, boolean ads, double moveMult) — spread value for all fire modes.
  • pelletSpread(double baseSpread, boolean multiPellet) — per-pellet spread for shotguns.
• Named constants: HEAD_ZONE_START (0.80), CROUCH_FACTOR (0.85), SHOTGUN_SPREAD_FACTOR (1.45) — previously magic numbers scattered across GunListener.
• GunListener now delegates all damage math and spread calculations to DamageCalculator. The private computeFalloffMultiplier() method has been removed (logic moved to DamageCalculator.falloffMultiplier()).

StatsManager — Per-Kill Detail Log (kills_by_gun_detail table)

• New SQLite table kills_by_gun_detail added via schema migration v3. Stores one row per kill with uuid, gun_id, headshot flag, and Unix timestamp (ms).
• Enables future features: per-weapon leaderboards, session-based kill analytics, and season resets that preserve historical totals in the detail log while zeroing the aggregate counters.
• Two covering indexes (idx_kbgd_uuid, idx_kbgd_gun) ensure per-player and per-weapon queries stay fast as the table grows.
• Schema migration runs automatically on first startup of 2.0.5 — no manual SQL required.

GunCommand — Season Reset and Per-Player Stats Reset

• /gun statsreset <player> — resets kills, deaths, headshots, gun kills, and detail records for a single online player. Wipes the in-memory buffer and schedules async DB deletes across all three stat tables.
• /gun seasonreset confirm — resets ALL players' stats (requires the literal confirm argument as a safeguard against accidental use). Clears the in-memory buffer and truncates player_stats, gun_kills, and kills_by_gun_detail in a single transaction. Prints a gold confirmation message on success.
• Both commands require combatgun.admin permission.
• Both commands fail gracefully with a clear error if StatsManager is disabled (SQLite unavailable).

Improved

GunListener — God Class Reduction

• performShot() spread logic (previously a three-branch if/else if/else block) replaced with a single DamageCalculator.effectiveSpread() call.
• applyEntityDamage() damage calculation (previously inline) replaced with DamageCalculator.finalDamage() and DamageCalculator.baseDamage().
• isHeadshot() private method now delegates entirely to DamageCalculator.isHeadshot() — single source of truth for headshot geometry.
• Removed computeFalloffMultiplier() private method (~7 lines) — logic now lives in DamageCalculator.

StatsManager — Schema Version Bumped to 3

• SCHEMA_VERSION constant updated from 2 to 3.
• recordKill() now passes the headshot flag to incrementGunKill() so both the aggregate gun_kills table and the new kills_by_gun_detail table are updated in one async task.
• resetStats(UUID) now also deletes from kills_by_gun_detail in addition to player_stats and gun_kills.
• resetAllStats() truncates all three stat tables in a single transaction.

---