Conditional Rules and Context-Aware Weapons

Duck Shot has a real condition system for weapons. That means one item can react differently based on where the player is, what they are holding, what status effects they have, or what is happening around them.

This is one of the strongest authoring systems in the plugin because it lets you build smart weapons without cloning a dozen different YAML files.

What the condition system is for

Use conditions: when you want an item to:

• block ADS in certain environments
• block reload while airborne
• tighten or widen spread based on posture
• disable animated states for a special offhand setup
• play different sounds indoors vs outdoors
• change spread when sprinting or sneaking
• swap projectile behavior in special scenarios

If the weapon should stay the same item but react to context, conditions are usually the right tool.

The basic shape

Duck Shot condition rules live under conditions.rules.

Example structure:

conditions:
  rules:
    - id: block_ads_when_dark_night
      events: [ads]
      when:
        require_night: true
        max_sky_light: 4
      actions:
        block_event: true
        feedback:
          action_bar: '<gray>ADS blocked in low-sky-light night condition.</gray>'

That is the core pattern:

• choose which event the rule listens to
• describe the condition
• define what happens if it matches

Supported event lanes

The main event values are:

• ANY
• ADS
• SHOOT
• RELOAD
• PROJECTILE_END
• EXPLOSION
• ANIMATED_AIM
• ANIMATED_SHOT
• ANIMATED_RELOAD

Practical interpretation:

• use ADS, SHOOT, and RELOAD for gameplay gates
• use animated events when you only want to change the visual state layer
• use projectile or explosion hooks for advanced payload logic

Condition criteria you can actually use

Duck Shot's condition system is much deeper than just "if sneaking."

Duck Shot supports checks around:

• offhand materials
• inventory materials
• inventory custom model data
• armor materials
• potion effects
• attributes
• standing-on materials
• biome
• world
• y_min and y_max
• day and night checks
• sky-light range
• underwater and fully submerged checks
• indoors, outdoors, and enclosed spaces
• sneaking, sprinting, moving, walking, and airborne states
• nearby mobs by radius, count, and type

That means conditions are not just for blocking the player. They are for shaping the whole personality of the weapon in the world.

The important mental model

The condition engine is best at answering questions like:

• what am I standing on?
• am I sneaking, sprinting, airborne, or submerged?
• what world, biome, altitude, or skylight band am I in?
• what is in my offhand, armor, inventory, or status stack?

That is why this system is so strong for special-purpose weapons. The same item can feel disciplined, unstable, stealthy, heavy, or magical depending on context.

Blocking events cleanly

The simplest action is block_event: true.

Real patterns from the current conditional example include:

• block ADS on a specific surface
• block reload with a specific helmet
• block shooting while underwater
• block reload while airborne

Why this is useful:

• you can protect balance
• you can teach players about special restrictions
• you can build highly thematic items without changing the rest of the weapon

Feedback matters as much as the gate

If you block an action, always tell the player why.

Duck Shot supports feedback channels like:

• action bar
• chat
• title and subtitle
• sound
• particle

Good pattern:

actions:
  block_event: true
  feedback:
    action_bar: '<red>Reload blocked while airborne.</red>'

If you skip the feedback, the player experiences a bug.

If you include the feedback, the player experiences a rule.

Rule priority and fallthrough

Duck Shot also gives you ordering tools:

• priority
• fallthrough
• stop_on_match

Use higher priority when a rule should win early.

Use fallthrough: false or stop_on_match: true when that one rule should stop additional layering.

That is especially important for:

• hard gates
• mutually exclusive sound profiles
• special one-off projectile swaps

Conditions can change behavior, not just block it

This is the part many people miss.

The condition engine can also apply effects such as:

• additional sounds
• weapon event calls
• muting default sound or muzzle behavior
• spread multipliers
• spread add degrees
• projectile overrides
• projectile speed changes
• projectile gravity overrides
• max-range and max-tick overrides
• projectiles-per-shot overrides

That turns the system into a context-aware behavior layer.

The bridge to modern particles and FX

This is the part that matters if you are trying to build high-end content.

Condition feedback supports simple vanilla particle feedback directly, but the richer path is:

1. match the condition
2. trigger weapon_events
3. bind those event ids into particles_v2.events

That keeps the rule logic in the weapon file while the heavy cinematic FX library stays in your Particles v2 setup.

In practice, that is how you should think about it:

• simple "tell the player why it failed" -> use feedback
• reusable cinematic effect branch -> use effects.weapon_events

Copyable examples

Different sound and FX if the player is shifting on a specific surface

conditions:
  rules:
    - id: shoot_shifting_on_deepslate
      events: [shoot]
      when:
        standing_on_materials: [deepslate]
        sneaking: true
      actions:
        effects:
          weapon_events: [cond_secondary_fx]
          sounds:
            - time: 0
              key: minecraft:block.amethyst_cluster.hit
              volume: 0.35
              pitch: 1.55
              audience: PLAYER
          spread_multiplier: 0.75
          spread_add_degrees: -0.1

Interpretation:

