Fire, Recoil, and Aim

This page covers the three systems that decide how a Duck Shot weapon feels in the player's hands:

• fire mode behavior
• recoil behavior
• ADS and aim movement

Fire mode basics

Duck Shot treats right-click input as weapon intent, then resolves the actual firing logic from the weapon's fire: block.

Core fire block

fire:
  mode: AUTO
  shots_per_second: 10.9
  projectiles_per_shot: 1

Supported fire modes

AUTO

Use this for rifles, SMGs, and machine guns.

• holding right-click continues to fire
• shots_per_second controls the actual rate cap
• release stops the loop

SEMI

Use this for pistols, marksman rifles, shotguns, or any weapon where each click should be deliberate.

• each click is a shot attempt
• the client can still repeat while the button is held
• shots_per_second still caps the maximum rate

BURST

Use this for controlled burst rifles.

fire:
  mode: BURST
  shots_per_second: 20.0
  burst:
    shots_per_burst: 3
    interval_ticks: 3
    cooldown_ticks: 8

Once a burst starts, it completes unless another part of the weapon logic interrupts it.

multi_mode and player-controlled switching

Some example weapons support multiple fire modes inside one item:

fire:
  mode: AUTO
  multi_mode:
    enabled: true
    modes: [semi, BURST, AUTO]

Use this when the weapon should intentionally switch behavior in play, not when you are still deciding what the weapon is supposed to be.

Spread tuning

Spread lives inside the fire block:

spread:
  base_degrees: 1.13
  ads_multiplier: 0.45
  sneak_multiplier: 0.75
  moving_multiplier: 1.2
  sprinting_multiplier: 1.4
  air_multiplier: 1.6

This is where you make a weapon disciplined, wild, accurate, or punishing.

How each spread knob feels

base_degrees

This is the weapon's true baseline cone.

• lower values feel disciplined
• higher values feel loose or spammy

ads_multiplier

This decides how rewarding aiming is.

• 0.45 is a meaningful ADS reward
• 0.90 means ADS barely changes anything

moving_multiplier

How much the weapon punishes normal movement.

Raise this if you want the player to stop and commit.

sprinting_multiplier

This should usually punish harder than normal movement.

It is the difference between:

• tactical reposition then fire
• sprint-jump spraying

air_multiplier

This is one of the cleanest anti-cheese knobs in Duck Shot.

If jump shots are too reliable, raise this first.

Spread patterns from spread_patterns.yml

Duck Shot can also layer pattern-driven offsets on top of normal spread randomness:

fire:
  spread:
    base_degrees: 1.2
    pattern:
      enabled: true
      id: zigzag_demo
      mode: ORDERED
      loop: true
      yaw_scale: 1.0
      pitch_scale: 1.0

This is not the same thing as recoil:

• recoil moves the camera
• spread pattern offsets the projectile direction

Use spread patterns when you want a weapon to shoot in a readable sequence without forcing the player's camera through that same path.

Recoil basics

Duck Shot supports per-weapon recoil. The standard random pattern looks like this:

recoil:
  enabled: true
  mode: RANDOM
  ads_multiplier: 0.58
  reset_on_release: true
  vertical:
    min: 0.80
    max: 1.22
  horizontal:
    min: -0.30
    max: 0.30

Recoil tuning logic

Vertical range

Controls how much the muzzle climbs.

Horizontal range

Controls left-right unpredictability.

ADS multiplier

Tightens recoil while aiming.

reset_on_release

If true, recoil index resets when the player releases the trigger.

That is usually good for weapons that should reward controlled bursts.

Random recoil vs PNG recoil

Duck Shot supports two major recoil styles:

• RANDOM
• PNG

RANDOM

Best for:

• classic firearms
• less authored feel
• easier quick tuning

PNG

Best for:

• hand-authored spray patterns
• competitive or learned recoil paths
• weapons that should feel intentionally patterned

Example:

recoil:
  enabled: true
  mode: PNG
  png:
    file: recoil_patterns/example_scurve.png
    scale_x: 0.12
    scale_y: 0.12
    loop: true

Interpretation:

• scale_x controls yaw strength
• scale_y controls vertical climb strength
• loop decides whether the pattern repeats instead of ending

Turn suppression and judder control

Duck Shot also supports recoil suppression while the player is actively turning:

recoil:
  suppress_when_turning: true
  turning_yaw_threshold_degrees: 3.0

This is a comfort and polish feature.

If players say recoil feels like it is fighting their mouse, this is one of the first things to inspect.

Aim and ADS

Most firearms should declare an aim: block:

aim:
  enabled: true
  movement_speed_multiplier: 0.85
  zoom_levels: [item]

That lets you decide:

• whether the weapon supports ADS at all
• how much movement slows while aiming
• whether the weapon cycles zoom levels

zoom_levels

An empty array often means simple ADS without stepped zoom cycling.

A populated list is better for scopes or special optics.

movement_speed_multiplier

This is one of the cleanest feel knobs in the whole plugin:

• lower values make the weapon feel committed and heavy
• higher values feel lighter and more mobile

If a sniper feels too easy to strafe with, lower this before touching projectile logic.

Stepped optics, breath sway, and hold breath

Duck Shot's aim layer goes beyond simple ADS.

The example sniper examples use:

• zoom_levels for stepped optics
• breath_sway for sight drift
• hold_breath for temporary stabilization

Those systems are part of why scoped weapons can feel deliberate instead of just "the same rifle but zoomed in."

See scopes, Thermal, Flashlights, and Held Effects for the deeper optic-specific authoring pass.

Global input settings that affect feel

Some important global settings live in config.yml rather than the weapon file:

• input.semi_policy
• input.trigger_release_timeout_millis
• input.aim_toggle_debounce_millis
• input.aim_walk_speed_multiplier
• recoil.smoothing_ticks
• input.hold_group_millis
• input.aim_toggle_delay_ticks
• recoil.suppress_when_turning

If every weapon on the server feels slightly wrong, look there before rewriting every file.

Good tuning patterns

Assault rifle

• AUTO
• medium recoil
• medium spread
• clear ADS improvement

Pistol

• SEMI
• faster handling
• lower magazine size
• lighter recoil per shot but harsher cadence punishment

Burst rifle

• BURST
• tighter base spread
• stronger recoil inside the burst
• cooldown long enough to stop spam

Precision rifle

• low base_degrees
• strong ADS benefit
• lower movement speed while aiming
• more authored recoil or PNG recoil if you want a learned pattern

Common mistakes

Fire rate too high for the weapon role

If a weapon feels wrong, check shots_per_second before you touch anything else.

Recoil too random

Wild horizontal recoil can make a weapon feel broken instead of skill-based.

ADS with no reward

If aiming slows movement but barely improves spread or recoil, the weapon often feels bad.

Mixing spread and recoil blindly

If both systems are pushed too hard at the same time, the weapon feels random rather than skill-based.

Usually:

• spread controls certainty
• recoil controls control difficulty

Treat them as different jobs.

Next pages

• projectiles and Impacts
• global Config and Runtime
• action Bar, Sounds, and Feedback
• visual States and Animated Models
• scopes, Thermal, Flashlights, and Held Effects