Throwables, Explosives, and Flashbangs

Duck Shot is not limited to guns. It also supports thrown utilities, planted charges, flashbangs, and explosive projectile chains.

Thrown utility baseline

A typical throwable uses a display-style projectile with bounce or plant logic:

projectile:
  type: THROWN_DISPLAY
  speed: 1.25
  gravity: true

That base is common for flashbangs, grenades, and utility payloads.

Fuse style and plant style are different choices

A throwable explosive can behave in very different ways depending on how you wire the explosion branch.

Timed throwable

Use a normal fuse when you want:

• grenade behavior
• bounce, roll, then detonate
• readable timing pressure

Planted charge

Use projectile.explosion.plant when you want:

• stick or plant behavior
• remote detonation
• model swaps for armed state
• optional pickup or pack-up behavior

Flashbang setup

The example flashbang is a good example of a non-lethal utility item:

flashbang:
  enabled: true
  radius_blocks: 10.0
  blind_ticks: 100
  darkness_ticks: 110

It also supports a screen overlay:

overlay:
  enabled: true
  mode: BLOCK_DISPLAY
  material: WHITE_CONCRETE
  duration_ticks: 100

Flashbang design notes

Use flashbangs when you want:

• disorientation instead of raw damage
• bounce before detonation
• readable fuse behavior
• strong visual feedback without terrain damage

What the flashbang knobs mean

Using the example file:

flashbang:
  radius_blocks: 8.0
  blind_ticks: 50
  darkness_ticks: 65

Interpretation:

• radius_blocks is the effective crowd-control area
• blind_ticks is the fast whiteout or immediate disorientation
• darkness_ticks extends the recovery window afterward

If you want a breaching tool:

• keep the radius controlled
• keep the effect sharp

If you want a bigger support item:

• raise the radius
• use longer post-flash darkness

Overlay tuning

overlay:
  enabled: true
  mode: BLOCK_DISPLAY
  material: WHITE_CONCRETE
  duration_ticks: 45

This is what creates the real screen flash effect. Shorter durations feel tactical. Longer durations feel more punishing.

Plantable explosives

Duck Shot also supports sticky or planted explosives under:

projectile:
  explosion:
    plant:
      enabled: true

This is how items like C4 can:

• plant onto surfaces
• stay armed
• be remotely detonated
• swap held-item visuals between idle and armed states

Remote-charge interpretation

One of the most important Duck Shot explosive ideas is this:

• thrown explosive pressure is about timing
• planted explosive pressure is about setup and control

That means C4-style items should usually communicate:

• where they are planted
• whether they are armed
• how to detonate or retrieve them

Explosive block and water behavior

Duck Shot can also split explosive behavior by environment:

• standard blast
• water plume and water shrapnel
• crater carving and rebuild
• custom shrapnel display fragments

Blocks, craters, and rebuild

Duck Shot's explosion system is not just vanilla TNT damage.

The modern branch can:

• carve temporary craters
• rebuild them later
• spawn visual shrapnel
• treat water separately

Example:

blocks:
  enabled: true
  shape: CRATER
  wall_shape: HEMISPHERE
  radius_x: 4.5
  radius_y: 3.0
  radius_z: 4.5
  max_depth: 6
  rebuild_duration_ticks: 240

What these knobs mean

• shape: CRATER is the normal ground-impact bowl
• wall_shape: HEMISPHERE gives cleaner side-surface blasts
• radius_* sets the blast footprint
• max_depth controls how aggressively the crater cuts down
• rebuild_duration_ticks controls how fast the map heals back in

Shrapnel render modes

Duck Shot's shrapnel system supports several render styles:

• ITEM_DISPLAY
• BLOCK_DISPLAY
• FALLING_BLOCK

ITEM_DISPLAY

Best for:

• smooth debris
• better interpolation
• modern premium look

BLOCK_DISPLAY

Best for:

• stylized water plumes
• heavier chunk-like visuals
• very readable debris sheets

FALLING_BLOCK

Legacy look. Useful when you intentionally want Minecraft physics flavor, but usually less polished than display entities.

Water behavior

Duck Shot can split explosions when the origin is inside liquid:

water:
  enabled: true
  power_multiplier: 0.40
  no_block_damage: true

That gives you a different feel from dry-land explosions:

• less raw destructive force
• more splash or plume styling
• no ugly underwater terrain carving if you do not want it

Cluster and airstrike branches

The explosive branch can also keep going into more complex payloads:

• cluster explosions
• airstrike payloads
• fire fields
• mortar or sky-select systems

These are not beginner systems, but they are part of the real Duck Shot config surface and belong in the public docs because they are real supported behavior, not private notes.

Cluster payloads

Good for:

• fragmentation grenades
• multi-burst launchers
• cinematic impact chains

Airstrike / sky-select

Good for:

• support designators
• call-in weapons
• event-style utility

These should usually be authored after the basic projectile or throwable already works.

Cluster grenade example

The example CLUSTER_GRENADE.yml is a very good public example of when one grenade should become many problems.

Its cluster branch uses:

• count
• waves
• wave_delay_ticks
• spread_radius
• spread_height
• per-fragment speed, upward force, gravity, and power

That means the grenade does not just explode. It:

• lands
• arms
• breaks into submunitions
• spreads secondary blast pressure across space and time

Use this pattern when the delayed fragmentation is the real fantasy, not just a stronger single blast.

Explosive ammo branches belong here too

Duck Shot's explosive ecosystem also includes explosive ammo variants in ammos.yml.

That is an important public design lesson:

• if the base weapon should stay the same, explosive ammo is often the better route
• if the item itself should become a grenade, charge, or payload tool, use the projectile or explosive branch directly

C4 example branch

projectile:
  explosion:
    power: 4.0
    set_fire: false
    break_blocks: false
    blocks:
      enabled: true
      shape: SPHERE
      rebuild_delay_ticks: 160
      rebuild_duration_ticks: 120

When to use each pattern

Flashbang

Use when the point is crowd control, disorientation, or breach support.

Grenade

Use when the item should throw, bounce, then detonate with short-fuse pressure.

C4 or charge

Use when the item should be planted, armed, and triggered later.

Launcher payload

Use when the explosive belongs to a fired projectile, rocket, shell, or airburst.

Best practices

Make the action bar explain the item

Thrown tools should tell the player what right-click and left-click do.

Keep fuse feedback readable

Fuse sounds, action bar text, and FX should all work together.

Separate damage from spectacle

Do not make every explosive more useful just to make it more cinematic. Duck Shot already gives you sound, particles, shrapnel, and rebuild options for that.

Start with the smallest working payload

If you are building an advanced explosive:

1. get the projectile traveling correctly
2. get the detonation timing right
3. add flashbang or explosion behavior
4. add shrapnel
5. add crater or rebuild logic
6. add water handling or clusters last

That order will save you a lot of debugging time.

Related pages

• projectiles and Impacts
• particles v2 and FX
• block Breaking, Restoration, and Craters
• planted Charges, Mines, and Proximity Devices
• sky Select, Airstrikes, and Support Callers
• explosive Payloads, Clusters, and Strike Recipes