CustomJewel.xml

Defines custom jewels that enhance equipment. Each jewel specifies which items it can target (via filters on item level, options, set/socket state, slot), per-tier success rates, a vendor sell price, and the stat deltas applied on success or failure.

File Location#

Data/Plugins/Items/CustomJewel.xml

Loaded once at GameServer startup. Supports hot reload via plugin admin command.

Schema#

<CustomJewels>
    <Jewel Index="..." ItemIndex="..."
           MinItemLevel="..." MaxItemLevel="..."
           MaxItemOption1="..." MaxItemOption2="..."
           MinItemOption3="..." MaxItemOption3="..."
           MinItemNewOption="..." MaxItemNewOption="..."
           MaxItemSetOption="..."
           MinItemSocketOption="..." MaxItemSocketOption="..."
           EnableSlotWeapon="..." EnableSlotArmor="..." EnableSlotWing="..." EnableSlotAccessory="..."
           SuccessRateAL0="..." SuccessRateAL1="..." SuccessRateAL2="..." SuccessRateAL3="..."
           SalePrice="..." RejectIfNoEffect="1">
        <Success Level="..." Option1="..." Option2="..." Option3="..."
                 NewOption="..." SetOption="..." SocketOption="..." />
        <Failure Level="..." Option1="..." Option2="..." Option3="..."
                 NewOption="..." SetOption="..." SocketOption="..." />
    </Jewel>
</CustomJewels>

Identity#

Attribute	Type	Effect
`Index`	0-14	Jewel slot ID. Max 15 jewels
`ItemIndex`	int	Item ID of the jewel. `Type * 512 + SubIndex`. See Item.xml

Target Filters#

-1 means no limit on that attribute.

Attribute	Effect
`MinItemLevel` / `MaxItemLevel`	Target item +level range
`MaxItemOption1`	Max skill option. `0` requires no skill. Target must also be an item whose base definition supports skill
`MaxItemOption2`	Max luck option. `0` requires no luck
`MinItemOption3` / `MaxItemOption3`	Additional damage option range (0-7)
`MinItemNewOption`	Minimum excellent option count (counts bits set on the item's NewOption)
`MaxItemNewOption`	If less than or equal to 10: maximum excellent option count. If greater than 10: treated as an exclude mask - the filter rejects the item when any of the bits in `(value - 10)` are already set on the item's NewOption
`MaxItemSetOption`	Set option requirement bitmask. The filter always rejects an item that already has a set option. Bit 0 (value 1) also requires set option index 0 to be defined for that item; bit 1 (value 2) requires set option index 1
`MinItemSocketOption`	Minimum socket slots. `0` requires any socket-capable item. Non-zero requires at least that many opened sockets
`MaxItemSocketOption`	Maximum socket slots. `0` requires a non-socket item. Non-zero caps the number of opened sockets and rejects items already at their socket capacity

Slot Enable#

Weapon, armor and wing: 0 blocks the slot. Any other value (including -1 and 1) allows it.

Accessory is opt-in: only 1 allows it. 0 or a missing attribute blocks it, so existing jewels keep their old behavior.

Attribute	Slot
`EnableSlotWeapon`	Weapons (Type 0-5)
`EnableSlotArmor`	Armor (Type 6-11)
`EnableSlotWing`	Wings and wing-like items. Covers the wing ranges in Type 12 (`0-6`, `36-43`, `49`, `50`, `200-265`) plus the Cape in Type 13 slot 30
`EnableSlotAccessory`	Rings and pendants (any item with Item.xml `Slot` 9, 10 or 11). Set `MaxItemLevel` too: custom jewels do not use the Bless/Soul jewelry level cap

Success Rates#

Per-tier success rate (0-100 percent). Values above 100 have no extra effect.

Attribute	Tier
`SuccessRateAL0`	Free account
`SuccessRateAL1`	Bronze / VIP 1
`SuccessRateAL2`	Silver / VIP 2
`SuccessRateAL3`	Gold / VIP 3

See Account Level.

Vendor#

Attribute	Effect
`SalePrice`	Zen sell price when a player sells the jewel to an NPC

No-Effect Guard#

Attribute	Default	Effect
`RejectIfNoEffect`	`1`	Before rolling, the server dry-runs `<Success>` on a copy of the target. If level, skill, luck, additional option, excellent options, set option and sockets would all stay the same (item already maxed for everything this jewel adds), the use is refused with a chat notice and the jewel is not consumed. Set `0` to allow using the jewel anyway

The target filters above are AND-ed, so a jewel that adds both a level and excellent options cannot express "reject only when every dimension is already maxed" with MaxItemLevel / MaxItemNewOption alone. This guard covers that case; leave the filters at -1 and let the dry-run decide.

Success Outcome#

The <Success> child element lists the stat deltas applied to the target item when the jewel succeeds.

Attribute	Effect
`Level`	Adds to the item's +level, capped at 15
`Option1`	Adds skill option (`0` or `1`)
`Option2`	Adds luck option (`0` or `1`)
`Option3`	Adds to additional damage option (capped at the server's MaxItemOption)
`NewOption`	If less than 10: number of random excellent options to roll on (rolls stop once the item's excellent-option cap is reached). If 10 or greater: `(value - 10)` is OR'd directly onto the item's excellent option flags
`SetOption`	Set option write mask. Bit 0 (value 1) assigns set index 0, bit 1 (value 2) assigns set index 1 (or randomly picks between them if both are valid for the item). Bit 2 (value 4) advances set tier to 1; bit 3 (value 8) advances it to 2
`SocketOption`	Number of empty socket slots to open on the target item. Slots opened this way start empty and can be filled with a Seed Sphere

Failure Outcome#

The <Failure> child element lists stat deltas subtracted from the target item when the jewel fails. The attributes are the same as <Success>. Level decreases are capped at 0; option fields are decremented.

Cross-File Dependencies#

Attribute	Related in
`ItemIndex`	Item.xml
Client-side jewel visual	CustomItemVisual.xml
Account level tiers (`AL0`-`AL3`)	Common.dat Account Level

Important Behavior#

The jewel table is sent to the client at login (game data sync). Custom jewels defined here are fully recognized client-side: dragging a custom jewel onto a target item works the same as a built-in jewel, and the drag-and-drop targeting rules match the server filters. No client patch is needed to add a new custom jewel; players who were already logged in must re-login to receive an updated table.

Common Issues#

Jewel accepted on wrong item - filter attributes too permissive (-1 everywhere). Add explicit restrictions
All tiers have the same success rate - intentional; mirror a single rate across all four AL keys, or set different values to differentiate VIP benefits
VIP success rate ignored - account record has AccountLevel = 0; tier keys AL1-AL3 never apply to that account
Success rate higher than 100 has no extra effect - the roll is capped at 100
Socket jewel rejected on pentagram - pentagram-style items follow a dedicated server-side branch; socket filters may not behave the same way as on regular weapons and armor
NewOption greater than or equal to 10 writes unexpected bits - remember the value is OR'd as (value - 10) onto the existing NewOption bitmask, not as a count