• same weapon
• same ammo
• different shot flavor because the player's stance and footing changed

Different behavior if the player is only standing on the block

conditions:
  rules:
    - id: shoot_standing_on_sand
      events: [shoot]
      when:
        standing_on_materials: [sand, RED_SAND]
      actions:
        effects:
          override_projectile_type: SNOWBALL
          projectile_speed_multiplier: 0.95
          spread_multiplier: 1.35
          sounds:
            - time: 0
              key: minecraft:block.sand.place
              volume: 0.45
              pitch: 1.35
              audience: PLAYER

Interpretation:

• the surface alone changes the shot behavior
• the player does not need a separate "sand version" of the gun

Fully submerged gate

conditions:
  rules:
    - id: block_ads_fully_submerged
      priority: 110
      events: [ads]
      when:
        fully_submerged: true
      actions:
        block_event: true
        feedback:
          action_bar: '<aqua>ADS blocked while fully submerged.</aqua>'

Interpretation:

• this is different from just being near water
• it only fires when the player is truly submerged

In the air and shifting

conditions:
  rules:
    - id: airborne_shift_penalty
      events: [shoot]
      when:
        airborne: true
        sneaking: true
      actions:
        effects:
          spread_multiplier: 1.75
          spread_add_degrees: 0.45
          sounds:
            - time: 0
              key: minecraft:entity.player.attack.sweep
              volume: 0.22
              pitch: 1.4
              audience: PLAYER

Interpretation:

• the player can still fire
• but the weapon reads as unstable because of the exact movement state

Muting defaults and replacing them cleanly

The example test file already demonstrates a high-value pattern:

• mute the default shot sound
• mute the default muzzle
• mute the default shot events
• trigger your own event ids
• layer your own staged sounds on top

That is how you build truly context-aware alternate fire personalities without cloning the entire base weapon.

Example:

conditions:
  rules:
    - id: fx_swap_shot_profile_on_red_terracotta
      events: [shoot]
      when:
        standing_on_materials: [red_glazed_terracotta]
      actions:
        effects:
          mute_default_shoot_sound: true
          mute_default_muzzle: true
          mute_default_shot_events: true
          weapon_events: [cond_muzzle_swap, cond_trail_swap]
          sounds:
            - time: 0
              key: minecraft:entity.firework_rocket.launch
              volume: 0.9
              pitch: 1.35
              audience: PLAYER
            - time: 2
              key: minecraft:block.amethyst_block.hit
              volume: 0.7
              pitch: 1.6
              audience: WORLD

That pattern is one of the cleanest ways to make a weapon react to a mode, surface, or gimmick zone without secretly becoming a different item file.

Animated-state conditions

Conditions are not only for combat logic. They also affect the animated layer.

Real example pattern:

animated_state:
  conditions:
    rules:
      - id: disable_animated_while_offhand_string
        events: [animated_aim, ANIMATED_SHOT, ANIMATED_RELOAD]
        when:
          offhand_materials: [string]
        actions:
          disable_animated_state: true

That is a smart example because the weapon itself still works, but the pose system steps aside when a specific offhand setup is present.

Use this when:

• another tool or visual lane would conflict with the default arm animation
• you want compatibility without rewriting the whole weapon

When conditions are better than a new weapon file

Use conditions when:

• the item should stay the same identity
• the changes are contextual
• the player should be able to learn the rule

Create a new weapon file instead when:

• the item fantasy is actually different
• the handling is different most of the time, not only in context
• you are trying to express a real attachment or permanent upgrade

Good authoring patterns

Environmental realism

Use conditions to change sound or feedback:

• indoors
• enclosed spaces
• underwater
• altitude bands
• stance-specific handling

Readable balance rules

Use conditions to block:

• reload while airborne
• ADS in a specific server gimmick zone
• a special action while blinded

Context-driven combat flavor

Use conditions to alter:

• spread
• shot layering
• projectile behavior
• particle events
• sound staging
• muzzle and trail event routing

Common mistakes

Turning one weapon into twelve hidden weapons

If too many condition rules are stacked on top of each other, the item stops feeling readable.

Blocking actions without messaging

Players will assume the item is broken.

Using conditions for permanent identity

If the weapon always behaves like the "conditional" version, it should probably just be the base config.

Ignoring rule order

A strong condition system becomes confusing very quickly if priorities and fallthrough are left to accident.

Treating feedback particles and Particles v2 as the same system

They are related, but they are not the same path.

• feedback.particle is for simple direct feedback
• effects.weapon_events is the cleaner route into your larger particles_v2.events library

A simple public workflow

1. make the base weapon feel correct first
2. add one condition rule at a time
3. give every blocking rule readable feedback
4. when you need cinematic FX, trigger weapon_events instead of stuffing everything into feedback
5. use priorities only when you really need them
6. keep a mental line between "context flavor" and "different weapon entirely"

Related pages

• fire, Recoil, and Aim
• projectiles and Impacts
• per-weapon Sounds, Events, and Breath Focus
• particles v2 and FX
• visual States and Animated Models
• integrations and Troubleshooting