> For the complete documentation index, see [llms.txt](https://axiomemu.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://axiomemu.gitbook.io/docs/data/plugins/customjewel.md).
# CustomJewel
Custom jewel definitions with per-target filters, per-tier success rates, success/failure outcomes, and sale prices
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
```xml
```
## 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](/docs/data/item/item.md) |
## 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
`0` blocks the slot. Any other value (including `-1` and `1`) allows it.
| 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 |
## 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](/docs/gameserver/common-dat.md#account-level-al0-al3).
## 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 `` 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 `` 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 `` child element lists stat deltas subtracted from the target item when the jewel fails. The attributes are the same as ``. Level decreases are capped at 0; option fields are decremented.
## Cross-File Dependencies
| Attribute | Related in |
| --------------------------------- | -------------------------------------------------------------------------------- |
| `ItemIndex` | [Item.xml](/docs/data/item/item.md) |
| Client-side jewel visual | [CustomItemVisual.xml](/docs/data/plugins/customitemvisual.md) |
| Account level tiers (`AL0`-`AL3`) | [Common.dat Account Level](/docs/gameserver/common-dat.md#account-level-al0-al3) |
## 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