Particles v2 and FX

Particles v2 is Duck Shot's modern effect pipeline. It is profile-based, reusable, and much better suited for a real content library than hand-authoring every single weapon effect from scratch.

Core idea

Duck Shot separates the effect library from the weapon binding:

• particles_presets.yml is the large bundled library
• particles.yml is your local override and custom profile file
• each weapon binds hooks to profiles through particles_v2

Why that matters

This lets you:

• reuse the same effect language across many weapons
• randomize between profile variations
• keep your weapons cleaner
• build cinematic or lightweight versions of the same effect family

Basic weapon binding

particles_v2:
  enabled: true
  replace_legacy: true
 
  muzzle:
    hip_shot:
      profile: muzzle.my_rifle
    ads_shot:
      profile: muzzle.my_rifle

Hook coverage

Duck Shot can bind particles to:

• muzzle
• trail
• impact
• impact on entities
• impact underwater
• explosion

It also supports custom event hooks such as:

• equip
• unequip
• ads_enter
• ads_exit
• reload_start
• reload_finish
• reload_cancel
• empty_click
• projectile_end
• shot
• shot_hip
• shot_ads

That custom-event layer is important because it lets you treat Duck Shot effects as a reusable library instead of a one-file gimmick.

Selector modes

You do not have to bind one fixed profile every time.

Single profile

profile: muzzle.flash.realism.xs

Explicit list

profiles:
  - muzzle.flash.realism.556.hip.1
  - muzzle.flash.realism.556.hip.2
  - muzzle.flash.realism.556.hip.3

Random or sequence

mode: random

Pool selection

mode: random
pool_prefix: muzzle.
pool_limit: 200

This is a big part of why Duck Shot can support large FX libraries cleanly.

When to use each selector mode

single

Use when the weapon should always look consistent.

random

Use when you want slight variation between shots so the weapon feels less repeated.

sequence

Use when you want a predictable visual cycle.

all

Use when multiple profiles should fire together as one effect stack, such as:

• flash + smoke
• dust + shockwave
• plume + debris

Profile schema in plain English

A profile is a timeline.

• the profile is the whole effect
• each stage is a timing window
• each emitter is one particle source
• the shape decides where points exist
• animations modify those points over time

Building a custom profile

Add profiles to particles.yml when you want your own custom layer:

profiles:
  muzzle.my_rifle:
    description: My rifle muzzle
    stages:
      - at: 0
        emitters:
          - particle: FLASH
            count: 1
            shape: POINT
          - particle: SMOKE_NORMAL
            count: 1
            extra: 0.02
            shape:
              type: CONE
              length: 0.30
              radius: 0.10
              rings: 2
              points_per_ring: 6

Practical Duck Shot FX workflow

Start with existing library profiles

For most weapons, begin by binding existing muzzle, trail, impact, and explosion profiles.

Add custom profiles only when needed

If a weapon pack has a unique identity, then add a custom profile or a small custom family in particles.yml.

Use events for polish

Reload, ADS, and dry-fire events can make the plugin feel much more premium when used sparingly and intentionally.

The particle knobs that matter most

Stages

Key fields:

• at
• duration
• every

Interpretation:

• at is when the stage begins
• duration is how long it stays live
• every controls how often it re-emits during that stage

Emitters

Key fields:

• particle
• count
• offset
• extra
• shape
• animations
• audience
• max_points

Interpretation:

• count is particles per generated point
• offset adds randomized spread around each spawn
• extra is the Bukkit speed-style parameter
• max_points is a safety cap

Shapes

Duck Shot includes a much deeper shape language than most server plugins:

• point
• line
• ring
• disk
• cone
• sphere
• sphere filled
• cube hollow
• cylinder hollow
• helix
• double helix
• plus
• X

That is why it can build:

• simple muzzle flashes
• tracer streaks
• shockwaves
• rising smoke plumes
• stylized fantasy casts

Animations

Common animation types include:

• rotate
• scale
• pulse
• drift
• jitter
• wave

Use these to answer different visual questions:

• should this grow?
• should it drift upward?
• should it wobble?
• should it rotate around an axis?

Particle data types

Some particles need additional payload data:

• FLASH
• DUST
• DUST_COLOR_TRANSITION
• BLOCK_CRACK
• BLOCK_DUST
• ITEM

If one of those looks broken in-game, check the data: block first.

Cookbook-style comparisons

Simple muzzle flash

Good for:

• rifles
• SMGs
• basic pistols

Keep it short, fast, and low point count.

Tracer trail

Good for:

• tracer ammo
• special rounds
• projectile debugging

Use a short line behind the projectile and do not overbuild it.

Explosion stack

Good for:

• grenades
• airstrikes
• cinematic payloads

This is where mode: all becomes useful because you can combine dust, shockwave, plume, and debris profiles together.

Debug tools

Duck Shot includes particle-focused admin helpers. The most important public ones are:

• /duckshot particles list
• /duckshot particles test <profileIdOrPrefix> [emit|play]

Those are the fastest way to confirm whether a profile exists and how it behaves before you wire it into a live weapon.

Performance and safety

Duck Shot also exposes global limits:

effects:
  particles_v2:
    limits:
      max_points_per_emitter: 256
      max_spawn_calls_per_tick: 7500

If a server is struggling, tune those before gutting your entire effect library.

Good authoring order for effects

1. bind an existing preset profile
2. confirm the hook is firing
3. duplicate or override only if the stock profile is not enough
4. add randomization or stacking after the single profile works
5. keep a close eye on limits if you start authoring cinematic explosions

Common good uses

Muzzle flash families

Shared rifle, pistol, shotgun, and launcher flash groups.

Trail families

Tracer rounds, glowing projectiles, smoke strings, or specialty utility trails.

Impact families

Surface-specific hits, sparks, dust, block crack, and underwater splashes.

Explosion families

Charges, grenades, cinematic bursts, airbursts, and water plumes.

Related pages

• projectiles and Impacts
• throwables, Explosives, and Flashbangs
• action Bar, Sounds, and Feedback
• stage Templates for Sounds, Particles, and Conditions