GUI Browser, Live Tuning, and Categories

gui.yml is the file that turns Duck Shot from a pile of weapon files into a browsable in-game arsenal. It decides how the menu is laid out, how categories are resolved, and which small tuning controls are safe to expose to admins in the live editor.

If a server owner says "the in-game browser feels wrong," this file is usually where the fix belongs.

What gui.yml is responsible for

Duck Shot uses gui.yml for four jobs:

• top-level menu sizing and paging
• category routing and filtering
• give behavior in the browser
• the lightweight live-tuning controls inside the editor

At the top of the file, you can see that split clearly:

menu:
  rows: 6
  page_size: 45
  first_match_wins: true
 
  give:
    default_amount: 1
    shift_click_amount: 8
 
  editor_live_tuning:
    enabled: true
    damage_step: 0.5
    shots_per_second_step: 0.25
    spread_step: 0.05
    projectile_speed_step: 0.10

Menu size and paging

These are the safest knobs to change if the menu feels crowded or too sparse.

• rows sets the inventory height.
• page_size decides how many entries are shown per page.
• first_match_wins decides whether a weapon stops at the first matching category or can continue down the file until a later category also matches.

For public packs, first_match_wins: true is usually the cleanest choice. It keeps attachments, throwables, and special tools from showing up in multiple unrelated places.

Arsenal icon and titles

The main and titles blocks define the branding layer of the in-game browser.

main:
  arsenal_icon:
    use_weapon_icon: true
    weapon_id: M16A2
 
titles:
  root: "<#7CE3A1>Duckshot Menu <gray>(%page%/%pages%) <dark_gray>[%mode%]"
  category: "<#7CE3A1>%category% <gray>(%page%/%pages%) <dark_gray>[%mode%]"

That means you can change the menu's visual tone without touching the actual content pipeline.

Category routing is data-driven

The category section is one of the most important quality-of-life systems in the whole plugin. Categories are not hardcoded by the Java side. They are driven by include and exclude rules in gui.yml.

The default gui.yml already shows the intended pattern:

COMBAT_FIREARMS:
  parent_key: WEAPONS_ROOT
  label: "<#7CE3A1>Combat Firearms"
  include:
    match_mode: ANY
    weapon_categories: [pistol, SMG, RIFLE, SNIPER, SHOTGUN, HEAVY, MISC]
  exclude:
    match_mode: ANY
    weapon_ids: [m136, M32, THUMPER, MORTAR_STATION, MOUNTED_MG]
    tags_contains: [attachment, melee, magic, wand, staff]

That design keeps the public menu readable:

• core firearms stay together
• attachments do not bleed into the gun list
• plantables and mounted systems get their own lane
• tools and consumables can stay readable for non-shooter items

How category matching actually feels in practice

The example menu is not only sorting by one field. It uses a mixture of:

• weapon_categories
• explicit weapon_ids
• id_contains
• tags_contains
• optional parent categories such as WEAPONS_ROOT

That is why the current file can separate things like:

• combat firearms
• throwables and explosives
• plantables and mountables
• tools
• consumables
• attachments

without forcing every item into a single flat folder structure.

Live tuning inside the menu

The editor_live_tuning block is one of Duck Shot's best admin-side conveniences because it gives less-technical builders a small safe surface for quick iteration.

editor_live_tuning:
  enabled: true
  damage_step: 0.5
  shots_per_second_step: 0.25
  spread_step: 0.05
  projectile_speed_step: 0.10

This is not meant to replace full YAML editing. It is there for:

• quick damage checks
• live spread testing
• temporary projectile-speed iteration
• sanity-checking a new build before deeper balance work

Common mistakes in gui.yml

A weapon appears in the wrong menu

Check the category order first. With first_match_wins: true, a broad early rule can catch the weapon before the intended category sees it.

Attachments show up beside guns

Make sure the firearm category excludes attachment tags and attachment IDs. The example config already uses this pattern.

Test items leak into public browsing

Keep a test category near the top and aggressively exclude test, example, and conditional tags from public lanes.

Files that work with gui.yml

gui.yml is easiest to reason about when you treat it as part of a larger authoring stack:

• classifications.yml helps define tags and families that categories can respond to
• editor/create_wizard_schema.yml decides how items are created
• visual_states.yml controls how the chosen item looks in hand
• weapons/*.yml still remain the actual source of weapon behavior

Recommended next pages

• create Wizard, Templates, and Knobs
• support YML Files and Global Editors
• projectiles, Spread Patterns, Recoil, and Debugging