Projectiles and Impacts

Once a Duck Shot weapon fires, the projectile block decides how the shot behaves in flight and on collision.

Core projectile example

projectile:
  type: ARROW
  speed: 9.11
  gravity: false
  max_range_blocks: 240
  physics:
    enabled: true
    gravity_per_tick: 0.03
    drag_per_tick: 0.01

Projectile types

Duck Shot supports multiple projectile modes, including:

• ARROW
• SNOWBALL
• THROWN_ITEM
• THROWN_DISPLAY
• ARROW_STAY
• display-driven or projectile-profile-driven specialty types from projectiles.yml

Choose the type based on the gameplay and visual language you want:

• firearms usually use ARROW
• thrown utilities often use THROWN_DISPLAY
• highly visual or custom payloads often use display-driven projectile styles

Flight behavior

speed

How quickly the projectile travels.

gravity

Whether the projectile drops naturally.

max_range_blocks or lifetime controls

Use these to stop long-running projectiles from living forever.

custom physics

If you need more control, enable the physics block and tune gravity plus drag directly.

Projectile profiles from projectiles.yml

Duck Shot supports reusable projectile presets so you do not have to redefine every advanced behavior in every weapon:

projectile:
  profile: homing_rocket_demo
  speed: 1.65
  max_ticks: 100

This pattern is important:

• the profile gives you the advanced baseline
• the weapon file only overrides what should be different for this item

That is a much cleaner workflow than pasting giant projectile branches into every file.

The big Projectile v2 behavior knobs

The example projectiles.yml shows the real advanced behavior surface.

Homing

Example knobs:

behavior:
  homing:
    enabled: true
    range: 26.0
    turn_rate_degrees: 11.0
    start_ticks: 3
    retarget_interval_ticks: 2
    require_line_of_sight: true

Interpretation:

• range is how far the projectile can acquire a target
• turn_rate_degrees is how sharply it can correct course
• start_ticks delays the first correction so launch still feels readable
• retarget_interval_ticks controls how aggressively it keeps updating
• require_line_of_sight decides whether it should feel fair and readable or more magical

Lock-on

Lock-on is a different system from homing. It governs target acquisition before launch:

behavior:
  lock_on:
    enabled: true
    ticks: 28
    range: 80.0
    cone_degrees: 12.0
    require_ads: true

Interpretation:

• ticks is how long the player must hold the target
• range is acquisition distance
• cone_degrees is how tight the aim cone must be
• require_ads makes the system feel more intentional and less spammy

Pierce

Example knobs:

behavior:
  block_pierce_count: 2
  entity_pierce_count: 2
  block_pierce_speed_multiplier: 0.82
  block_pierce_damage_multiplier: 0.80

Interpretation:

• higher counts allow the round to keep traveling through more surfaces or entities
• lower speed and damage multipliers keep the round from staying too perfect after piercing

Ricochet / bounce

Example knobs:

bounce:
  enabled: true
  chance: 1.0
  max_bounces: 4
  speed_multiplier: 0.74
  damage_multiplier: 0.78
  accuracy_penalty_degrees: 2.4

Interpretation:

• more bounces create trick-shot potential
• lower speed and damage keep ricochet from outclassing direct hits
• accuracy penalty keeps later bounces messy and believable

Speed curves

Example knobs:

behavior:
  speed_curve:
    multiplier_per_tick: 1.012
    add_per_tick: 0.0
    ramp_ticks: 30

Use this when the projectile should:

• accelerate
• decelerate
• ramp into a more dramatic travel feel

This is especially useful for rockets, special arrows, and thrown utilities.

Homing and ricochet

Duck Shot can also change projectile behavior through ammo variants or weapon overrides.

Examples from example content include:

• homing rounds
• ricochet rounds
• explosive impact rounds
• tracer variants

That means a weapon can stay structurally the same while different ammo families rewrite how each shot behaves in the air.

Impact layers

A projectile is not finished at collision. Duck Shot also lets you tune:

• impact sounds
• impact particles
• impact decals
• underwater impact sounds
• entity and block impact FX

Impact decal interpretation

The decal system is deeper than just "leave a bullet mark":

impact_decal:
  enabled: true
  scale: 0.66
  scale_range:
    min: 0.72
    max: 1.32
  lifetime_ticks: 200
  shrink_start_ticks: 180

What these knobs change

• scale sets the baseline mark size
• scale_range adds variety so every hit does not look cloned
• lifetime_ticks controls how long the mark stays visible
• shrink_start_ticks controls when the cleanup begins

If you want subtle realism, keep these restrained.

If you want louder arcade feedback, allow larger size and longer life.

Impact decal example

impact_decal:
  enabled: true
  material: GOLD_NUGGET
  custom_model_data: 98001
  lifetime_ticks: 200

This is how you add bullet marks or surface-hit visuals without rewriting the whole projectile system.

Sticky and display projectiles

Duck Shot also supports projectile types that are useful outside standard firearms:

ARROW_STAY

Good for:

• bolts that stick into surfaces
• creative arrows
• projectiles that should remain visible for a short time

THROWN_DISPLAY

Good for:

• flashbangs
• grenades
• magic or utility items
• display-driven cinematic payloads

Example: why one projectile setup feels different from another

Compare these two ideas:

Fast rifle shot

type: ARROW
speed: 12.5
gravity: false

Feels:

• immediate
• direct
• better for rifles and marksman weapons

Slow arcing grenade

type: THROWN_DISPLAY
speed: 1.1
gravity: true

Feels:

• readable in the air
• utility-focused
• better for explosives and tools

That is why projectile type and speed should match the weapon fantasy before you even start tuning damage.

Explosive projectiles

Projectile explosions sit under projectile.explosion.

That same tree can branch into:

• blast damage
• plantable explosives
• cluster payloads
• airstrike behavior
• custom block carving and rebuild logic

If you are building utility explosives or launchers, start on throwables, Explosives, and Flashbangs.

Good projectile design habits

Separate feel from flight

Use fire: for trigger feel and projectile: for motion. Do not try to solve both in the same block.

Keep impact readable

Players should understand whether they hit:

• a block
• an entity
• water
• armor or hard cover

Use sound and particles to reinforce that.

Tune with real engagement distance

A CQB weapon and a sniper should not share the same projectile lifetime or sound reach.

Use profiles for advanced systems

Once a projectile starts using:

• homing
• lock-on
• ricochet
• speed curves
• advanced bounce

move the baseline into projectiles.yml unless the item is intentionally one-off.

Related pages

• fire, Recoil, and Aim
• throwables, Explosives, and Flashbangs
• particles v2 and FX
• block Breaking, Restoration, and Craters
• sky Select, Airstrikes, and Support Callers