Classifications, Groups, Lore, and Held Hooks

classifications.yml is one of the most important shared files in Duck Shot because it does not only label items. It decides how items are described, grouped, limited, and optionally enhanced while held.

That makes it the bridge between:

• item identity
• loadout rules
• menu routing
• lore placeholders
• held-effect behavior

If ammo changes the round personality and attachments change the weapon branch, classifications change how the whole item family is understood by the server and the player.

The file shape

The default classifications file is organized into three main layers:

lore:
  placeholders:
    classified_label: "<color:#66624e>Classified as:</color>"
 
groups:
  weapon_type:
    display_name: "<gray>Weapon Type"
    tags: [weapon_type]
    members: [pistol, smg, rifle, shotgun, sniper, heavy_rifle]
 
classifications:
  primary:
    display_name: '<#47D764>Primary'
    hotbar:
      max: 2
    groups: [weapon_role]
    tags: [primary, combat]

Read that structure like this:

• lore.placeholders gives you reusable text fragments
• groups define shared families
• classifications define the actual tags you put on weapons

What groups are really doing

Groups are not cosmetic folders. They are the reusable middle layer that keeps the rest of the ecosystem sane.

The default classifications file already uses them for:

• weapon_role
• weapon_type
• support_item
• tools_item
• attachment_item
• heavy_slot

That means one classification can belong to multiple larger ideas at once. For example, heavy_rifle belongs to both a weapon-type family and a heavy-slot family.

This is why groups are the right place for rules that should apply to many items at once.

What classifications are really doing

Classifications are the player-side identity markers that weapons actually carry.

Examples from the default classifications file:

• primary
• secondary
• pistol
• rifle
• sniper
• explosive
• consumable
• tool
• grapple
• attachment
• plantable
• mountable

Each one can define:

• display name
• tags
• group membership
• hotbar limits
• lore placeholder overrides
• held effect hooks

That is why classifications are much more than "category labels."

Hotbar and loadout control

The most immediately useful gameplay hook is the inventory control lane.

For example:

classifications:
  primary:
    display_name: '<#47D764>Primary'
    hotbar:
      max: 2
    groups: [weapon_role]
    tags: [primary, combat]

Interpretation:

• the item is labeled as a primary
• it joins the weapon_role family
• it carries searchable tags
• the hotbar can enforce a max count for this class

This is one of the cleanest ways to keep a server readable when you have firearms, support items, attachments, grapples, tools, and magical devices all sharing inventory space.

Lore placeholders are a major quality-of-life system

The default classifications file already exposes shared placeholder text:

lore:
  placeholders:
    classified_label: "<color:#66624e>Classified as:</color>"
    requires_label: "<color:#66624e>Requires:</color>"
    attachment_label: "<color:#66624e>Attachment:</color>"
    ammo_label: "<color:#66624e>Ammo:</color>"

Those placeholders matter because they keep your public item language consistent. Instead of hard-writing the same fragments into every weapon, you define the vocabulary once and reuse it everywhere.

That becomes even more important when you combine this file with:

• the create wizard
• GUI categories
• attachment lore lines
• classification-aware display text

Group-level held hooks

The file also shows a real scaffold for group-based held effects:

groups:
  heavy_slot:
    display_name: "<gray>Heavy Slot"
    tags: [heavy]
    members: [heavy_rifle]
    effect_hooks:
      held:
        enabled: false
        tick_interval: 4
        potion_effects:
          - type: SLOWNESS
            amplifier: 0
            duration_ticks: 8
            particles: false
            icon: true

Interpretation:

• every item in that family can share one held-effect rule
• the hook is disabled by default
• the scaffold is already there for heavier mobility penalties or role flavor

This is the right level for shared family behavior. If every heavy weapon should slow the player a little, put that on the heavy family instead of copying it across every weapon.

Copyable custom classification example

This is a good public example for adding a new lightweight scout classification that has its own lore language and a held mobility effect.

groups:
  weapon_type:
    display_name: "<gray>Weapon Type"
    tags: [weapon_type]
    members: [pistol, smg, rifle, shotgun, sniper, heavy_rifle, scout]
 
classifications:
  scout:
    display_name: '<#8ED8FF>Scout'
    groups: [weapon_type]
    tags: [scout, lightweight]
    lore:
      placeholders:
        class_role_text: '<#8ED8FF>Scout Role'
    effect_hooks:
      held:
        enabled: true
        tick_interval: 4
        potion_effects:
          - type: SPEED
            amplifier: 0
            duration_ticks: 8
            particles: false
            icon: true
        action_bar: '<gray>Scout mobility active'
        action_bar_interval_ticks: 20

Why this works:

• the new role is readable in lore
• it joins an existing group structure cleanly
• the held effect belongs to the classification instead of being hacked into every weapon file

When to change groups vs classifications

Use a new group when:

• many classifications should share one larger identity
• you want reusable tags or shared held behavior
• you need one place for family-wide lore or editor browsing

Use a new classification when:

• a weapon needs a player-visible role or inventory rule
• one item family needs its own tags
• one item family needs its own lore placeholder or held behavior

How this file cooperates with the rest of Duck Shot

classifications.yml is upstream of a lot of the rest of the ecosystem:

• gui.yml can route by tags and categories that originated here
• the create wizard can seed default classifications
• lore placeholders can pull display data from these entries
• support items and tools can use the same identity framework as firearms

That is why this file is worth keeping clean even on smaller servers.

Suggested order

1. define the families you want players to recognize
2. create or update the reusable groups first
3. add classifications with clear tags and display names
4. add hotbar limits only where they solve a real loadout problem
5. add held hooks only when the family should share that behavior

Related pages

• ammo, Attachments, and Classifications
• loadouts, Support Items, and Classification Design
• gui Browser, Live Tuning, and Categories
• create Wizard, Templates, and Knobs