Create Wizard, Templates, and Knobs

Duck Shot includes a schema-driven editor and create-weapon wizard. This is the layer that turns a huge YAML surface into a guided authoring flow.

The important files are:

• editor/create_wizard_schema.yml
• editor/knobs.yml
• editor/templates/*.yml
• editor/global_editor_schema.yml

If you are creating a content pipeline for a server team, this part of Duck Shot matters almost as much as the weapon files themselves.

What the wizard is actually doing

Duck Shot's create flow is not hardcoded to one weapon type. It is grouped and schema-driven:

create_wizard:
  groups:
    combat:
      tracks: [gun, melee]
    throwable:
      tracks: [throwable]
    utility:
      tracks: [grapple, attachment, emitter]

That means the editor can open different creation tracks for:

• guns
• throwables
• consumables
• grapples
• attachments
• magic items
• plantable or mountable devices

The editor files and what each one does

The editor stack is easier to manage when you treat each file as its own job:

• editor/create_wizard_schema.yml = the creation flow and track registry
• editor/editor_settings.yml = admin-side create defaults and quick-add bundles
• editor/global_editor_schema.yml = dedicated in-game editors for support files
• editor/knobs.yml = the actual per-control definitions
• editor/templates/*.yml = the starting YAML skeletons

If you change the wrong file, the editor may still open, but it will feel confusing or incomplete.

Groups and tracks

Think of the wizard in layers:

• a group is a high-level lane like Combat or Utility
• a track is the actual item path like Gun, Throwable, or Grapple
• a template is the YAML starter file
• seed values and seed lists stamp defaults into the new item

This is why Duck Shot can guide creators into the right setup instead of dumping one giant YAML form on them.

Template files

The included templates give you the cleanest starting point for each item family:

• gun_base.yml
• throwable_base.yml
• consumable_base.yml
• grapple_base.yml
• plantable_mountable_base.yml

For example, gun_base.yml already seeds the normal baseline:

category: RIFLE
ammo:
  type: RIFLE
  magazine_size: 30
fire:
  mode: SEMI

That is exactly what you want from a starter template: enough to be valid, not so much that every new item starts bloated.

Classification strategy

The wizard can also decide how template classifications and schema defaults combine:

classification_strategy: merge

Common strategies:

• template_if_present
• merge
• template_only
• default_only

When to use merge

Use merge when you want the schema to add server-wide defaults like primary or consumable while still respecting the template's own classifications.

When to use template_only

Use template_only if the template itself is the authoritative item identity.

Seed values and seed lists

The wizard can prefill values directly into the new weapon file:

seed_values:
  display.visual_key: "%id%"
 
seed_lists:
  display.lore:
    mode: append
    values:
      - "{classified_label} {classification_display_csv}"

This is what makes the create flow feel finished:

• the item gets a visual key automatically
• lore can already include classification placeholders
• creators do not have to retype the same setup every time

editor_settings.yml

editor_settings.yml is the practical admin layer that sits above the schema.

The default editor_settings.yml includes features such as:

• seed_children_defaults
• simple_view_default
• quick-add bundles
• type-level quick-add profiles
• category matching for bundle defaults

That means this file is about creation ergonomics, not weapon behavior. Use it when you want the editor to feel smarter for admins without rewriting the whole schema.

What knobs.yml is for

editor/knobs.yml is the opt-in admin tools for the editor.

A knob tells Duck Shot:

• which YAML path a control edits
• what type it is
• when it is visible
• which children it activates
• whether inactive child settings should be pruned

Example:

- id: weapon.projectile.homing_enabled
  path: projectile.behavior.homing.enabled
  type: BOOLEAN
  seed_children_defaults_on_activate: true
  prune_children_on_deactivate: true

This is a big deal because advanced systems like homing or lock-on should not clutter the editor until the creator actually enables them.

global_editor_schema.yml

This file is what lets Duck Shot offer focused in-game editors for support YAML instead of one giant raw-config screen.

The default editor schema already maps dedicated editor surfaces for:

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

That is why Duck Shot can expose things like a Classification Studio and a Visual State Studio without pretending that every file should be edited the same way.

Template files are starter kits, not final answers

The templates folder currently includes files such as:

• gun_base.yml
• throwable_base.yml
• consumable_base.yml
• grapple_base.yml
• plantable_mountable_base.yml
• conditions_templates.yml
• particle_stage_templates.yml
• sound_stage_templates.yml

Use them as clean launch points. Do not try to cram every future option into one starter template, or the create flow becomes noisy immediately.

Additive authoring instead of giant forms

The best way to use the Duck Shot editor is:

1. start with identity and base combat
2. make the item work
3. add only the advanced knobs the item actually needs

That means:

• do not turn on lock-on for a normal rifle
• do not enable explosive branches on a med kit
• do not add visual-state complexity to an item that only needs one model

Examples of what a knob should feel like

Homing

This should appear only after projectile.behavior.homing.enabled is turned on.

Then the child knobs like range and turn rate become editable.

Burst fire

The editor should expose burst size and interval only when fire.mode is BURST.

Lock-on

Lock-on range and required ticks should stay hidden until the lock system is enabled.

That keeps the interface readable for the average creator.

Why this matters for server teams

This system is the reason Duck Shot can support:

• cleaner first drafts for less experienced builders
• consistent file structure across a large pack
• safer handoff between admins, builders, and artists
• faster setup without forcing every item into one giant YAML

Use the right template first

The fastest way to keep a pack readable is to start from the template that already matches the item family.

Use:

• gun_base.yml for firearms
• throwable_base.yml for grenades, shells, and simple planted explosives
• consumable_base.yml for med kits and one-shot support items
• grapple_base.yml for traversal tools and recovery tools
• plantable_mountable_base.yml for mounted devices, mortars, and placeable systems

Go deeper here:

• starter Templates for Guns, Throwables, Consumables, Grapples, and Devices
• stage Templates for Sounds, Particles, and Conditions

When to hand-edit YAML instead

Use the wizard and editor for:

• new item creation
• structured tuning
• category-safe setup

Hand-edit YAML when you are doing:

• deep effect libraries
• very custom explosive chains
• large particle profile authoring
• bulk copy-adjust workflows across many files

Practical editor debugging flow

If the in-game editor feels wrong, use this order:

1. create_wizard_schema.yml if a track, category, or flow step is missing
2. editor_settings.yml if quick add or default bundles feel wrong
3. knobs.yml if a field does not appear, appears too early, or refuses to prune
4. global_editor_schema.yml if a support-file editor layout feels messy
5. templates/*.yml if new items are being created with the wrong baseline content

That order saves a lot of wasted time because the visible symptom is not always caused by the file you edited most recently.

Recommended next pages

• weapon File Structure
• gui Browser, Live Tuning, and Categories
• support YML Files and Global Editors
• ammo, Attachments, and Classifications
• projectiles and Impacts
• starter Templates for Guns, Throwables, Consumables, Grapples, and Devices
• stage Templates for Sounds, Particles, and Conditions