> 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

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
<CustomJewels>
    <Jewel Index="..." ItemIndex="..."
           MinItemLevel="..." MaxItemLevel="..."
           MaxItemOption1="..." MaxItemOption2="..."
           MinItemOption3="..." MaxItemOption3="..."
           MinItemNewOption="..." MaxItemNewOption="..."
           MaxItemSetOption="..."
           MinItemSocketOption="..." MaxItemSocketOption="..."
           EnableSlotWeapon="..." EnableSlotArmor="..." EnableSlotWing="..."
           SuccessRateAL0="..." SuccessRateAL1="..." SuccessRateAL2="..." SuccessRateAL3="..."
           SalePrice="...">
        <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](/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 |

## 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 NewOption bitmask                          |
| `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 (changes closed slots from `0xFF` to `0xFE`)                                                                                                                                                         |

## 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](/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