Enchanting & Item Modifiers

1. Summary

All item instances — including consumables (food, potions, scrolls) — can carry enchantments. Effects on equipment apply while worn or on hit; effects on consumables apply when the item is used (eat, drink, read scroll). Players spend reagents, mana, and stamina at an enchanting station, with success/failure and partial material loss on failure.

Gourmet enchanted meals are a top-tier player food economy (15, 10) — settlement hardtack stays bare; cooks sell unique enchanted feasts at stalls.

The item construction graph (09) includes enchantment definitions and enchant recipes as first-class nodes — not a separate ad-hoc system.

2. Locked decisions

3. Design principles

4. What can be enchanted

Slot limits per item (ruleset):

enchant_slots_by_quality:
  poor: 1
  common: 1
  fine: 2
  masterwork: 3
  legendary: 4

Replacing an enchant in a filled slot requires dispel reagent + separate ritual (higher cost) — not silent overwrite.

5. Item instance schema

struct ItemInstance {
    template_id: ItemTemplateId,
    quality: QualityTier,           // from craft roll (`09` C3)
    durability: f32,
    soul_bound: bool,
    enchantments: Vec<EnchantmentInstance>,
    // ... provenance, custom name, etc.
}

struct EnchantmentInstance {
    def_id: EnchantmentDefId,
    applied_by: CharacterId,
    applied_at: Timestamp,
    power: f32,                     // rolled at apply — skill influences roll
    charges: Option<u32>,           // None = permanent; Some = limited procs
}

Item template adds:

# assets/items/longsword.yaml
id: longsword
kind: weapon
consumable: false
enchantable: true          # default true when consumable: false
max_enchant_slots: null    # null = use quality table
allowed_enchant_tags: [weapon_melee, metal, blade]

# assets/items/iron_stew.yaml
id: iron_stew
kind: consumable_food
consumable: true
enchantable: true
allowed_enchant_tags: [food, cooked, meal]
on_use: eat                    # triggers consume + enchant on_consume effects

6. Enchantment definitions (graph nodes)

Enchantment defs are data assets — referenced by recipes and attached to instances.

# assets/enchantments/flame_edge.yaml
id: flame_edge
display_name: Flame Edge
tags: [weapon_melee, fire, on_hit]
kind: on_hit_proc

# Combat (`12`) — proc on successful primary hit
proc:
  chance_base: 0.15
  chance_per_power: 0.02
  effect: apply_dot
  dot:
    damage_type: fire
    dps: 3
    duration_ticks: 120
    tick_interval: 20
  splash: false

# Optional passive component (usually 0 for pure proc)
modifiers: []

requirements:
  min_enchanting: 25
  target_tags: [weapon_melee, metal]

# assets/enchantments/vitality_charm.yaml
id: vitality_charm
display_name: Vitality Charm
tags: [accessory, passive]
kind: passive

proc: null

modifiers:
  - target: derived.hp_regen
    op: mul
    value_base: 1.08
    value_per_power: 0.01

# assets/enchantments/venom_sting.yaml
id: venom_sting
display_name: Venom Sting
tags: [weapon_melee, poison, on_hit]
kind: on_hit_proc

proc:
  chance_base: 0.20
  effect: apply_dot
  dot:
    damage_type: poison
    dps: 2
    duration_ticks: 200
    reduces_healing_received: 0.1

# assets/enchantments/vigor_broth.yaml
id: vigor_broth
display_name: Vigor Broth
tags: [food, cooked, on_consume]
kind: on_consume

proc: null

on_consume:
  modifiers:
    - target: derived.stamina_regen
      op: mul
      value_base: 1.25
      value_per_power: 0.02
      duration_ticks: 900
  bonus_hunger_restore: 5          # stacks with base meal stats

Kinds:

7. Enchant recipes (graph edges)

Enchant recipes are not standard craft mint — they transform an existing instance:

struct EnchantRecipe {
    id: EnchantRecipeId,
    enchant_def: EnchantmentDefId,
    target_tags: Vec<Tag>,              // must match item template
    inputs: Vec<RecipeInput>,           // essences, dust, catalysts — consumed
    catalysts: Vec<RecipeInput>,        // consumed: false — reusable tools
    required_station: StationKind,      // enchantment_altar
    required_tools: Vec<ToolReq>,
    skill: SkillReq,                    // enchanting ≥ N
    mana_cost: u32,
    stamina_cost: u32,
    ritual_ticks: u32,
    base_success: f32,                  // 0.0–1.0
    failure_reagent_loss_pct: f32,      // partial loss (`09` C1 pattern)
    difficulty: u32,                    // scales with item quality / existing enchants
}

