Nothing in this release changes how your existing guns behave. Every new option defaults to what Pewpew did before, and the one behaviour that had to change is switched back on automatically for servers upgrading.

Config safety

• Config migrations. config.yml now carries a config-version. Pewpew migrates it on startup, keeps a .bak of the previous version next to it, and logs exactly what it changed.
• Typos are reported. Unknown fields in an item file used to be ignored in silence. spred: 2.0 or bulletcount: 8 now logs a warning naming the item, the file and the field. The item still loads.

Item files

New advanced: section in config.yml, all options off by default:

• extends: <id> copies another item's fields, then applies its own on top. The parent can live in any file in items/, so your own files can build on the bundled weapons, and chains work.
• abstract: true makes an entry a template only: never registered, never given, and it needs no name or itemModel.
• ammo-stats turns on the ammo stats below.

Shooting

• Spray patterns. Give a gun a fixed pattern of [horizontal, vertical] steps and recoil becomes something players can learn and pull against instead of a dice roll. patternLoop and patternReset control what happens past the end of the pattern and how long a pause resets it.
• Movement accuracy. spreadModifiers scales spread by what the shooter is doing: sprinting, walking, sneaking, standing, plus midair and inWater on top.
• Bloom. bloomPerShot, bloomMax and bloomDecay widen the cone while you hold the trigger and close it again when you stop.
• Ammo stats. Ammo items can carry damageMultiplier, velocityMultiplier and penetration (entities a shot passes through). Ammo multiplies the gun's numbers, it never replaces them, so baseDamage and damageType stay in charge. A gun remembers which ammo was loaded into it.
• damageType per gun. Defaults to minecraft:arrow as before. Set minecraft:generic for damage that ignores armor and Protection, so your configured numbers land exactly.
• burstDelay is configurable instead of a fixed 2 ticks.
• Multiple fire and hit sounds per weapon.
• Decimal fire rates, so a gun can fire faster than once per tick.

Fixed

• Bullet spread was not a cone. It rotated around the world axes, giving a square spread that shrank as you looked up or down. It is now a true cone of spread degrees in every direction. Upgrading servers keep the old maths via compatibility.legacy-spread; turn it off and retune spread when you are ready.
• Two memory leaks: hit tracking and per-player shooting state grew forever. Quitting now also cancels in-flight reload and autofire tasks.
• The OpenMinetopia hook silently allowed weapon use if its reflection broke. It now logs once and blocks until fixed or disabled.
• Legacy § colour codes are stripped from messages instead of reaching chat.

Permissions

• All command permissions are declared, with a pewpew.* parent.
• pewpew.use.<id> per item, defaulting to allowed. Negate it (-pewpew.use.awm) to stop a group shooting, throwing, or attaching to that item.

Developer API and Skript

• Five new events: kill, reload complete, scope, attachment, and hit block. Scope and attachment are cancellable; the kill event lets you rewrite the death message.
• Skript grows to 11 events, 9 expressions and 6 conditions, including pewpew ammo and pewpew bloom (both writable), pewpew attachment id, pewpew death message, and conditions like player is scoped in or the pewpew hit was a headshot.
• Skript is documented for the first time, in assets/docs/skript.md.

Integrations

• OpenMinetopia: blocks weapon use while handcuffed and in configured cities or worlds.

Internal

• JUnit tests (31) covering migrations, spread geometry, extends resolution and recoil patterns, plus a GitHub Actions build.
• -dev builds publish to the snapshots repository instead of releases.

Fixed

• Recoil no longer spins your camera while moving. Rotation is now sent as a relative delta, so it composes with your own mouse input instead of fighting the client's rotation over the network. This was the cause of the violent camera swinging when strafing and firing at the same time.
• selfKnockback now fires on every shot instead of only on a hit. Guns with a self shove launch you when you shoot at open air, and multi pellet guns shove you once per shot instead of once per connecting pellet.
• Recoil controllers no longer leak when a profile is configured with partial recovery; the recoil task now correctly shuts down when nobody is firing.

Added

• Per gun recoil profiles. New optional recoilProfile block on any gun, with ten tunables: verticalMean, verticalVariance, horizontalMean, horizontalVariance, smoothing, damping, recovery, recoveryPenalty, speed and maxAccumulation. Every gun used to share one hardcoded feel; now an AK can drift right while an M4 stays flat. See assets/docs/guns.md.
• recoveryPenalty the share of each kick the camera never gives back, so sustained fire walks your aim up the screen. 0.0 is full recovery.
• Set horizontalMean and horizontalVariance to 0 for pure vertical recoil.

