Ammo Families, Variants, and Custom Rounds

ammos.yml is one of the most important Duck Shot files because it lets you dramatically change a weapon without rewriting the weapon.

That is the real job of ammo in Duck Shot:

• keep the weapon identity
• change the round personality

If you use this file well, one rifle can support normal rounds, tracers, subsonics, homing rounds, ricochet rounds, and explosive rounds without becoming six separate weapon files.

The shape of the file

At a high level, ammos.yml is organized like this:

ammo_types:
  RIFLE:
    material: PURPLE_DYE
    display_name: <#8F9399>Rifle Magazine
    lore:
      - <#AEB3BA>Used by rifles.
    variants:
      TRACER:
        custom_model_data: 3
        display_name: <#FFAA4D>Rifle Mag (Tracer)
        loaded_label: <#FFAA4D>Tracer
        lore:
          - <gray>Bright trajectory for easier tracking.
        overrides:
          projectile_glow: true
          trail_profile: trail.tracer.flare.red.heavy
          trail_every_ticks: 1
          trail_skip_legacy: true

The two layers are:

• the ammo family
• the variant override

The family defines the physical ammo item. The variant defines what changes when that round is loaded.

What ammo variants can already change

Ammo variants can already reach into all of these systems:

• raw damage
• spread
• projectiles per shot
• projectile type
• projectile speed
• projectile gravity
• projectile max ticks
• projectile max range
• glow and trail behavior
• homing
• ricochet
• explosion behavior
• underwater explosion behavior
• shoot sound
• impact sound
• additional staged sounds
• muzzle_v2_profiles
• impact_v2_profiles
• impact_entity_v2_profiles
• impact_underwater_v2_profiles
• shot_events
• shot_ads_events
• shot_hip_events
• muzzle_events
• impact_events
• impact_entity_events
• impact_underwater_events

That is why ammo is not a tiny side-system in Duck Shot. It is one of the main behavior layers.

What "same gun, different round" really means

Duck Shot ammo is strong because it changes the shot personality without breaking the public identity of the weapon.

That distinction matters:

• the gun file still owns the base handling, reload flow, optic tree, and identity
• the ammo variant changes how the shot behaves once it leaves the weapon

That is why ammo is the right place for:

• tracer visibility
• homing or ricochet personality
• quieter subsonic sound design
• special impact sounds
• payload-style explosive conversion

It is not the best place for:

• a permanent optic branch
• a totally different animation tree
• a gun that should visually become a new item in inventory

Those are usually attachment or result-weapon problems.

What the example round types are really doing

Armor-piercing

Typical pattern:

overrides:
  damage_multiplier: 1.12
  spread_multiplier: 1.03
  impact_sound_volume_multiplier: 1.1
  impact_sound_pitch_multiplier: 0.94

Interpretation:

• slightly stronger hit
• a little less tidy
• harder impact personality

Tracer

Typical pattern:

overrides:
  projectile_glow: true
  trail_profile: trail.tracer.flare.red.heavy
  trail_every_ticks: 1
  trail_skip_legacy: true

Interpretation:

• easier to read in the air
• better for suppression and target correction
• also easier for enemies to read

Subsonic

Typical pattern:

overrides:
  damage_multiplier: 0.92
  projectile_speed_multiplier: 0.82
  shoot_sound:
    enabled: true
    replace_default: false
    use_weapon_volume: true
    use_weapon_pitch: true
    key: minecraft:silenced
    volume: 1.0
    pitch: 1.0

Interpretation:

• quieter report
• slower travel
• better for stealth flavor than raw pressure

Homing

Typical pattern:

overrides:
  projectile_speed_multiplier: 0.9
  spread_multiplier: 0.88
  homing_enabled: true
  homing_range_multiplier: 1.35
  homing_turn_rate_multiplier: 1.45
  homing_start_ticks: 2
  homing_retarget_interval_ticks: 2
  homing_require_line_of_sight: false

