First Weapon Walkthrough

This page shows a clean Duck Shot weapon pipeline from top to bottom. The goal is not to expose every knob at once. The goal is to get one real weapon working, then expand from there.

What you are building

A typical Duck Shot weapon is one YAML file inside plugins/Duckshot/weapons/.

That file usually controls:

• the item display
• ammo type and magazine size
• fire mode and spread
• projectile behavior
• damage
• ADS and recoil
• sounds
• particles

Recommended first build

Start with a straightforward automatic rifle. Duck Shot's M4A1.yml example file is a good mental model because it includes the normal systems most creators actually need.

Minimal working example

Create a new file such as plugins/Duckshot/weapons/MY_FIRST_RIFLE.yml:

id: MY_FIRST_RIFLE
category: RIFLE
tier: COMMON
classifications:
  - primary
  - rifle
visual_key: MY_FIRST_RIFLE
 
display:
  name: '<green>My First Rifle'
  material: SHEARS
  custom_model_data: 9101
  lore:
    - '<gray>Simple Duck Shot example weapon'
    - '<gray>Uses the Rifle Magazine ammo family'
 
ammo:
  type: RIFLE
  magazine_size: 30
 
reload:
  ammo_consumption_mode: INHERIT
  duration_ticks: 40
 
fire:
  mode: AUTO
  shots_per_second: 10.0
  projectiles_per_shot: 1
  spread:
    base_degrees: 1.1
    ads_multiplier: 0.45
    moving_multiplier: 1.2
    sprinting_multiplier: 1.4
    air_multiplier: 1.6
 
projectile:
  type: ARROW
  speed: 9.0
  gravity: false
  max_ticks: 45
  max_range_blocks: 240
  physics:
    enabled: true
    gravity_per_tick: 0.03
    drag_per_tick: 0.01
 
damage:
  base: 5.0
 
aim:
  enabled: true
  zoom_levels: [item]
  movement_speed_multiplier: 0.85
 
recoil:
  enabled: true
  mode: RANDOM
  ads_multiplier: 0.6
  vertical:
    min: 0.8
    max: 1.2
  horizontal:
    min: -0.25
    max: 0.25
 
sounds:
  shoot:
    audience: WORLD
    stages:
      - time: 0
        key: 'minecraft:entity.generic.explode'
        volume: 1.0
        pitch: 1.0
  empty:
    audience: PLAYER
    stages:
      - time: 0
        key: 'minecraft:item.flintandsteel.use'
        volume: 1.0
        pitch: 1.8
 
particles_v2:
  enabled: true
  replace_legacy: true
  muzzle:
    hip_shot:
      profile: muzzle.flash.realism.556.hip.1
    ads_shot:
      profile: muzzle.flash.realism.556.ads.1

Why this works

Display

The display block turns the item into a real visible weapon with a model and name.

Ammo

The ammo block tells Duck Shot which ammo family the weapon consumes and how large the magazine is.

Fire

The fire block controls feel:

• mode
• shots_per_second
• projectiles_per_shot
• spread

Projectile

The projectile block decides how the shot actually travels.

Damage

The damage block is the simplest damage entry point and should always be present unless you are building a very custom system.

Aim and recoil

These turn a basic item into something that feels like a firearm instead of a generic click tool.

Sounds and particles

Those are what make the weapon feel finished.

Test steps

After saving the file:

1. Reload Duck Shot with your normal admin workflow
2. Give yourself the weapon
3. Confirm the item model appears
4. Test hip-fire and ADS
5. Confirm the action bar updates
6. Confirm reload and empty-click behavior work

First improvements after it works

Once the baseline rifle is live, move in this order:

1. add better sound stages in action Bar, Sounds, and Feedback
2. improve recoil and handling with fire, Recoil, and Aim
3. expand the FX with particles v2 and FX
4. start using ammo variants from ammo, Attachments, and Classifications

Good first mistakes to avoid

If the file is not loading, check the basics first

If Duck Shot is ignoring the file, start with the filename, indentation, reload logs, and whether the weapon id is unique.

Do not forget ammo.type

If you expect reload behavior but the weapon acts like it has infinite ammo, check the ammo block first.

Do not overload the first test weapon

Skip grenades, cluster payloads, grapple logic, or custom event spam until one basic firearm works end to end.

Where to go next

• weapon File Structure
• fire, Recoil, and Aim
• particles v2 and FX