Changed

• Default weapon configs rewritten. 27 guns across sidearms, SMGs, assault rifles, precision rifles, shotguns, support and launchers, plus a fun tier. Fire rates map to real cyclic rates, magazines and calibers match the real weapons, and each platform has its own recoil character.
• Ammo configs rewritten. 19 items covering every caliber the guns use, including boxed rounds, spare magazines and a 100 round linked belt.
• speed in a recoil profile now behaves as a timing factor that converges on the correct total rotation, rather than permanently scaling every movement.

Notes for existing setups

• Guns without a recoilProfile keep their previous behavior the block is optional and its defaults match the old hardcoded values.
• The rewritten guns.yml and ammo.yml renamed several ammo ids and ammoType tags. If you edited these files, your copies are untouched; if you want the new defaults, back yours up first.

Additions

• Guns with firingMode: projectile can now be explosive. Add an explosive: block for a rocket launcher that detonates on impact (blastRadius, explosionDamage, explosionKnockback), with optional block damage and terrain rebuild.
• Added grenade launchers via payload: the round flies as that throwable's model and inherits its fuse and effect (explosion, smoke, flash, poison, fire).
• Added projectileModel to change how a bullet looks in flight (e.g. minecraft:fire_charge), and trajectory: FLAT|ARC to control projectile drop.
• Added the PewpewGunExplodeEvent API and matching on pewpew gun explode: Skript event, with editable pewpew damage.

Swapped NMS internals for the standard Paper API, so PewPew runs across a wider range of server versions instead of being locked to one build.

Fixes

• Fixed a startup crash (NoClassDefFoundError) caused by the bStats metrics referencing Skript's shaded class instead of the bundled one.

Improvements

• The update notifier now links to Modrinth, and the download URL is a clickable link in chat.

New

• Per-gun knockback - guns can push the victim away (knockback) and shove the shooter back (selfKnockback). Both default to 0, so existing guns are unchanged.

• Tunable throwables - explosion damage/knockback, effect duration/amplifier, and fire duration are now per-item config (explosionDamage, explosionKnockback, effectDuration, effectAmplifier, fireTicks). Omit them and throwables behave exactly as before.

• Customizable messages - all player-facing text moved to messages.yml (MiniMessage), with built-in fallbacks for missing keys.

• WorldGuard support (optional) - registers a pewpew-guns region flag (default allow); deny it to block guns and throwables in a region. Enforced per shot, so full-auto stops on entering a protected area. No effect if WorldGuard isn't installed.

• CombatTagPlus support (optional) - combat-tags shooter and victim on a gun hit. No effect if CombatTagPlus isn't installed. Notes

Both integrations are optional soft-depends, toggleable in config.yml (integrations.worldguard.enabled, integrations.combattagplus.enabled). config.yml gains the integrations block automatically on upgrade; messages.yml is generated on first run

New

Per-gun knockback - guns can push the victim away (knockback) and shove the shooter back (selfKnockback). Both default to 0, so existing guns are unchanged.
Tunable throwables - explosion damage/knockback, effect duration/amplifier, and fire duration are now per-item config (explosionDamage, explosionKnockback, effectDuration, effectAmplifier, fireTicks). Omit them and throwables behave exactly as before.
Customizable messages - all player-facing text moved to messages.yml (MiniMessage), with built-in fallbacks for missing keys.
WorldGuard support (optional) -registers a pewpew-guns region flag (default allow); deny it to block guns and throwables in a region. Enforced per shot, so full-auto stops on entering a protected area. No effect if WorldGuard isn't installed.
CombatTagPlus support (optional) - combat-tags shooter and victim on a gun hit. No effect if CombatTagPlus isn't installed.
Notes

Both integrations are optional soft-depends, toggleable in config.yml (integrations.worldguard.enabled, integrations.combattagplus.enabled). config.yml gains the integrations block automatically on upgrade; messages.yml is generated on first run

New

• Update checker — plugin now checks GitHub for newer releases on startup and notifies players with pewpew.update.notify on join.
• Locked attachments — attachments can be locked, preventing removal/swapping.
• Dummy shield blocking — dummies now support shield blocking.

Improved

• Recoil — reworked recoil behaviour for better feel.

Fixed

• Module loading reflection that prevented modules from loading correctly.