Enchants

Each enchant is stored in its own file under content/enchants/. This keeps the catalogue easy to extend and lets validation report the exact file containing an error.

Enchant schema

schema-version: 1

enchants:
  speed:
    display-name: '<aqua><bold>Speed Enchant</bold></aqua>'
    description: 'Increase how fast the player walks.'
    category: SOUL
    required-sword-level: 1
    gui:
      slot: 11
      material: FEATHER
      primary-colour: '<aqua>'
      accent-colour: '<white>'
      name: '{primary}<bold>Speed {accent}<bold>Enchant'
      lore: ['{menu_template_lore}']
    max-level: 3
    activation-chance: { base: 1.0, per-level: 0.0, maximum: 1.0 }
    cost: { currency: souls, base: 100, multiplier: 10.0 }
    effects:
      movement_speed:
        type: WALK_SPEED
        parameters: { bonus-per-level: 0.10, maximum-bonus: 0.30 }
    visual:
      particle: CLOUD
      particle-count: 6
      sound: ENTITY_BREEZE_WIND_BURST
      volume: 0.35
      pitch: 1.5
      animation: SPEED

The map key (speed) is the persistent enchant ID. Keep it identical to the filename and do not change it after players own levels, toggles, crystals, or forced-proc state for that enchant.

Categories and layout

Valid categories are SOUL, ESSENCE, and SHARD. The gui.slot must be one of the slots provided by menus/sword-enchanter.yml: items.enchant.slots. Slots explicitly assigned inside one category must not conflict.

required-sword-level controls when the enchant becomes purchasable. cost.currency must be a configured currency. The upgrade price grows from the base using the configured multiplier.

Activation chance

Chance values are decimal probabilities:

chance at level = min(maximum, base + per-level × level adjustment)

The final effective rolled chance can also receive player bonuses, but is capped by settings/gameplay.yml: rebirth.maximum-effective-enchant-proc-chance. Guaranteed passive effects are not turned into rolled effects by that cap.

Effect types

Supported runtime types include damage multipliers, flat damage boosts, currency multipliers, per-swing currency, sword XP, critical effects, multi-hit, explosions, chain attacks, execute, attack speed, walk speed, commands, damage-over-time, zone damage, and advanced abilities.

The safest way to add an enchant is to copy an existing file using the same effect type, assign a new stable ID and GUI slot, then adjust its values.

Visual load

Particles, sounds, and animation types are configured per enchant. Large zone-wide effects can touch many private mobs, so keep maximum-targets, hit counts, and intervals bounded. Use reduced-effects player settings and the engine budgets when testing high-proc builds.

Admin testing

/dga forceproc <player> <enchant>
/dga forceproc <player> clear
/dga testsword <player> --with-procs

Run /dga validate after every catalogue change. Test the enchant at minimum and maximum level before publishing it to players.