Ammo, Attachments, and Classifications

Duck Shot's weapons are only part of the story. The public depth usually comes from three support files working together:

• ammos.yml
• attachments.yml
• classifications.yml

These files are what let one weapon become:

• several ammo personalities
• several upgrade paths
• one cleanly grouped item family

If your weapon file defines the base gun, these three files define the ecosystem around it.

What each file is really responsible for

ammos.yml

Use ammo when the weapon should still be the same weapon, but the round changes how it behaves.

Good examples:

• tracer rounds
• armor-piercing rounds
• subsonic stealth rounds
• homing rockets
• ricochet or explosive payload variants

attachments.yml

Use attachments when the weapon should convert into a new version of itself.

Good examples:

• adding an ACOG
• adding a flashlight
• converting a rifle into a silenced version
• swapping to a thermal or night-vision sight

classifications.yml

Use classifications when you need the item to be routed, grouped, limited, or labeled differently.

Good examples:

• primary vs secondary slot logic
• grouping pistols, SMGs, rifles, and heavy weapons
• support-item or tool routing
• heavy carry rules or held effects

The fast mental model

If the player should say:

• "same gun, different round" -> use ammo
• "same gun, upgraded version" -> use attachments
• "same item family, different slot or rules" -> use classifications

Why this matters

Most messy content packs happen because these three jobs get mixed together.

Common mistakes:

• cloning whole weapon files for simple ammo behavior
• using attachment items to fake what should really be an ammo variant
• hardcoding slot logic into lore instead of using classifications

Duck Shot reads much cleaner when you keep those jobs separate.

A practical authoring flow

1. Make the base weapon feel correct in weapons/*.yml
2. Add ammo families in ammos.yml
3. Add visible upgrade paths in attachments.yml
4. Tag the item cleanly in classifications.yml
5. Use the classification groups and hooks to keep menus, hotbars, and support-item logic readable

What the source already supports

This is the main reason these support files matter so much in Duck Shot.

Ammo can already change more than damage

Ammo overrides can already reach into:

• projectile speed, gravity, range, and lifetime
• projectiles per shot
• homing and retarget behavior
• ricochet bounce behavior
• explosions, ripple, and water behavior
• shoot and impact sounds
• staged additional sounds
• trails and glow
• muzzle_v2_profiles
• impact_v2_profiles
• impact_entity_v2_profiles
• impact_underwater_v2_profiles
• shot_events, muzzle_events, and impact event bindings

That means one ammo file can completely change the feel of the exact same weapon without forcing you to fork the weapon config.

Attachments are real conversion recipes

The current attachment recipes already support:

• matching by weapon_id
• matching by material
• matching by custom_model_data
• matching by name_contains
• carrying magazine ammo into the result
• preserving the original item name and lore
• appending an attachment-specific lore line
• custom feedback message and sound

So attachments are not just cosmetic. They are a structured conversion pipeline.

Classifications are more than labels

The classification framework in the example files already supports:

• groups and tags
• placeholder-driven lore
• hotbar limits
• held-effect hooks
• support/tool routing
• reusable item-family grouping

That is why a clean classification setup pays off across the whole plugin.

Go deeper from here

Use these next pages when you are ready to work at the source-file level:

• ammo Families, Variants, and Custom Rounds
• attachment Recipes, Conversions, and Upgrade Paths
• classifications, Groups, Lore, and Held Hooks
• loadouts, Support Items, and Classification Design
• per-weapon Sounds, Events, and Breath Focus

Quick recommendation

If you are building a premium-feeling gun pack, do not stop at the weapon file.

At minimum, give each flagship weapon:

• one default ammo family
• one or two meaningful ammo variants
• one visible upgrade path
• clean classifications

That is the point where Duck Shot starts feeling layered instead of flat.

Related pages

• weapon File Structure
• ammo Families, Variants, and Custom Rounds
• attachment Recipes, Conversions, and Upgrade Paths
• classifications, Groups, Lore, and Held Hooks
• loadouts, Support Items, and Classification Design
• per-weapon Sounds, Events, and Breath Focus
• projectiles and Impacts
• particles v2 and FX