Example — Flame Edge on melee weapon:

Reagent chain example in graph:

fire_essence ──► salamander_scale, distilled_oil
sulfur_dust    ──► sulfur_chunk, mortar (tool)
binding_oil    ──► wild_herb, tallow

8. Enchant ritual flow

1. Player places target item + reagents at enchantment_altar (or inventory ritual UI)
2. Server validates: enchantable, free slot, tags, skills, station, tools
3. Debit mana + stamina immediately (not refunded on fail)
4. Progress ritual_ticks — interruptible; partial progress lost on cancel
5. Roll success:
     success → attach EnchantmentInstance (power roll from skill)
              → consume full reagents
              → XP to enchanting (+ elemental school if applicable)
     failure → consume reagents × failure_reagent_loss_pct
              → item unchanged (no enchant added)
              → XP (reduced)
6. Audit log + item instance update; broker listings refresh stats

Success chance:

success = clamp(
    base_success
  + (enchanting_skill - min_enchanting) × 0.008
  + (relevant_element_skill - threshold) × 0.004
  - difficulty × 0.01
  - existing_enchant_count × 0.05,
  0.05, 0.95
)

Power roll (on success): higher skill → tighter distribution toward max power — affects DoT dps, modifier strength, proc chance.

9. Resource & profit loop (economy)

Typical enchanter business (10):

Margin drivers: rare essences, high skill (fewer fails), masterwork bases (more slots), regional reagent prices.

Enchanted items show full enchant tooltip at stall inspect — transparency for buyers.

Workers (13) may run enchant job steps if residence has altar + stocked reagents — wages + pantry + failure loss still apply.

10. Combat integration (12)

On weapon hit resolution (after hit confirmed, before damage mitigation complete):

for enchant in weapon.enchantments where kind == on_hit_proc:
    if roll(proc.chance_base + proc.chance_per_power × enchant.power):
        apply_dot or apply_debuff per enchant.def

• Flame Edge — fire DoT ticks on target; stacks policy per ruleset (refresh duration vs stack intensity)
• Venom Sting — poison DoT + healing reduction debuff
• Procs use server RNG; clients show VFX from replicated proc events

Passive enchants (necklace HP regen) register modifiers on equip / remove on unequip — same pipeline as gear stats (08 §6, 11 §11).

Enchant does not replace base weapon damage — it adds proc layer and/or modifier layer.

10.1 Consumable use (flatland eat, drink, scroll read)

On successful consume (12 consumable path):

for enchant in item.enchantments where kind == on_consume:
    apply on_consume.modifiers to consumer (duration from def)
    apply bonus_restore fields (hunger, mana, heal, …)
remove item instance from inventory

• Vigor Broth on iron_stew — extra stamina regen buff after eating
• Potions — enchant may add resist buff or amplify heal_amount
• Scrolls — enchant modifies spell payload when read (costly, high skill)

Inspect before buy: base meal stats plus enchant preview. Settlement NPC food is not enchanted — only player/crafter instances.

11. Skills

XP on success > XP on failure; critical success (high roll) bonus XP + bonus power.

12. Stations & tools

Altar kit is a craft graph node — crafters sell altars to enchanters.

13. TUI / agent

flatland enchant list --station altar
flatland enchant plan flame_edge --item <instance>
flatland enchant start flame_edge --item <instance> --station <id>
flatland item inspect <instance> --json    # enchantments[], power, proc stats

Agent JSON exports enchant defs + recipes for margin calculators.

14. Phasing

15. Content pipeline

assets/
  enchantments/*.yaml       # defs (proc, modifiers, tags)
  enchant_recipes/*.yaml    # rituals
  items/*.yaml              # enchantable, allowed_enchant_tags
tools/
  validate-enchant-graph.mjs

16. Open questions

Resolved (2026-07-06):

Crafting graph & stations: 09-crafting-and-recipes.html
Markets & stalls: 10-economy-and-markets.html