Projectiles, Spread Patterns, Recoil, and Debugging

Duck Shot separates several systems that other plugins often blur together:

• projectiles.yml controls reusable projectile profiles
• spread_patterns.yml controls shot-to-shot projectile offset patterns
• recoil_patterns/*.png controls camera recoil curves
• particles.yml and particles_presets.yml control FX libraries

If you keep those layers separate, tuning gets much faster.

The runtime map

Use this mental model:

• projectile profile = how the shot travels
• spread pattern = where repeated shots drift
• recoil pattern PNG = how the player's camera is kicked
• particle profile = what the shot looks and sounds like

Those are related, but they are not the same job.

projectiles.yml

projectiles.yml is the reusable movement library for Projectile v2.

The included examples already cover:

• tracers
• sticky arrows
• item-display bolts
• homing rockets
• piercing rounds
• ricochets
• slow arcing grenades

Example:

projectiles:
  homing_rocket_demo:
    type: FIREBALL
    speed: 1.55
    gravity: false
    max_ticks: 90
    behavior:
      enabled: true
      homing:
        enabled: true
        range: 26.0
        turn_rate_degrees: 11.0

This is the right file when the question is "what does the projectile do after it leaves the weapon?"

spread_patterns.yml

This file controls projectile offset, not camera recoil.

The example header says it clearly:

# Recoil PNG files in `recoil_patterns/` control CAMERA recoil.
# This file controls PROJECTILE spread offsets (yaw/pitch) per shot.

Example:

patterns:
  zigzag_demo:
    mode: ORDERED
    loop: true
    steps:
      - { yaw: -0.35, pitch: 0.00 }
      - { yaw:  0.30, pitch: -0.05 }

Use spread patterns when you want the actual bullet path to follow a recognizable pattern over repeated shots.

Recoil PNG files

Duck Shot includes recoil images such as:

• example_vertical.png
• example_scurve.png

These belong to camera recoil, not projectile simulation.

Think of them this way:

• spread_patterns.yml decides where the bullets drift
• recoil_patterns/*.png decides how the player's view is kicked around

particles.yml vs particles_presets.yml

These files are also easy to mix up.

particles_presets.yml is the large preset library. It is where the build stores big reusable preset families such as cinematic explosions, shockwaves, smoke columns, and trail stacks.

particles.yml is the user override file. It is where your server should add:

• custom shapes
• local overrides
• pack-specific effect profiles

The example header explains the merge flow:

# The bundled library lives in: particles_presets.yml
# On reload, Duckshot merges presets first, then applies overrides from this file.

How to debug projectile problems

The projectile motion feels wrong

Check projectiles.yml first:

• type
• speed
• gravity
• max life
• homing or bounce behavior

The bullet path is wrong on sustained fire

Check spread_patterns.yml and the weapon's fire.spread.pattern binding.

The camera feels wrong but bullet travel is fine

Check the recoil image choice, recoil settings, and any weapon-side recoil path before touching projectile profiles.

The shot looks wrong but hits correctly

Check particle bindings and visual-state hooks before touching projectile math.

Recommended next pages

• projectiles and Impacts
• fire, Recoil, and Aim
• particles v2 and FX