Support YML Files and Global Editors

Duck Shot is not only a weapons/ folder. A lot of the plugin's real power lives in the support YAML files that sit beside the weapons and feed reusable behavior into many different items at once.

This page is the practical map for that layer so you can decide which file to open before you start changing knobs at random.

The support-file layer at a glance

These files matter the most once you move beyond one-off weapon edits:

• ammos.yml
• attachments.yml
• classifications.yml
• gui.yml
• block_breaking.yml
• integrations.yml
• visual_states.yml
• editor/create_wizard_schema.yml
• editor/global_editor_schema.yml
• editor/knobs.yml

The simple rule is:

• weapon files define one item
• support files define reusable systems that many items can share

What each file is for

ammos.yml

Use this when the same gun should support multiple round personalities without becoming multiple weapon files.

That file is where you author:

• ammo families
• ammo variants
• sound swaps
• trail and particle swaps
• homing, ricochet, and explosive behavior overrides

Go deeper here:

• ammo Families, Variants, and Custom Rounds

attachments.yml

Use this when one item should convert into another item through a clean upgrade recipe.

That file is where you author:

• attachment recipes
• item-to-item conversions
• lore continuity
• ammo transfer on upgrade
• player-side install feedback

Go deeper here:

• attachment Recipes, Conversions, and Upgrade Paths

classifications.yml

Use this when the server needs better identity, loadout, lore, or family behavior.

That file is where you author:

• role labels
• shared groups
• hotbar limits
• lore placeholders
• held effect hooks

Go deeper here:

• classifications, Groups, Lore, and Held Hooks
• loadouts, Support Items, and Classification Design

gui.yml

Use this when the in-game browser feels wrong or the category layout is leaking the wrong items into the wrong places.

That file handles:

• menu sizing
• category routing
• give amounts
• editor live tuning
• category include and exclude logic

Go deeper here:

• gui Browser, Live Tuning, and Categories

block_breaking.yml

Use this when the world reaction is wrong rather than the weapon itself.

That file handles:

• breakable materials
• damage thresholds
• chain breaking
• restoration timing
• crater-style spectacle without permanent grief

Go deeper here:

• block Breaking, Restoration, and Craters

integrations.yml

Use this when the problem only exists at the boundary between Duck Shot and another system.

That file currently matters most for:

• Airdrops
• WorldGuard
• shared ecosystem safety

Go deeper here:

• integration bridges, Airdrops, WorldGuard, and Vehicle MC
• integrations and Troubleshooting

visual_states.yml

Use this when the weapon behaves correctly but looks wrong.

That file handles:

• base, ADS, reload, sprint, and shot CMDs
• ammo-tier visual mapping
• visual priority ordering
• per-weapon state mapping

Go deeper here:

• visual States and Animated Models

editor/create_wizard_schema.yml

Use this when the create-weapon wizard needs a better creation flow.

That file decides:

• groups
• tracks
• category filtering
• template routing
• post-create actions
• recommended follow-up sections

Go deeper here:

• create Wizard, Templates, and Knobs

editor/global_editor_schema.yml

Use this when the in-game admin editor needs a better layout for shared files.

The default editor setup already exposes selected editors for:

• classifications.yml
• visual_states.yml
• safe portions of config.yml

editor/knobs.yml

Use this when you want to change the addable admin tools itself.

That file is where you define:

• sections
• knob ids
• path targets
• data types
• defaults
• activation rules
• parent/child relationships

If you are changing how the in-game editor thinks, not only what one weapon does, this file matters.

The best way to think about the system

Use this decision guide:

• change the weapon file when one item should behave differently
• change a support file when many items should share the same system
• change an editor schema when the admin or creator workflow itself needs to be cleaner

Recommended next pages

• classifications, Groups, Lore, and Held Hooks
• ammo Families, Variants, and Custom Rounds
• attachment Recipes, Conversions, and Upgrade Paths
• starter Templates for Guns, Throwables, Consumables, Grapples, and Devices
• stage Templates for Sounds, Particles, and Conditions
• planted Charges, Mines, and Proximity Devices
• mounted Guns and Deployable Emplacements
• melee Weapons, Breach Tools, and Hybrid Actions
• magic Casters, Wands, Staffs, and Spell Actions
• gui Browser, Live Tuning, and Categories