Magic Casters, Wands, Staffs, and Spell Actions

Duck Shot's magic lane is a real public authoring surface, not a hidden test feature.

The example content already shows:

• wands
• staffs
• recall knives
• hybrid melee-plus-magic tools
• utility casts that behave more like spells than firearms

What the magic module actually is

Duck Shot magic lives under magic.cast.triggers.

That means a magic item is still authored as a Duck Shot weapon file, but the actual gameplay comes from triggered actions instead of ordinary bullets.

In practical terms, that lets you build:

• a right-click bolt
• a shift-right-click pull or blast
• a relic with multiple spell lanes
• a spell weapon that still keeps a light melee fallback

The basic magic.cast shape

magic:
  cast:
    enabled: true
    triggers:
      RIGHT_CLICK:
        cooldown_ticks: 8
        actions:
          - type: DAMAGE
            target: LOOK_ENTITY
            range_blocks: 26
            amount: 9.4
          - type: PARTICLES_V2
            profile: magic.arcane.bolt
            target: LOOK_ENTITY
            range_blocks: 26
      SHIFT_RIGHT_CLICK:
        cooldown_ticks: 16
        actions:
          - type: IMPULSE
            target: NEARBY_LOOK_ENTITY
            range_blocks: 7.2
            toward_caster: true
            strength: 1.95
            set_velocity: false

What the example files are teaching you

ARCANE_WAND.yml

This is the clean spell-weapon baseline.

It shows:

• a direct bolt on right click
• an area pull on shift-right click
• strong spell particles
• sound identity that reads as arcane instead of ballistic

AETHER_SCEPTER.yml

This is a staff-style crowd-control pattern.

It shows:

• a push or blast lane
• a cyclone-style pull lane
• a melee fallback for close range

BLOCK_LEVITATOR_WAND.yml

This is a utility-heavy magic example.

It shows that a spell item can do more than damage. It can lift, throw, and manipulate the feel of the fight in a more systemic way.

ARCANE_RECALL_KNIFE.yml

This is the hybrid pattern.

It proves a melee item can still carry a proper magic lane without becoming unreadable.

The action types that matter most for magic

The current magic examples lean heavily on:

• DAMAGE
• IMPULSE
• POTION
• PARTICLES_V2
• SOUNDS

That means a spell in Duck Shot is usually built from:

• hit logic
• movement logic
• status-effect logic
• visual identity
• audio identity

Copyable wand pattern

Use this when you want a clean two-button spell item.

magic:
  cast:
    enabled: true
    triggers:
      RIGHT_CLICK:
        cooldown_ticks: 8
        actions:
          - type: DAMAGE
            target: LOOK_ENTITY
            range_blocks: 24
            amount: 8.8
          - type: IMPULSE
            target: LOOK_ENTITY
            range_blocks: 24
            vector:
              x: 0.0
              y: 0.22
              z: 1.0
              relative_to_look: true
              strength: 1.0
          - type: PARTICLES_V2
            profile: magic.arcane.bolt
            target: LOOK_ENTITY
            range_blocks: 24
      SHIFT_RIGHT_CLICK:
        cooldown_ticks: 16
        actions:
          - type: IMPULSE
            target: NEARBY_LOOK_ENTITY
            range_blocks: 7.0
            toward_caster: true
            strength: 1.85
            set_velocity: false
          - type: POTION
            target: NEARBY_LOOK_ENTITY
            range_blocks: 7.0
            effect: LEVITATION
            duration_ticks: 40
            amplifier: 0
          - type: PARTICLES_V2
            profile: magic.arcane.singularity
            target: LOOK_ENTITY
            range_blocks: 24

Why this works:

• one trigger handles direct damage
• one trigger handles area control
• both triggers feel distinct immediately

Copyable staff-style crowd-control pattern

Use this when the item should feel heavier and more controlling than a quick wand.

magic:
  cast:
    enabled: true
    triggers:
      RIGHT_CLICK:
        cooldown_ticks: 10
        actions:
          - type: DAMAGE
            target: LOOK_ENTITY
            range_blocks: 24
            amount: 8.2
          - type: IMPULSE
            target: LOOK_ENTITY
            range_blocks: 24
            vector:
              x: 0.0
              y: 0.28
              z: 1.35
              relative_to_look: true
              strength: 1.0
      SHIFT_RIGHT_CLICK:
        cooldown_ticks: 17
        actions:
          - type: IMPULSE
            target: NEARBY_LOOK_ENTITY
            range_blocks: 6.6
            toward_caster: true
            strength: 1.85
            set_velocity: false
          - type: DAMAGE
            target: NEARBY_LOOK_ENTITY
            range_blocks: 6.6
            amount: 5.6
          - type: POTION
            target: NEARBY_LOOK_ENTITY
            range_blocks: 6.6
            effect: LEVITATION
            duration_ticks: 38
            amplifier: 0

Why this works:

• the right click is the directed blast
• the shift-right click is the crowd-control lane
• the item reads more like a staff than a gun

Spell identity comes from the action mix

If two spell items use the same actions, they will feel similar even if the model is different.

To make a magic item feel unique, change:

• the hit shape
• the pull or push behavior
• the potion effects
• the sound family
• the particle family

That is usually more important than changing the item material.

Hybrid items are a strength, not a problem

Duck Shot already supports items that mix:

• melee and magic
• utility and magic
• throwable feel and magic-style effects

Use that on purpose.

If the item is supposed to feel like a spellblade or relic, let it keep:

• a readable melee fallback
• one clear spell button
• one stronger alternate spell

That is usually easier to understand than six overloaded trigger paths.

Common mistakes

Treating magic like a gun with fantasy particles

If the item is spell-first, give it spell-first action logic and sound design.

Making every spell a damage spell

Duck Shot magic is much stronger when some items focus on control, pull, launch, recall, or utility.

Overloading every trigger

Start with one right-click lane and one shift-right-click lane. Add more only if the item still reads clearly.

Related pages

• melee Weapons, Breach Tools, and Hybrid Actions
• particles v2 and FX
• per-weapon Sounds, Events, and Breath Focus
• weapon Archetype Recipes