> For the complete documentation index, see [llms.txt](https://thanhpahts-organization.gitbook.io/product-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://thanhpahts-organization.gitbook.io/product-docs/ultimate-storage/ii.-configuration.md).

# II. Configuration

## **Configuration File Structure**

| <p>plugins/UltimateStorage/</p><p>    config.yml</p><p>    messages.yml</p><p>    storage.yml</p><p>    dedication.yml</p><p>    database.db</p><p>   gui/</p><p>        categories.yml</p><p>        storage.yml</p><p>        item.yml</p><p>        dedication.yml</p><p></p> |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

### **1. config.yml**

| Key                              | Meaning                                                                           |
| -------------------------------- | --------------------------------------------------------------------------------- |
| economy.mode                     | VAULT or PLAYERPOINTS. Controls which economy provider is used.                   |
| storage.default-limit.mode       | ALL or CATEGORY. Controls whether base capacity is global or category-based.      |
| storage.default-limit.all        | Base capacity when default-limit mode is ALL.                                     |
| storage.default-limit.categories | Base capacity per category when default-limit mode is CATEGORY.                   |
| upgrade.mode                     | ALL or CATEGORY. Controls whether upgrade templates are global or category-based. |
| upgrade.all                      | Global upgrade levels with cost and limit.                                        |
| upgrade.categories               | Per-category upgrade levels with cost and limit.                                  |
| auto-storage.\*                  | Default auto storage states and ON/OFF labels.                                    |
| gui.open-sound                   | Sound played only when a GUI is opened.                                           |
| gui.click-sound                  | Fallback click sound when a GUI item does not define its own sound.               |
| notifications.\*                 | Default message mode and special mode for selected message keys.                  |
| database.save-interval-ticks     | Async save interval for dirty cached player data.                                 |

### **2. storage.yml**

The official sample contains 278 resources across 9 categories. A resource is matched primarily by the real dropped item material. If a player breaks, kills, fishes, or deposits an item whose material matches a configured resource, that amount can be stored.

```
  diamond:
    category: ore
    page: 0
    slot: 16
    display-name: "&bDiamond"
    material: DIAMOND
    amount-multiplier: 1
    sell-price: 100
```

| Field                    | Meaning                                                                  |
| ------------------------ | ------------------------------------------------------------------------ |
| category                 | Category ID used to place the resource under a category GUI.             |
| page                     | Storage page index, starting from 0.                                     |
| slot                     | GUI slot used by this resource on that page.                             |
| display-name             | Resource display name. Supports color codes.                             |
| material                 | Stored item material and primary real-drop match.                        |
| amount-multiplier        | Stored amount multiplier. Stored amount = real drop amount x multiplier. |
| sell-price               | Price per stored unit when selling.                                      |
| head / custom-model-data | Optional icon customization for resource display.                        |

### **3. GUI Files**

| File               | Controls                                                                               |
| ------------------ | -------------------------------------------------------------------------------------- |
| gui/categories.yml | Main category menu, global category auto toggle, category icons.                       |
| gui/storage.yml    | Resources inside a category, back button, pagination, category toggle, upgrade button. |
| gui/item.yml       | Per-resource management GUI: deposit, withdraw, sell, transfer, back.                  |
| gui/dedication.yml | Dedication input slots, confirm button, cancel button, filler, invalid sound.          |

### **4. Slot Ranges**

GUI items can use either a single slot or slot ranges. Button slots are rendered after filler items, so a button can override a filler slot when both use the same slot.

```
items:
  filler:
    material: BLACK_STAINED_GLASS_PANE
    name: " "
    slots:
      - 0-9
      - 17-18
      - 26-27
      - 35-39
      - 41-44
    sound:
      enabled: false
  close:
    material: BARRIER
    name: "&cClose"
    slot: 44
    action: CLOSE
    sound:
      enabled: true
      sound: BLOCK_CHEST_CLOSE
      volume: 0.8
      pitch: 1.0
```

### **5. Icons, Heads, And CustomModelData**

```
    material: PLAYER_HEAD
    head:
      type: BASE64 
      value: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvZWY0ZGJmNGQ5N2RhYjBjMjA0NTIwODE1YzZmNjUxNzNjOWU5MWZjNGJhNjBjNzcxZWE4NDkxNmI0OTY1ZTNiNCJ9fX0="
    name: "&cWithdraw"
    lore:
      - "&7Stored: &f%current%"
```

### **6. Messages And Notifications**

messages.yml controls all player-facing text and prefix behavior. config.yml controls whether normal messages use CHAT, ACTIONBAR, or TITLE modes, and which keys use the configurable mode.

| Message Config                      | Meaning                                                 |
| ----------------------------------- | ------------------------------------------------------- |
| prefix.enabled                      | Enables or disables the shared message prefix.          |
| prefix.text                         | Prefix text shown before chat messages.                 |
| prefix.modes.chat/actionbar/title   | Controls which notification modes receive the prefix.   |
| prefix.excluded-keys                | Message keys that should not receive the prefix.        |
| notifications.default-mode          | Default delivery mode for normal messages.              |
| notifications.configurable-mode     | Delivery mode for keys listed in configurable-messages. |
| notifications.configurable-messages | Message keys that should use configurable-mode.         |