> 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/jewelsbank.md).

# Jewels Bank

The Jewels Bank provides account-wide storage for jewels and other stackable items, with capacity limits based on account level. Players can deposit and withdraw items across all characters on their account, with optional auto-deposit functionality.

## File Location

```
Data/Plugins/Items/JewelsBank/JewelsBank.xml
```

## Dependencies

| Depends On                          | Purpose                                                          |
| ----------------------------------- | ---------------------------------------------------------------- |
| DataServer                          | Stores account bank data, auto-deposit flag, and transaction log |
| AccountLevel System                 | Determines storage capacity multipliers (AL0 through AL4/VIP)    |
| [Item.txt](/docs/data/item/item.md) | Source of the Type/Index pairs used in the `<Items>` list        |

## Configuration Structure

```xml
<JewelsBank Enable="1" MaxItemsPerPage="9" ConfirmCooldownMs="1000">
    <AccountLimits>
        <!-- Storage capacity multipliers by account level -->
    </AccountLimits>
    <Items>
        <!-- Allowed items and their base storage limits -->
    </Items>
</JewelsBank>
```

## Sections

### Root Element

```xml
<JewelsBank Enable="1" MaxItemsPerPage="9" ConfirmCooldownMs="1000">
```

| Attribute           | Type | Default | Description                                                   |
| ------------------- | ---- | ------- | ------------------------------------------------------------- |
| `Enable`            | bool | 0       | Enable/disable the entire plugin                              |
| `MaxItemsPerPage`   | int  | 9       | Items displayed per page in UI (cosmetic)                     |
| `ConfirmCooldownMs` | int  | 1000    | Milliseconds between deposit/withdraw actions to prevent spam |

{% hint style="info" %}
**ConfirmCooldownMs** prevents accidental double-clicks and reduces database write load. 1000ms (1 second) is recommended for normal play.
{% endhint %}

### AccountLimits

Defines storage capacity multipliers based on account level. The actual storage limit for each item is `MaxCount * Multiplier`.

```xml
<AccountLimits>
    <Tier Level="0" Multiplier="1.0" />   <!-- Standard -->
    <Tier Level="1" Multiplier="1.5" />   <!-- AL1 -->
    <Tier Level="2" Multiplier="2.0" />   <!-- AL2 -->
    <Tier Level="3" Multiplier="3.0" />   <!-- AL3 -->
    <Tier Level="4" Multiplier="5.0" />   <!-- VIP -->
</AccountLimits>
```

| Attribute    | Type  | Default  | Description                                      |
| ------------ | ----- | -------- | ------------------------------------------------ |
| `Level`      | int   | Required | Account level (0-4)                              |
| `Multiplier` | float | 1.0      | Storage capacity multiplier applied to all items |

**Example**: With `MaxCount="500"` for Bless and `Multiplier="2.0"` for AL2:

* AL2 players can store 500 \* 2.0 = 1,000 Jewels of Bless

### Items

Defines which items can be stored and their base maximum counts.

```xml
<Item Type="14" Index="13" Level="*" MaxCount="500" Name="Jewel of Bless" />
<Item Type="14" Index="11" Level="0" MaxCount="50" Name="Box of Kundun +1" />
```

| Attribute  | Type   | Default  | Description                                                   |
| ---------- | ------ | -------- | ------------------------------------------------------------- |
| `Type`     | int    | Required | Item type category (e.g., 14 = Jewels, 12 = Wings/Bundles)    |
| `Index`    | int    | Required | Item index within type                                        |
| `Level`    | string | `*`      | Item level filter: `*` = all levels, or specific level (0-15) |
| `MaxCount` | int    | 100      | Base storage limit before account level multiplier            |
| `Name`     | string | -        | Display name for logging (not shown to players)               |

**Item Code Calculation**: `ItemCode = Type * 512 + Index`

Example: Jewel of Bless = 14 \* 512 + 13 = 7181

#### Level Matching Behavior

{% hint style="info" %}
The `Level` attribute determines level-specific storage:

* `Level="*"` - Stores all item levels together (aggregated count)
* `Level="0"` - Separate storage for level 0 items only
* When depositing with `Level="*"`, items preserve their actual level internally but display as a combined total
  {% endhint %}

**Example Configuration**:

* `Level="*"`: All Box of Kundun levels (+1 to +5) share one storage pool
* `Level="0"`, `Level="1"`, etc.: Each level has separate storage

## Important Behavior

{% hint style="info" %}
**Account-Wide Storage**: The bank is shared across all characters on an account. If Character A deposits 100 Bless, Character B can withdraw them.
{% endhint %}

{% hint style="info" %}
**Level Preservation**: When depositing items with `Level="*"` configuration, the system internally tracks each item's actual level. Withdrawing retrieves items at their original level, even though they display as a combined count.
{% endhint %}

{% hint style="warning" %}
**Database Saves**: All deposit/withdraw operations trigger an immediate database save to prevent item loss during crashes. High-frequency transactions may increase DataServer load.
{% endhint %}

{% hint style="warning" %}
**Auto-Deposit Setting**: Players can toggle auto-deposit (automatically sends configured items to bank on pickup). This setting is stored in the database and persists across sessions. The first item pickup after login triggers a full bank data load.
{% endhint %}

