# 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

```
GameServer/Data/Plugins/JewelsBank/JewelsBank.xml
```

## Dependencies

| Depends On          | Purpose                                 |
| ------------------- | --------------------------------------- |
| DataServer          | Stores account bank data in database    |
| AccountLevel System | Determines storage capacity multipliers |

## 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 %}

## 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 5× storage capacity, rewarding premium membership.
{% endtab %}
{% endtabs %}

## Client Protocol

The Jewels Bank uses custom F3 subcode packets for client communication:

| Packet              | Direction | Subcode | Purpose                         |
| ------------------- | --------- | ------- | ------------------------------- |
| Open Request        | C→S       | 0x70    | Player opens bank               |
| Bank Data           | S→C       | 0x70    | Server sends bank contents      |
| Deposit Request     | C→S       | 0x71    | Player deposits items           |
| Withdraw Request    | C→S       | 0x72    | Player withdraws items          |
| Result              | S→C       | 0x73    | Transaction result notification |
| Auto-Deposit Toggle | C↔S       | 0x78    | Toggle auto-deposit setting     |

## 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 %}

## Database Tables

The DataServer requires these tables:

* `JewelsBank` - Stores item counts per account (row-per-item storage)
* `JewelsBankSettings` - Stores auto-deposit preference per account
* `JewelsBankLog` - Transaction history for auditing

{% hint style="info" %}
The main table is named `JewelsBank` (not `JewelsBankData`). Each row stores a specific ItemCode + ItemLevel combination for an account with its count.
{% endhint %}
