Grapples and Tools

Duck Shot includes a full grapple module, so traversal and utility items can live inside the same content ecosystem as the weapons.

What the grapple module does

When grapple.enabled: true, Duck Shot treats the item as a grapple tool instead of a normal ballistic weapon.

It can:

• pull the player toward a block
• pull mobs or items toward the player
• optionally pull players
• auto-store grappled items when inventory space exists

Minimal grapple example

grapple:
  enabled: true
  range_blocks: 30.0
  cooldown_ticks: 10
  allow_blocks: true
  allow_items: true
  allow_mobs: true
  allow_players: false
  require_line_of_sight: true
  consume_item_when_depleted: true
  item_auto_store: true

Example grapple structure

The default Duck Shot grapple content also uses:

• tool and grapple classifications
• uses instead of a normal magazine readout
• custom action bar text
• event hooks for cast, fail, pull, and arrival

That keeps grapples readable in menus and readable in-hand.

Key grapple knobs

Range and cooldown

• range_blocks
• cooldown_ticks
• max_pull_ticks

Allowed target types

• allow_blocks
• allow_items
• allow_mobs
• allow_players

Pull feel

• pull_multiplier.self
• pull_multiplier.target
• pull_multiplier.target_player
• movement speed caps
• arrival distance thresholds

Utility behavior

• consume_item_when_depleted
• item_auto_store
• item_pickup_range_blocks

Why classifications matter for grapples

Duck Shot's classification system can route grapples into a Tools lane instead of the normal consumable or firearm categories.

That is why the example grapple setup uses tags like:

• tool
• grapple
• utility

See ammo, Attachments, and Classifications for the routing side.

Grapple effects and events

Duck Shot exposes event ids for the major grapple phases, including:

• cast
• fail
• block arm and arrive
• entity arm and arrive
• player arm and arrive
• item arm and arrive

That means you can give grapples custom sound and particle language without rewriting the core logic.

Good grapple design

For movement-focused servers

• allow blocks
• keep line of sight on
• tune arrival boost carefully
• keep the action bar simple

For loot-recovery tools

• allow items
• keep item_auto_store: true
• use limited uses

For combat utility

• consider allowing mobs
• be careful with player pulls
• keep cooldowns honest

Related pages

• action Bar, Sounds, and Feedback
• particles v2 and FX