5-Minute Quick Start

Previous: Installation & Environment　·　Next: Core Concepts & Architecture

This page walks you from zero to a sword with attributes, a left-click skill effect, and epic quality — pick either route: hand-written YAML or the in-game GUI.

---

Route A: Hand-written YAML (recommended to understand the structure)

Step 1: Create / open a type file

Items are stored per type under plugins/QinhItems/items/; the filename is the type. For weapons, edit items/weapon.yml. Each top-level key is one item ID.

Step 2: Paste an item

my_first_sword:                     # ← item ID (lowercase, underscores)
  type: weapon                      # item type
  material: diamond_sword           # base material (vanilla material name)
  display_name: "<gold>Trial Blade</gold>"   # name, supports MiniMessage
  tier: EPIC                        # quality (see item_tiers.yml)
  lore:
    - ""
    - "<gray>Swing on left-click, sparks burst</gray>"
    - "<dark_gray>Cooldown 3s</dark_gray>"
  providers:
    ap:
      value: '{"attack_damage":18,"crit_rate":0.12}'   # attributes (handed to AttributePlus)
  options:
    unbreakable: true               # infinite durability
    glow: true                      # enchant glow
  actions:
    triggers:
      left_click:                   # left-click trigger
        trigger:
          atom: left_click
        cooldown: 3s                # 3s cooldown
        refs:                       # handlers run in order
          - handler: qi:title
            payload: "<gold>⚡ Spark ⚡</gold>||<gray>The blade rings</gray>||3||30||10"
          - handler: qi:sound
            payload: "minecraft:entity.player.attack.crit;1;1.2"

Step 3: Reload and grab it

/qi reload
/qi give my_first_sword

Left-click to swing and you'll see the title and sound, plus a 3s cooldown. Attributes are taken over by AttributePlus once equipped in hand (assuming AP is installed).

✅ Done! Next you can:

• Add random-value variables
• Add gem sockets
• Bind it into a set
• Make it soulbound

---

Route B: In-game GUI (no YAML)

Step 1: Open the editor

/qi editor

Opens the type browser. For full navigation see Editor Overview.

Step 2: Pick a type → create item

1. Click the Weapon type.
2. Click "New item" and type the item ID in chat (e.g. my_first_sword).
3. Enter the item editor main screen.

Step 3: Edit field by field

In the item editor, click the matching buttons (see Item Editor):

• Material → type diamond_sword in chat
• Quality → type EPIC in chat
• Display name → type <gold>Trial Blade</gold> in chat
• Attributes → open the attribute editor, add attack_damage = 18
• Actions/skills → open the action editor, under the left_click tab add the qi:title / qi:sound handlers

Step 4: Save

Click the Save button at the bottom right (emerald, slot 53). QI validates, writes back the YAML, then hot-reloads the action table.

🖼️ [Image placeholder] Item editor main screen (field buttons annotated) · suggested assets/editor-item-main.png

---

The two routes compared

	Hand-written YAML	GUI editor
Ramp-up	Medium (need the structure)	Fast
Bulk work	Strong (copy-paste)	Weak
Complex actions / sets	Flexible	Guided, hard to break
Best for	Veterans, mass gearing	Beginners, single-item polish

The two are fully interchangeable: saving in the GUI produces the same YAML; conversely, after hand-editing, /qi reload lets you open it in the GUI.

---

Common first pitfalls

• Attributes don't apply? You don't have AttributePlus, or combat.enabled is off — pure item-library mode. See Attributes & Numbers.
• Action doesn't fire? Actions load only on /qi reload; reload after editing YAML.
• Quality name not showing? tier must be uppercase (EPIC) and exist in item_tiers.yml. See Quality & Display.
• material errors? Use a vanilla material name (e.g. diamond_sword); anything with : or - is treated as an external item-source reference.

Next → Core Concepts & Architecture