Scopes, Thermal, Flashlights, and Held Effects

Some Duck Shot systems do not change the projectile at all. They change what it feels like to hold the item.

This page covers the four big ones:

• stepped zoom and scoped handling
• night vision and thermal optics
• flashlight modules
• held effects and carry penalties

These systems are what make one item feel like a normal rifle, another feel like a tactical platform, and another feel like a heavy piece of battlefield equipment.

Multi-stage scopes start with zoom_levels

Duck Shot supports simple ADS and stepped optics.

Example example:

aim:
  enabled: true
  zoom_levels: [3.0, 10.0]
  movement_speed_multiplier: 0.45
  breath_sway:
    enabled: true
    amplitude_degrees: 5.20
    frequency_hz: 0.12
    hold_breath:
      enabled: true
      focus_multiplier: 0.12

Interpretation:

• the first ADS level is a lighter scope stage
• the second ADS level is a more committed high zoom
• movement is heavily reduced while aiming
• breath sway makes the weapon feel alive instead of perfectly laser-stable
• hold breath temporarily tightens the reticle behavior

How zoom_levels actually changes the experience

One zoom stage

Use this when:

• the weapon is a basic optic platform
• the player should commit to aiming, but not enter a full sniper loop

Multiple zoom stages

Use this when:

• the optic should feel premium
• the player is expected to scan, then commit harder
• the weapon belongs in a marksman or sniper role

Multi-stage zoom works best when the rest of the weapon agrees with it:

• lower movement speed while aiming
• stronger payoff for accurate shots
• meaningful breath sway or recoil discipline

Breath sway and hold breath

The aim.breath_sway system is one of the most important realism knobs Duck Shot has.

The key controls are:

• amplitude_degrees
• frequency_hz
• ellipse_ratio
• hold_breath.enabled
• hold_breath.focus_multiplier
• stamina drain and recovery values

What those mean in practice:

• higher amplitude means a more noticeable sight wander
• lower frequency means slower, heavier motion
• hold breath reduces that motion temporarily
• stamina and lockout rules stop the feature from becoming permanent free accuracy

Good use case:

• sniper and anti-materiel rifles

Bad use case:

• normal carbines that should still feel responsive in regular movement

Night vision optics

Some example scoped weapons use an aim.effects.night_vision block.

Real example structure:

aim:
  effects:
    night_vision:
      enabled: true
      amplifier: 0
      refresh_interval_ticks: 20
      duration_ticks: 60

Interpretation:

• the weapon refreshes a mild night-vision effect while the scope is active
• the duration stays longer than the refresh window so the effect does not stutter
• the goal is visual readability, not permanent potion spam

Use this when:

• the optic is supposed to help in low light
• the weapon has a designated tactical or recon identity

Thermal optics

Thermal is a separate system, not just "night vision but greener."

Real example structure from SCAR_THERMAL.yml:

aim:
  zoom_levels: [5.0]
  effects:
    thermal:
      enabled: true
      overlay: 'scope.thermal_green'
      highlight:
        enabled: true
        max_range_blocks: 80
        fov_degrees: 55
        update_interval_ticks: 4
        max_targets: 20
        require_line_of_sight: true

overlay

This is the actual optic presentation. It gives the player the thermal look.

highlight

This is the detection logic that makes targets stand out.

The important feel knobs are:

• max_range_blocks
• fov_degrees
• update_interval_ticks
• max_targets
• require_line_of_sight

Interpretation:

• larger range makes the optic feel more useful
• wider FOV makes it easier to pick up targets but less focused
• faster updates make the scope feel more responsive
• line-of-sight keeps thermal from feeling like unfair wallhacks

Flashlights are a real module, not a fake particle trick

Duck Shot includes a real flashlight module with both input routing and light behavior.

Real example from G17_FLASHLIGHT.yml:

input:
  bindings:
    alt_action:
      bind: PICK_BLOCK_MMB
      action: TOGGLE_FLASHLIGHT
      cooldown_ticks: 4
 
modules:
  flashlight:
    enabled: true
    toggle:
      bind: PICK_BLOCK_MMB
      cooldown_ticks: 4
    beam:
      enabled: false
    light:
      enabled: true
      brightness: 14
      depth_blocks: 16
      sample_points: 3
      update_interval_ticks: 2
      only_when_ads: false
    visibility:
      mode: SELF_ONLY
      public_cull_radius_blocks: 24

How to read the flashlight module

Beam

This is the visible particle-style beam lane.

Use it when:

• you want the player to see the cone or trace
• the effect is more stylized

Light

This is the actual practical illumination lane.

The important knobs are:

• brightness
• depth_blocks
• sample_points
• update_interval_ticks
• only_when_ads

Interpretation:

• more brightness and depth makes the light feel stronger
• more sample points makes it feel fuller, but costs more
• faster updates feel smoother

Visibility mode

Duck Shot supports:

• SELF_ONLY
• PUBLIC

Use SELF_ONLY when the flashlight is mostly a personal utility feature.

Use PUBLIC when the tactical tradeoff matters and other players should read the beam or light presence too.

Held effects are how Duck Shot makes heavy gear feel heavy

Held effects are one of the most underrated systems in the whole plugin.

Real example file from M240.yml:

held_effects:
  enabled: true
  tick_interval: 4
  require_any_classifications: [heavy_rifle]
  min_hotbar_counts:
    heavy_rifle: 1
  potion_effects:
    - type: SLOWNESS
      amplifier: 0
      duration_ticks: 14
      ambient: true
      particles: false
      icon: false

Interpretation:

• the effect only matters while the player is actually carrying that heavy class of item
• the plugin reapplies the effect on a cadence instead of pretending it is a permanent potion
• the presentation stays clean because particles and icons are disabled

That is exactly how you make a heavy machine gun feel weighty without turning the screen into potion clutter.

What held effects can do

Held effects can drive:

• potion effects
• sounds
• action-bar messaging
• classification or inventory-count requirements

This makes them useful for more than just slowing players.

Good public uses:

• heavy rifles slow movement while held
• a special tool displays context guidance in the action bar
• a support pack gives a subtle buff while equipped

Why classifications matter here

Held effects become much more useful when they key off classifications instead of one hardcoded weapon id.

That way you can say:

• all heavy rifles should carry a penalty
• all utility scanners should display a helper message
• all special support tools should apply the same soft buff

without rewriting the logic for every single file.

A clean optic authoring recipe

Tactical assault rifle

Use:

• one zoom stage
• mild movement penalty
• no breath sway or only very light sway
• optional flashlight

Thermal rifle

Use:

• one committed zoom stage
• thermal overlay
• line-of-sight target highlighting
• handling slow enough to justify the optic power

Sniper

Use:

• multiple zoom stages
• meaningful movement penalty
• real breath sway
• hold breath

Heavy support weapon

Use:

• little or no scope complexity
• strong held-effect identity
• weight communicated through carry penalty instead of only recoil

Common mistakes

Giving thermal no meaningful drawback

If a thermal optic highlights too far, updates too fast, and barely slows the user, it stops feeling like a premium tradeoff and starts feeling like free wall-tracking.

Using held effects too noisily

If every held effect spams particles, chat, and icons, the player stops reading any of it.

Making flashlights unreadable

If the input is not obvious and the light is weak, players assume the module is broken.

Adding high zoom without handling costs

If a weapon gets major zoom but keeps normal movement and stability, the rest of the item balance usually collapses.

Related pages

• fire, Recoil, and Aim
• ammo, Attachments, and Classifications
• visual States and Animated Models
• input Binds, Consumables, and Alt Actions