Weapon File Structure

This page is the public reference for plugins/Duckshot/weapons/*.yml.

The goal here is not just to show one skeleton. The goal is to help you understand what kind of file you are actually building:

• a firearm
• a throwable or explosive
• a grapple or tool
• a special item that inherits behavior from support files

Recommended top-level order for a normal firearm

Duck Shot does not force a perfect visual ordering, but this structure keeps files readable:

1. id, enabled, category, tier, classifications, visual_key
2. display
3. ammo
4. reload
5. fire
6. projectile
7. damage
8. aim
9. recoil
10. sounds
11. particles or particles_v2
12. optional special systems like grapple, action_bar, impact_decal, animated_state, interceptor, melee

Reference skeleton

id: EXAMPLE_WEAPON
category: RIFLE
tier: COMMON
classifications:
  - primary
  - rifle
visual_key: EXAMPLE_WEAPON
 
display:
  name: '<green>Example Weapon'
  material: SHEARS
  custom_model_data: 1001
 
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
 
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]
 
recoil:
  enabled: true
  mode: RANDOM
 
sounds:
  shoot:
    audience: WORLD
    stages:
      - time: 0
        key: 'minecraft:entity.generic.explode'
        volume: 1.0
        pitch: 1.0
 
particles_v2:
  enabled: true
  replace_legacy: true

Three real file styles

The biggest source of confusion in Duck Shot is assuming every item should look like a gun. That is not true.

1. Standard firearm

A normal firearm usually needs:

• ammo
• reload
• fire
• projectile
• damage
• aim
• recoil
• sounds
• particles or particles_v2

2. Throwable or explosive

A throwable often drops or shrinks some of the firearm-only branches and grows the explosive branch instead:

projectile:
  type: THROWN_DISPLAY
  speed: 1.2
  gravity: true
  explosion:
    enabled: true
    plant:
      enabled: true

That item may not need:

• ammo
• ADS zoom
• rifle-style recoil

3. Grapple or utility tool

A traversal or tool item usually keeps the identity and feedback layers, then swaps in a special module:

projectile:
  type: THROWN_DISPLAY
  speed: 1.6
  gravity: true
 
grapple:
  enabled: true

This is why comparing every special item to M4A1.yml can be misleading.

Identity and organization

id

This is the weapon's unique internal id. Keep it stable once players start using the item.

category and tier

These are organizational labels. They help your content stay readable and can support menus or server logic around the weapon.

classifications

These are the public and system-facing tags that matter most for Duck Shot routing. They control things like slot rules, tool routing, and category behavior.

See ammo, Attachments, and Classifications for the full breakdown.

visual_key

Use this when the weapon should pull visual state behavior from visual_states.yml.

That is especially important for items with:

• base / ADS / reload model swaps
• ammo tier model states
• shot flash states
• sprint overlays

If a weapon should behave like the visual-state system instead of a one-model item, start by setting visual_key correctly.

Display block

The display block defines how the item looks in the inventory:

display:
  name: "<green>M4A1"
  material: SHEARS
  custom_model_data: 38
  lore:
    - "<gray>Example rifle"

Use this block to keep naming, pack ids, and public item copy consistent.

Lore placeholders

Duck Shot can pull classification placeholders directly into lore. That is why many included example files look like this:

lore:
  - '<color:#66624e>Classified as:</color> <#FF4D4D>Legend'
  - '<color:#66624e>Requires:</color> <#8F9399>Rifle Magazine'

Those lines become much easier to maintain once you start leaning on classifications.yml and shared placeholder tokens.

Ammo and reload

The basic ammo block looks like this:

ammo:
  type: RIFLE
  magazine_size: 30

If ammo.type is missing, the weapon behaves more like an infinite-ammo tool. That is useful for some utilities, but not for most firearms.

Reload interpretation

reload.duration_ticks is the full reload timing.

Shorter values make the weapon feel snappier.

Longer values increase punishment and downtime.

If the weapon is supposed to inherit the ammo behavior from the global or ammo config, you may also see:

reload:
  ammo_consumption_mode: INHERIT

Fire and spread

Fire behavior belongs under fire::

fire:
  mode: AUTO
  shots_per_second: 10.9
  projectiles_per_shot: 1
  spread:
    base_degrees: 1.13
    ads_multiplier: 0.45
    moving_multiplier: 1.2

That block controls how the weapon feels before projectile physics even begin.

Spread interpretation

• lower base_degrees means tighter base accuracy
• lower ads_multiplier rewards aiming more strongly
• higher moving_multiplier or sprinting_multiplier punishes movement
• higher air_multiplier makes jump shots less reliable

If you want a weapon to feel accurate but demanding, keep the base tight and punish movement.

If you want it to feel chaotic, raise the base and state penalties together.

Projectile and damage

Projectile behavior is separate from fire behavior:

projectile:
  type: ARROW
  speed: 9.11
  gravity: false
  max_range_blocks: 240
 
damage:
  base: 5

This separation is important:

• fire controls trigger feel
• projectile controls travel and collision
• damage controls impact output

Profile inheritance

Duck Shot also supports reusable projectile profiles:

projectile:
  profile: homing_rocket_demo
  speed: 1.65

That means you can pull a baseline from projectiles.yml, then override only the parts that make this specific item different.

Feedback layers

The finish layer of a weapon usually comes from:

• action_bar
• sounds
• flyby and spatial sound
• particles_v2
• impact_decal
• animated_state
• interceptor

You do not need every one of those on day one, but the best-feeling Duck Shot weapons usually use at least sounds plus particles.

impact_decal

Use this for bullet marks or hit marks on surfaces.

Knobs like:

• scale_range
• lifetime_ticks
• shrink_start_ticks
• max_per_block_surface

let you control whether decals feel subtle, persistent, crowded, or clean.

interceptor

Example weapons like M4A1.yml also show interception-driven cosmetic modules such as:

• shell eject
• mag eject
• muzzle light

Those are polish systems, not required baselines, but they are part of what makes a premium weapon pack feel finished.

Special modules

Duck Shot also supports specialized branches such as:

• grapple
• explosive payloads under projectile.explosion
• bounce and plant logic for thrown items
• flashbang behavior
• melee buttstroke handling
• sky select or airstrike call-ins
• animated_state offhand overlays and reload drivers

Keep those modules isolated and add them one at a time.

Best practice

Start from an included example

If you are building a rifle, compare against an existing rifle.

If you are building a thrown explosive, compare against FLASHBANG.yml or C4.yml.

If you are building a traversal tool, compare against the example grapple file.

If you are building a homing or advanced projectile item, compare against EXAMPLE_PROJECTILE_V2.yml and the reusable profiles in projectiles.yml.

Do not mix unrelated systems too early

A firearm with recoil, ADS, ammo, particles, ricochet, homing, and a custom explosive chain may be possible, but it is much harder to debug if everything is enabled in the first pass.

Keep files human-readable

If you cannot scan the YAML in seconds, the next person maintaining the server probably cannot either.

Best comparison workflow

When you want to understand what one knob changes, compare:

1. one minimal example file
2. one full example file
3. the support file that feeds it

Example:

• EXAMPLE_PROJECTILE_V2.yml
• M4A1.yml
• projectiles.yml

That is the fastest way to understand whether a knob belongs to:

• the weapon file
• the projectile profile
• global runtime config

Related pages

• first Weapon Walkthrough
• global Config and Runtime
• ammo, Attachments, and Classifications
• projectiles and Impacts
• visual States and Animated Models
• weapon Archetype Recipes