Visual States and Animated Models

Duck Shot has more than one way to make a weapon look alive. That is why this part of the plugin can feel confusing at first.

The short version:

• display controls how the item looks in inventory
• visual_states.yml swaps model ids based on weapon state
• animated_state adds first-person or offhand animation behavior on a specific weapon
• interceptor adds cosmetic reactions like shell eject, muzzle light, or mag eject

If you keep those jobs separate, the whole system gets much easier to reason about.

When to use each system

Use visual_states.yml when the model itself should change

This is the right tool when a weapon needs different custom model data for:

• base idle
• ADS
• reload
• sprint
• shot flash
• empty or low-ammo states

Real examples in the example config include rifles like M4A1, sidearms, LMGs, and even attachment items.

Use animated_state when the weapon should feel more alive in-hand

This is the right tool when the model is mostly the same but you want:

• reload swing timing
• staged animation behavior
• offhand-specific rules
• pose timing that reacts to shots or reloads

The example M4A1.yml uses this to make reload and pose behavior feel much more premium than a plain static item.

Use interceptor for extra cosmetics

This is where you wire in effects like:

• shell eject
• muzzle light
• mag eject

These do not replace the visual-state system. They sit on top of it as polish.

The one weapon-side hook you must understand

In the weapon file, the key field is:

visual_key: M4A1

That tells Duck Shot which entry inside visual_states.yml belongs to this weapon.

If visual_key is wrong, the weapon can still function, but the state-based model system will not line up with it.

Minimal visual-state setup

This is the kind of entry Duck Shot expects in visual_states.yml:

weapons:
  M4A1:
    base: 38
    ads: 39
    reload: 37
    sprint: 815
    shot_hip: 816
    shot_ads: 817
    magazine_size: 30
    shot_use_damage: true
    ammo_tier_cmd:
      empty: 818
    ads_empty: 819

This is enough to cover the main loop:

• idle model
• aiming model
• reload model
• sprint model
• firing flash model
• empty model

That is already a huge jump in readability compared to one static model.

The real priority stack

Duck Shot does not pick these states at random. It applies a priority order.

From the current visual-state manager, the effective stack is:

1. shot flash
2. reload
3. empty state
4. sprint
5. ammo tiers
6. ADS
7. base

That matters because a weapon can be:

• aimed
• low on ammo
• sprinting
• and firing

all inside a short span of time. The priority stack decides what the player actually sees.

The most important visual-state keys

base

The idle model. If nothing else is happening, this is what players see.

ads

The aiming model. Use this when the weapon should visibly shift while aiming.

reload

The reload model. This makes reload timing readable even before you add deeper animation.

sprint

The sprint model. Use this when the item should lower or rotate while the player is moving hard.

shot_hip and shot_ads

These are the shot-flash models. They give the weapon a visible firing reaction instead of snapping instantly back to the idle pose.

ads_empty

Use this when the weapon should show a different empty state while aiming than it does while held at the hip.

That is a good place to show open bolts, locked slides, or a dead sight picture.

Shot flash timing and why it matters

Global shot-flash timing lives near the top of visual_states.yml:

shot_flash:
  ticks: 2
  auto_ticks: 4
  use_damage:
    enabled: true
    hip_damage: 0.98
    ads_damage: 0.99

ticks

How long the shot pose lasts for a normal shot.

auto_ticks

Extra hold time for automatic weapons so they do not flicker back to base too quickly between rounds.

use_damage

This is a clever trick. Instead of only swapping to a second model id, Duck Shot can also apply tiny durability-style damage changes to help the resource-pack side represent a short shot sequence.

That is useful when you want:

• slightly different hip and ADS shot timing
• more stable auto-fire visuals
• a stronger illusion of movement without inventing a full custom animation system

Ammo tiers and ammo detail

These are related, but they are not the same thing.

Ammo tiers

Ammo tiers are broad state changes like:

• full enough
• low
• empty

Global tier rules look like this:

ammo_tiers:
  enabled: true
  only_when_not_ads: true
  tiers:
    - id: empty
      max_percent: 0.0
    - id: lt20
      max_percent: 0.2

Use this when you want a simple, readable low-ammo warning.

Ammo detail

Ammo detail is more granular. It is for weapons that should visibly count down or step through multiple model states as the magazine shrinks.

Included examples use weapons like M4A1, P90, and Hk21.

Two common modes show up:

• STEPS
• LAST_N

Interpretation:

• STEPS is good when you want multiple evenly spaced states through the whole magazine
• LAST_N is good when you only care about the final handful of rounds

That makes a big difference in feel:

• STEPS feels premium and detailed
• LAST_N feels practical and lower-maintenance

Ordered and random shot sequences

Duck Shot also supports shot sequences such as:

shot_hip_sequence:
  enabled: true
  mode: ORDERED
  use_damage: false
  damage_ratios: [0.98, 0.97, 0.96, 0.95]

This is useful for weapons that should cycle through multiple firing frames instead of always reusing one flash model.

Use ORDERED when:

• the weapon should look mechanical
• the sequence should progress predictably
• you are faking a multi-frame barrel or bolt cycle

Use RANDOM when:

• you want subtle variation
• the effect is more cosmetic than deterministic
• you are trying to avoid cloned-looking repeated shots

The example Minigun entry is a good example of why ordered sequences can help high-rate weapons feel less static.

visual_states vs animated_state vs interceptor

This is the decision most creators get stuck on.

If the custom model data itself changes, use visual_states

Examples:

• ADS swaps
• empty chamber swaps
• sprint pose swaps
• low-ammo model states

If the weapon needs a richer pose behavior, use animated_state

Examples:

• staged reload animation
• shot pose hold
• offhand override behavior
• reload timing that should feel more authored

If you just need cosmetic reactions, use interceptor

Examples:

• shell casing ejection
• muzzle lighting
• mag ejection

The M4A1.yml file is a good proof-of-concept for combining all three without turning the weapon into a mess.

Practical setup recipes

Clean rifle setup

Start with:

• visual_key
• base, ads, reload
• shot_hip, shot_ads
• one empty or low-ammo state

Only add animated_state after the weapon already feels readable.

LMG with visible final rounds

Use:

• standard base/ADS/reload states
• ammo_detail.mode: LAST_N

That keeps the file manageable while still making the last rounds feel tense.

Premium rifle with more visible magazine countdown

Use:

• ammo_detail.mode: STEPS
• enough model ids to cover a real stepped countdown

This is more work on the resource-pack side, but it looks much more impressive in-hand.

Attachment item or passive cosmetic item

Some example attachment entries in visual_states.yml intentionally point every state at the same model.

That is fine. It means the item participates in the system without needing a huge state tree.

Common mistakes

Wrong visual_key

The weapon works, but the state models never appear the way you expect.

magazine_size mismatch

If the visual entry does not match the weapon's real mag size, ammo tiers and detail states can look wrong.

Too many model states too early

Do not try to build a 15-step ammo-detail rifle before the base, ADS, reload, and shot flash states are already correct.

Forgetting ADS rules

ammo_tiers.only_when_not_ads: true is a good example of a rule that changes what players see. If you forget it, the system can feel inconsistent even when the config is technically correct.

Suggested order

1. Get the weapon fully functional with one model
2. Add visual_key
3. Add base, ADS, reload, and shot states
4. Add empty state
5. Add ammo tiers or ammo detail
6. Add animated_state
7. Add interceptor polish last

That order keeps your debugging clean.

Related pages

• weapon File Structure
• action Bar, Sounds, and Feedback
• fire, Recoil, and Aim
• weapon Archetype Recipes