Process

One strengthening run combines target equipment, a recipe, materials, success chance, and failure results; when a stage goes wrong, follow the flow: first check whether the recipe matches, then materials and costs, and finally PDC writes and presentation refresh

Standard flow

┌─────────────────────────────────────────────────────────────┐
│ 1. Player opens the strengthen GUI                           │
│ 2. Insert target equipment → read current star and temper    │
│ 3. Match an available recipe through the recipe rules        │
│ 4. Validate materials, costs, conditions, and star limit     │
│ 5. Compute success rate (base + temper bonus, clamped)       │
│ 6. Fire StrengthenPreAttemptEvent (cancellable, rate-writable) │
│ 7. Roll the outcome → success / failure                      │
│ 8. Rebuild the item and write the strengthen layer           │
│ 9. Charge economy costs                                      │
│ 10. Fire StrengthenAttemptEvent                              │
│ 11. Run that star's actions.success / actions.failure        │
│ 12. Broadcast on first reach of a broadcast star             │
│ 13. Settle escrow on the owner thread, refresh GUI/inventory │
└─────────────────────────────────────────────────────────────┘

Troubleshooting entry points

Symptom	Check first
GUI says strengthening is unavailable	The recipe's top-level matcher / slot_groups, current star, limits.max_star, and the stars node
Insufficient materials after clicking	materials, item sources, amounts, and the player's actual inventory
Currency shortage or charge issues	economy.currencies, the economy provider, and cost_formula
Star level does not change	Whether the strengthen layer was written, and whether failure downgrade or a protection material applied
Lore is not refreshed	Whether CoreLib assembly ran; use /estrengthen refresh if needed

Stage details

Stages 1-2: opening the GUI and item recognition

You open the strengthen GUI and place the target item into the designated slot. The module:

• Reads the item's current strengthen layer (star, temper level, milestone flags, success/failure counts, branch path)
• Treats an item without a strengthen layer as +0

Stage 3: recipe matching

Recipes match the target through the following top-level fields, combined with AND:

Field	Description
matcher	General item matcher for non-item-source conditions such as components, PDC, lore, and variables. The top-level item-source condition is expressed by the sibling source_patterns. See Item Matcher
slot_groups	Coarse slot/equipment type groups (weapon/armor/offhand/generic), not concrete equipment slots
stats_any	Has any of the given attributes
source_patterns	Match by item source pattern

The old match block is no longer read; see Recipes for migration

The current star must also be below limits.max_star, and the target star must have a matching entry in stars

Stage 4: validation

Check	Failure behavior
Required material amounts	Reports insufficient materials and blocks the attempt
Economy balance	A failed charge returns an uncommitted result
Condition check	Returns strengthen.error.condition_not_met when conditions are unmet
Star limit	Blocks the attempt once limits.max_star is reached

This stage detects protection and temper materials but never requires them

Stage 5: success rate

rate = target-star base rate + effective temper × temper_chance_bonus_per_level
final rate = clamp (rate, 0, success_chance_cap)

• The target-star base rate comes from the recipe success_rates entry for that star; if the recipe does not define one, it falls back to the global success_rates in config.yml
• Effective temper = clamp(current temper + material temper_boost, 0, max_temper)

Stages 6-7: event and roll

StrengthenPreAttemptEvent fires on the main thread. You can cancel it from your listener or rewrite its success rate with setSuccessRate. A random number in [0, 100) is then drawn; a value below the rate means success

Stage 8: writing the strengthen layer

Outcome	Star	Temper
Success	Raised to the target star	Reset to 0
Failure (target star < 6)	Unchanged	Temper gain added
Failure (target star ≥ 6, no protection)	Drops 1 star, floor 0	Temper gain added
Failure (protection material used)	Unchanged	Temper gain added

Temper gain is +1 when the target star is 8 or below and +2 above 8, then clamped to limits.max_temper

Whether the run succeeds or fails, the item's success count, failure count, and last attempt time are updated; success also records first-reach star milestones

Stages 9-13: charging, actions, and safe settlement

• The item is rebuilt first, and economy costs are charged only after that succeeds; a failed charge leaves the attempt uncommitted
• StrengthenAttemptEvent fires during settlement
• That star's actions.success / actions.failure receive a mutable item_target, and the final item is read only after the action chain completes
• Reaching a star in broadcast.local_stars or broadcast.global_stars for the first time sends a broadcast; see Broadcast
• The final item, unconsumed materials, and other escrow content are settled only on the player's owner thread, after which the GUI and inventory refresh
• If material consumption or target rebuild/commit fails, the source restores material amounts and attempts to compensate charged economy. The failed attempt is not committed as a partial result

Pending settlement and recovery

When the result actions have run but the player is offline or entity scheduling is rejected, the attempt is held as pending settlement: nothing is delivered early and no escrow is discarded

• When the player rejoins, the module retries settlement on that player's owner thread
• Opening the strengthen GUI also retries pending settlement
• Closing the GUI or reloading configuration does not clear committed pending settlement
• Settlement records completion phases; if the result item was delivered but a later material-return step failed, a retry resumes the remaining phase without delivering the result item again
• A pending entry is removed only after every settlement phase completes, keeping retries idempotent

NOTE

The pending queue is an in-process recovery mechanism; it does not guarantee persistence across a full server restart

Temper

Temper is a level accumulated on failure that compensates for losing streaks:

• Each failure adds 1 or 2 temper levels depending on the target star, capped at limits.max_temper
• Each temper level raises the next attempt's success rate by limits.temper_chance_bonus_per_level
• Temper resets to 0 after a successful strengthen
• Materials can define temper_boost to supply extra temper bonus for the current attempt
• Admins clear the main-hand item's temper with /estrengthen clearcrack

Temper state is stored in the strengthen layer PDC

Milestone stars

stars.<star>.name names a star for GUI display. The item state records the set of stars reached for the first time, which prevents duplicate broadcasts

At a milestone star you trigger that star's effects and actions:

• Extra attributes (ea_attribute) and skill attachment (es_skill)
• Name prefixes or lore markers (name_action / lore_action)
• Success actions such as broadcasts, sounds, and titles

Action nodes

The actions node of a star stage supports two keys:

Node	Trigger
actions.success	After a successful strengthen at that star
actions.failure	After a failed strengthen at that star

Action example

stars:
  8:
    name: "<gold>Damage Boost</gold>"
    actions:
      success:
        - 'send_title title="<gold><bold>+8 Damage Boost</bold></gold>" subtitle="<yellow>Bonus damage unlocked</yellow>"'
        - "play_sound sound=minecraft:entity.player.levelup volume=1.1 pitch=1.2"
      failure:
        - 'send_message text="<red>Strengthening failed, currently +%star%.</red>"'
        - "play_sound sound=minecraft:block.anvil.destroy volume=1 pitch=0.8"

The placeholders available in action lines are listed in Placeholders