Interpretation:

• a little slower
• more forgiving
• useful for guided utility or fantasy ammo

Ricochet

Typical pattern:

overrides:
  ricochet_enabled: true
  ricochet_max_bounces: 2
  ricochet_chance_multiplier: 1.35
  ricochet_speed_multiplier: 0.85
  ricochet_damage_multiplier: 0.78

Interpretation:

• angle-dependent utility
• less consistent direct pressure
• strong for gimmick rounds, trick shots, or sci-fi behavior

Explosive

Typical pattern:

overrides:
  explosion_enabled: true
  explosion_power_override: 0.82
  explosion_set_fire: false
  explosion_break_blocks: false
  impact_v2_profiles:
    - explosion.duck.cinematic.v2.urban.debris

Interpretation:

• converts the shot into a payload
• trades pure projectile identity for area feedback
• opens ripple, water, and impact FX lanes that normal rounds do not need

How ammo sound and particle overrides actually stack

Ammo variants can already change much more than raw damage.

An ammo round can swap or add:

• shoot_sound
• shoot_additional_sounds
• impact_sound
• impact_additional_sounds
• trail_profile
• trail_every_ticks
• muzzle_v2_profiles
• impact_v2_profiles
• impact_entity_v2_profiles
• impact_underwater_v2_profiles
• shot_events
• impact_events

That means a custom round can sound different, look different in flight, and explode or splash differently on impact without replacing the whole weapon.

Minimal custom variant pattern

Use this pattern when you only want one behavior lane to change.

ammo_types:
  RIFLE:
    variants:
      HEAVY_AP:
        custom_model_data: 31
        display_name: <#E8DDAA>Rifle Mag (Heavy AP)
        loaded_label: <#E8DDAA>Heavy AP
        lore:
          - <gray>Hard-hitting anti-armor pressure round.
        overrides:
          damage_multiplier: 1.18
          spread_multiplier: 1.05
          impact_sound_volume_multiplier: 1.1
          impact_sound_pitch_multiplier: 0.92

This is the clean pattern when the gun should still sound and read like itself, but the round needs more stopping power.

Copyable custom ammo example

This is a good public template for building a custom ammo variant that changes sound, particles, and impact behavior without replacing the weapon.

ammo_types:
  RIFLE:
    material: PURPLE_DYE
    display_name: <#8F9399>Rifle Magazine
    lore:
      - <#AEB3BA>Used by rifles.
    variants:
      SHOCK:
        custom_model_data: 21
        display_name: <#7FDBFF>Rifle Mag (Shock)
        loaded_label: <#7FDBFF>Shock
        lore:
          - <gray>Precision energy round with bright impact feedback.
        overrides:
          damage_multiplier: 1.04
          projectile_speed_multiplier: 1.08
          spread_multiplier: 0.96
          shoot_sound:
            enabled: true
            replace_default: false
            use_weapon_volume: true
            use_weapon_pitch: true
            key: minecraft:block.beacon.power_select
            volume: 0.55
            pitch: 1.35
          shoot_additional_sounds:
            - key: minecraft:block.amethyst_cluster.hit
              volume: 0.20
              pitch: 1.75
              delay_ticks: 0
          impact_sound:
            enabled: true
            replace_default: false
            key: minecraft:entity.lightning_bolt.impact
            volume: 0.45
            pitch: 1.5
          trail_profile: trail.tracer.flare.red.heavy
          trail_every_ticks: 1
          trail_skip_legacy: true
          muzzle_v2_profiles:
            - smoke.duck.incendiary.puff
          impact_v2_profiles:
            - explosion.duck.incendiary.flare
          shot_events:
            - shock_shot
          impact_events:
            - shock_impact

Why this works:

• the rifle is still the rifle
• the round feels distinct immediately
• the new personality comes from ammo, not from a cloned weapon file

Copyable custom family with multiple round identities

When you want a clean content-pack family, author the family once and keep the variants disciplined.

