Melee Weapons, Breach Tools, and Hybrid Actions

Duck Shot melee is not a throwaway backup swing. It is a real configurable action system.

That matters because the example content already proves Duck Shot can support:

• fast knives
• heavier breach tools
• hybrid melee-plus-magic artifacts
• projectile-free close-range utility items

What the melee module actually does

melee.actions lets a weapon react to contact and swing events without pretending to be a normal firearm shot.

At the public-content level, that means you can build:

• a quick stab weapon
• a slam weapon
• a breaching hammer
• a melee item that also has alternate right-click powers

The basic melee.actions shape

melee:
  actions:
    enabled: true
    triggers:
      SWING:
        cooldown_ticks: 6
        actions:
          - type: SOUNDS
            target: SELF
            stages:
              - time: 0
                key: minecraft:entity.player.attack.sweep
                volume: 0.8
                pitch: 1.0
      HIT_ENTITY:
        cooldown_ticks: 8
        actions:
          - type: DAMAGE
            amount: 7.0
            target: TARGET
      HIT_BLOCK:
        cooldown_ticks: 10
        actions:
          - type: PARTICLES_V2
            profile: melee.impact.heavy
            target: LOOK_BLOCK
            range_blocks: 6

What the example triggers are teaching you

The current examples use three public trigger families:

SWING

Use this for:

• wind-up feedback
• whoosh sounds
• very light pre-hit particles

This is the best place for "I started the attack" feedback.

HIT_ENTITY

Use this for:

• direct damage
• knockback or impulse
• potion effects
• impact particles

This is the core contact event for melee combat against living targets.

HIT_BLOCK

Use this for:

• slam waves
• breaching effects
• ground-ripple visuals
• point-of-impact spectacle on terrain

This is how the heavier melee tools feel physical instead of decorative.

The action types that matter most

The example melee-heavy files rely on a small set of action types very effectively:

• DAMAGE
• IMPULSE
• POTION
• PARTICLES_V2
• SOUNDS
• GROUND_RIPPLE_WAVE

Those six action types already cover most of the public melee fantasies people actually want to build.

Copyable knife pattern

Use this when you want a fast, readable melee weapon.

melee:
  actions:
    enabled: true
    triggers:
      SWING:
        cooldown_ticks: 5
        actions:
          - type: SOUNDS
            target: SELF
            stages:
              - time: 0
                key: minecraft:entity.player.attack.sweep
                volume: 0.65
                pitch: 1.18
      HIT_ENTITY:
        cooldown_ticks: 7
        actions:
          - type: DAMAGE
            target: TARGET
            amount: 6.8
          - type: IMPULSE
            target: TARGET
            vector:
              x: 0.0
              y: 0.16
              z: 0.78
              relative_to_look: true
              strength: 1.0
          - type: PARTICLES_V2
            profile: melee.knife.hit
            target: TARGET

Why this works:

• the swing feedback is fast
• the hit gives enough push to feel sharp
• the config stays small and readable

Copyable breach-hammer pattern

Use this when the tool should feel heavy and physical.

melee:
  actions:
    enabled: true
    triggers:
      HIT_ENTITY:
        cooldown_ticks: 11
        actions:
          - type: DAMAGE
            target: TARGET
            amount: 11.6
          - type: IMPULSE
            target: TARGET
            vector:
              x: 0.0
              y: 0.32
              z: 1.10
              relative_to_look: true
              strength: 1.0
          - type: POTION
            target: TARGET
            effect: SLOWNESS
            duration_ticks: 80
            amplifier: 1
      HIT_BLOCK:
        cooldown_ticks: 16
        actions:
          - type: GROUND_RIPPLE_WAVE
            target: SELF
            damage: 8.2
            require_on_ground: true
            pattern_mode: FORWARD
            steps: 9
            step_interval_ticks: 1
            step_distance_blocks: 1.05

Why this works:

• entity hits feel heavy
• block hits become shockwave events
• the tool has a clear "breach" identity instead of feeling like a slow knife

Hybrid melee items are already a real Duck Shot pattern

The example BREACH_HAMMER.yml, ARCANE_RECALL_KNIFE.yml, and ARCANE_RECALL_TOMAHAWK.yml show something important:

an item can have a serious melee section and still keep a separate alternate-power lane.

That means you can build:

• a hammer with a leap on right click
• a recall knife
• a melee weapon with a spell pulse

without forcing all of that identity into one giant combat block.

When melee should stay melee

Use the melee section when:

• the core fantasy is close-range contact
• hit timing matters more than projectile travel
• the item should not need reload or ammo identity

Move to the magic or projectile side when:

• range is the real fantasy
• travel time matters
• the item is supposed to feel like a cast, bolt, or thrown artifact

Good public design patterns

Fast knife

Prioritize:

• low cooldown
• clean hit sound
• light impulse
• readable hit particles

Heavy hammer

Prioritize:

• stronger cooldown
• bigger impulse
• block-hit payoff
• slam-wave identity

Hybrid relic

Prioritize:

• simple left-click melee
• one strong right-click power
• clearly different sounds and particles for each lane

Common mistakes

Treating melee like a firearm with zero projectile speed

If the item is melee-first, author it through the melee actions cleanly instead of leaving it as a fake gun.

Making every block hit do everything

Start with one job:

• damage wave
• displacement
• breaching spectacle

Then add more only if the tool still reads clearly.

Forgetting hit readability

Melee needs fast feedback. Slow or muddy sound staging makes close-range tools feel unresponsive.

Related pages

• magic Casters, Wands, Staffs, and Spell Actions
• per-weapon Sounds, Events, and Breath Focus
• particles v2 and FX
• weapon Archetype Recipes