Global Config and Runtime

Duck Shot has two layers of configuration:

• global plugin behavior in config.yml
• per-item and per-weapon behavior in weapons/*.yml

If every single weapon on the server feels a little wrong in the same way, the problem is usually global config, not the weapon file.

What belongs in config.yml

Use config.yml for decisions that should feel consistent across the whole server:

• how Duck Shot listens for player input
• which key reloads
• how strict item identification is
• how aiming behaves globally
• global recoil smoothing
• action bar defaults
• debug and startup behavior

Use weapon files for the actual content:

• damage
• ammo
• recoil amounts
• projectiles
• particles
• sounds
• throwables, grapples, explosives, and special modules

Safe baseline for live servers

The starter defaults already show the direction Duck Shot expects:

reload_trigger: DROP_KEY
strict_item_identification: true
 
input:
  use_protocollib: true
  cancel_vanilla_right_click: true
  semi_policy: THROTTLED
  hold_group_millis: 250
  aim_toggle_debounce_millis: 140
  aim_toggle_delay_ticks: 2

That baseline matters because it keeps Duck Shot from acting like older plugins where any matching vanilla item can accidentally become a weapon.

strict_item_identification

This is one of the most important global safety knobs.

strict_item_identification: true

When this is true, Duck Shot only treats properly tagged Duck Shot items as weapons. That prevents server-wide confusion like:

• ordinary shears behaving like guns
• vanilla crafting outputs turning into combat items
• copied materials firing because they share the same base item

For public servers, keep this on.

Reload input and alternate methods

Duck Shot supports multiple input lanes:

reload_trigger: DROP_KEY
 
input:
  extra_methods:
    swap_hands:
      enabled: true
    drop:
      enabled: false

DROP_KEY

This is the common "press Q to reload" behavior. Duck Shot cancels the item drop and reloads instead.

SWAP_HAND

Useful if you want F to reload instead. This can feel better on servers where drop is already tied to other item workflows.

What to pick

• use DROP_KEY if you want traditional shooter muscle memory
• use SWAP_HAND if your server uses Q for other systems
• leave only one clearly advertised reload path enabled

Interactable guard

This system is easy to miss, but it solves a lot of user frustration:

input:
  interactable_guard:
    enabled: true
    mode: WHITELIST
    apply_to_firearms: true
    apply_to_throwables: true

This tells Duck Shot to let players open real containers and interactables instead of firing into them.

That means a player holding a rifle can still open:

• chests
• barrels
• furnaces
• dispensers
• anvils

without accidental shots or priming behavior.

For public servers, this should usually stay enabled.

Semi-auto feel and trigger timing

These knobs affect how semi-auto and burst content feels across the entire plugin:

input:
  trigger_release_timeout_millis: 200
  semi_policy: THROTTLED
  hold_group_millis: 250

trigger_release_timeout_millis

If full-auto weapons keep firing too long after release, lower this.

If they stop too early because the client only sends one use packet, raise this.

semi_policy

THROTTLED is the current safe default. It avoids a lot of missed-shot frustration on semi-auto weapons.

hold_group_millis

This is especially important for burst weapons. It groups repeated right-click packets into one hold so bursts do not instantly retrigger while the player keeps holding the mouse.

Aiming and ADS globals

Duck Shot also exposes ADS feel globally:

input:
  aim_toggle_debounce_millis: 140
  aim_walk_speed_multiplier: 0.85
  aim_toggle_delay_ticks: 2
  suppress_aim_after_drop_millis: 400

aim_toggle_debounce_millis

Prevents double-toggles from bursty click packets.

aim_walk_speed_multiplier

Sets the default movement slowdown while aiming. Per-weapon values can still override it, but this helps keep your whole weapon library feeling consistent.

aim_toggle_delay_ticks

Useful when Paper or client packet timing causes aim toggles to collide with reload or drop behavior.

suppress_aim_after_drop_millis

Prevents the classic "I pressed reload and the weapon aimed instead" issue.

Global recoil smoothing and turn suppression

Global recoil does not define each weapon's recoil amounts. It defines how recoil is applied:

recoil:
  smoothing_ticks: 1
  suppress_when_turning: false
  turning_yaw_threshold_degrees: 1.50
  turning_pitch_threshold_degrees: 1.50
  discard_pitch_when_turning: false

smoothing_ticks

• 1 feels immediate and sharp
• higher values feel softer and more eased

If your recoil looks too snappy on the whole server, raise this a little before rewriting every weapon.

suppress_when_turning

This is a comfort knob. When enabled, Duck Shot can skip camera recoil ticks while the player is actively moving the mouse.

Use it if players complain about:

• vibration
• snapback
• recoil fighting their tracking

Global action bar defaults

The global action bar template is the starting point for every weapon:

action_bar:
  enabled: true
  template: '{gun_display} <dark_gray>|</dark_gray> {ammo_display} {state} {status}'
  ammo_display_mode: BOTH

This is where you define your house style for:

• ammo bars
• numeric ammo formatting
• reloading colors
• empty-click flashes
• status tokens

Per-weapon overrides should only be used when an item needs to break away from the normal firearm HUD, like:

• grapples
• med kits
• flashbangs
• C4

Startup, logging, and debug

Duck Shot also gives you a cleaner startup and debugging surface:

startup:
  logging:
    verbosity: NORMAL
 
debug:
  enabled: false

Recommended live-server approach:

• keep startup verbosity on NORMAL
• leave debug off until you are actively troubleshooting
• only use more verbose modes when diagnosing install or content problems

What to change globally first

If your whole server feels off, check these in this order:

1. strict_item_identification
2. reload and input settings
3. ADS timing and debounce
4. recoil smoothing / turn suppression
5. action bar global template
6. debug or startup verbosity

What should stay per-weapon

Do not move these into global logic unless you are intentionally normalizing your whole library:

• damage values
• fire rate
• projectile speed
• recoil amounts
• ammo size
• explosion power
• particles
• sound identity

Recommended next pages

• install and First Boot
• first Weapon Walkthrough
• fire, Recoil, and Aim
• action Bar, Sounds, and Feedback