ammo_types:
  DMR:
    material: BLUE_DYE
    display_name: <#8FA6C9>DMR Magazine
    lore:
      - <#AEB3BA>Used by designated marksman rifles.
    variants:
      MATCH:
        custom_model_data: 41
        display_name: <#BEE2FF>DMR Mag (Match)
        loaded_label: <#BEE2FF>Match
        lore:
          - <gray>Tighter spread and cleaner impact feedback.
        overrides:
          damage_multiplier: 1.02
          spread_multiplier: 0.84
          projectile_speed_multiplier: 1.05
      DISRUPTOR:
        custom_model_data: 42
        display_name: <#7FDBFF>DMR Mag (Disruptor)
        loaded_label: <#7FDBFF>Disruptor
        lore:
          - <gray>Energy-like report with brighter impact effects.
        overrides:
          shoot_sound:
            enabled: true
            replace_default: false
            use_weapon_volume: true
            use_weapon_pitch: true
            key: minecraft:block.beacon.power_select
            volume: 0.55
            pitch: 1.22
          impact_sound:
            enabled: true
            replace_default: false
            key: minecraft:entity.lightning_bolt.impact
            volume: 0.42
            pitch: 1.35
          trail_profile: trail.tracer.flare.red.heavy
          trail_every_ticks: 1
          muzzle_v2_profiles:
            - smoke.duck.incendiary.puff
          impact_v2_profiles:
            - explosion.duck.incendiary.flare

Why this structure is strong:

• the family is readable in inventory
• each variant has a clear role
• the weapon file stays focused on the weapon instead of carrying every round branch

Ammo authoring decisions that save time

Use ammo when the player should think "same weapon, different round"

Good examples:

• tracer vs subsonic
• armor-piercing vs hollow point
• standard vs homing
• standard vs explosive

Use an attachment when the player should think "same weapon, upgraded branch"

Good examples:

• night vision optic
• thermal optic
• flashlight module
• silencer module

Use a cloned weapon only when the whole identity truly changes

That is the expensive path. Do it when the weapon needs a new visual state stack, a new optic workflow, or a new handling identity that ammo alone should not carry.

Recommended debugging flow

1. confirm the variant loads and shows the right label
2. test sound changes first
3. test trail and impact FX second
4. only then add homing, ricochet, or explosion overrides
5. if the weapon now feels like a different item, move the idea into an attachment or result weapon instead

Custom ammo design tips

Change one category at a time first

When authoring a new ammo variant, start with one main goal:

• stealth
• armor pressure
• visible tracers
• area payload
• guided utility

If you change everything at once, it becomes harder to tell what actually made the round feel different.

Use sounds and particles as identity cues

Ammo should not only change numbers. It should tell the player what they loaded.

Good identity cues:

• a cleaner or dirtier report
• a brighter or heavier trail
• a distinct impact color family
• subtle extra sounds that signal what kind of round just fired

Use event bindings when the round needs reusable FX logic

If you already have a good particles_v2.events library, do not hardcode every effect directly into the ammo. Use:

• shot_events
• muzzle_events
• impact_events

That keeps the ammo readable and moves the effect choreography into the FX system where it belongs.

When to use ammo vs a new weapon file

Use ammo when the player should still think:

• "this is my same rifle"
• "I just loaded a different round"

Create a new weapon file instead when:

• the handling changes all the time
• the scope or form factor changes permanently
• the whole item fantasy changes

Good authoring workflow for custom rounds

1. tune the base weapon first
2. make one clean ammo family
3. add one variant
4. verify the behavior change in game
5. only then add more dramatic variants like homing, ricochet, or explosive payloads

Related pages

• ammo, Attachments, and Classifications
• attachment Recipes, Conversions, and Upgrade Paths
• projectiles and Impacts
• explosive Payloads, Clusters, and Strike Recipes
• particles v2 and FX
• per-weapon Sounds, Events, and Breath Focus