{% hint style="info" %}
**Config and runtime limits**: The plugin accepts up to 64 `<Item>` entries in the `<Items>` block. A player's bank can hold up to 128 distinct `(ItemCode, Level)` rows simultaneously.
{% endhint %}

## Item Code Reference

Common jewel item codes for configuration:

| Item Name           | Type | Index | ItemCode | Notes                 |
| ------------------- | ---- | ----- | -------- | --------------------- |
| Jewel of Bless      | 14   | 13    | 7181     | Core jewel            |
| Jewel of Soul       | 14   | 14    | 7182     | Core jewel            |
| Jewel of Life       | 14   | 16    | 7184     | Core jewel            |
| Jewel of Creation   | 14   | 22    | 7190     | High-tier jewel       |
| Jewel of Chaos      | 12   | 15    | 6159     | **Type 12**, not 14!  |
| Jewel of Guardian   | 14   | 31    | 7199     | Socket jewel          |
| Jewel of Harmony    | 14   | 41    | 7209     | Harmony jewel         |
| Gemstone            | 14   | 43    | 7211     | Socket item           |
| Lower Refine Stone  | 14   | 44    | 7212     | Refining              |
| Higher Refine Stone | 14   | 45    | 7213     | Refining              |
| Box of Kundun       | 14   | 11    | 7179     | Level-specific (0-15) |
| Bless Bundle        | 12   | 30    | 6174     | Bundle item           |
| Soul Bundle         | 12   | 31    | 6175     | Bundle item           |

## Examples

{% tabs %}
{% tab title="Basic Setup" %}

```xml
<JewelsBank Enable="1" MaxItemsPerPage="9" ConfirmCooldownMs="1000">
    <AccountLimits>
        <Tier Level="0" Multiplier="1.0" />
        <Tier Level="1" Multiplier="1.5" />
        <Tier Level="2" Multiplier="2.0" />
    </AccountLimits>
    <Items>
        <!-- Core jewels -->
        <Item Type="14" Index="13" Level="*" MaxCount="500" Name="Jewel of Bless" />
        <Item Type="14" Index="14" Level="*" MaxCount="500" Name="Jewel of Soul" />
        <Item Type="14" Index="16" Level="*" MaxCount="500" Name="Jewel of Life" />
        <Item Type="12" Index="15" Level="*" MaxCount="200" Name="Jewel of Chaos" />
    </Items>
</JewelsBank>
```

**Result**: Standard account (AL0) can store 500 of each core jewel, AL1 gets 750, AL2 gets 1000.
{% endtab %}

{% tab title="Level-Specific Boxes" %}

```xml
<Items>
    <!-- Each Kundun box level stored separately -->
    <Item Type="14" Index="11" Level="0" MaxCount="50" Name="Box of Kundun +1" />
    <Item Type="14" Index="11" Level="1" MaxCount="50" Name="Box of Kundun +2" />
    <Item Type="14" Index="11" Level="2" MaxCount="50" Name="Box of Kundun +3" />
    <Item Type="14" Index="11" Level="3" MaxCount="50" Name="Box of Kundun +4" />
    <Item Type="14" Index="11" Level="5" MaxCount="50" Name="Box of Kundun +5" />
</Items>
```

**Result**: Each box level has its own 50-item storage limit (multiplied by account tier).
{% endtab %}

{% tab title="VIP Benefits" %}

```xml
<AccountLimits>
    <Tier Level="0" Multiplier="1.0" />   <!-- 500 limit -->
    <Tier Level="1" Multiplier="1.5" />   <!-- 750 limit -->
    <Tier Level="2" Multiplier="2.0" />   <!-- 1000 limit -->
    <Tier Level="3" Multiplier="3.0" />   <!-- 1500 limit -->
    <Tier Level="4" Multiplier="5.0" />   <!-- 2500 limit -->
</AccountLimits>
<Items>
    <Item Type="14" Index="13" Level="*" MaxCount="500" Name="Jewel of Bless" />
</Items>
```

**Result**: VIP (AL4) players get 5x storage capacity, rewarding premium membership.
{% endtab %}
{% endtabs %}

## Common Issues

{% hint style="warning" %}
**Items Not Storable**: Verify the item is listed in the `<Items>` section. Only configured items can be stored.
{% endhint %}

{% hint style="warning" %}
**Capacity Exceeded**: Check the `MaxCount` for the item and the player's account level multiplier. Players may need to upgrade their account tier for more storage.
{% endhint %}

{% hint style="warning" %}
**Level Mismatch**: If using level-specific entries (`Level="0"`), items of other levels won't match. Use `Level="*"` to allow all levels.
{% endhint %}

{% hint style="danger" %}
**Jewel of Chaos Type**: Jewel of Chaos is **Type 12, Index 15**, not Type 14! Using the wrong type will prevent storage.
{% endhint %}

## DataServer Persistence

Jewel stacks, the auto-deposit preference, and the transaction log are all written through DataServer as part of account persistence. No manual table creation is required; schema migrations run automatically when the DataServer starts.