> For the complete documentation index, see [llms.txt](https://codingguru1968.gitbook.io/inventorystacks-wiki/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codingguru1968.gitbook.io/inventorystacks-wiki/configuration.md).

# ⚙️ Configuration

> 💡 Tip: After making changes to the configuration, remember to run `/stacks reload` in-game or via the console to apply your settings without a full server restart.

### 🌐 General Settings

* `check-for-updates`: (Default: `true`) Keeps the plugin up-to-date with the latest features and bug fixes.
* `debug-mode`: (Default: `false`) Enable only when troubleshooting issues.
* `use-mini-message`: (Default: `false`) Enable to use MiniMessage formatting for chat messages.
* `item-change-delay`: (Default: `2`) The update rate (in ticks) for buckets, drinkable items, and damageable items. *Note: This delay is highly recommended for Folia servers to ensure thread safety.*
* `use-permission`: (Default: `false`) If enabled, only players with the `STACKS.USE` permission can utilize custom stacking.

### 📦 Dropped Item Management

InventoryStacks can manage dropped item stacks and display information holograms.

```
item-hologram:
  enabled: false
  update-interval-ticks: 10
  show-despawn-timer: true
  ground-merge-max-amount: 64
  ground-merge-radius-blocks: 16
```

* Merging: Even if holograms are disabled, the plugin will merge nearby identical items on the ground up to your defined `ground-merge-max-amount`.
* Performance: A radius of 16 blocks is standard; be cautious with higher values on busy servers.

### 🚀 Modern Version Settings (1.20.5+)

These settings apply exclusively to modern Minecraft versions.

* `use-legacy-reflection`:
  * Disabled (Recommended): Uses native `ItemMeta` handling. Most stable, though more resource-intensive.
  * Enabled: Forces legacy reflection-based stack handling. Use as a fallback for compatibility. *Note: Container GUIs may still display visual limitations.*
* `auto-stack-cleanup`: (Default: `true`) Resets items not listed in your config to vanilla limits to ensure server stability.

### 🛡️ WorldGuard Integration

Control where stacking is allowed by enabling specific regions.

* `enabled`: Toggle WorldGuard support.
* `hopper-support`: (Default: `false`) Use with caution; can significantly increase server load.
* `enabled-regions`: List the specific region names where custom stacking should be active.

### 💎 Item Limits

This plugin offers two ways to define stack sizes: **Global Limits** (one size for everything) and **Custom Mapping** (specific sizes for specific items).

#### 1. Custom Item Mapping (Recommended)

This is where you define stack sizes for individual materials or predefined groups. This is the most common way to use the plugin.

```
items:
  TOTEM_OF_UNDYING: 16
  POTIONS: 16
  TOOLS: 1
```

* Materials: You can use any standard Minecraft material name.
* Predefined Groups: You can use built-in aliases like `BEDS`, `POTIONS`, `STEWS`, `TOOLS`, `ARMOR`, etc., to apply limits to entire categories of items at once.

#### 2. Global Limits (Advanced)

If you want a universal stack size for every item in the game, you can enable this section.

```
max-stack-for-all-items: 
  enabled: false
  amount: 99
  whitelist:
  - BED
```

> Important: How Rules Combine If `max-stack-for-all-items` is enabled, the plugin applies that global limit to everything except the items in your `whitelist`.
>
> If you have both the Global limit and specific entries in `items:` defined, the plugin applies the global limit first, then overrides it with your specific item mappings. Use the whitelist for items you want to exclude entirely from global rules.

### 📜 Legacy Compatibility (Pre-1.20.5 or Legacy Mode)

These settings handle edge cases for older versions or when `use-legacy-reflection` is active.

| **Setting**                                | **Description**                                            |
| ------------------------------------------ | ---------------------------------------------------------- |
| `disallow-stacked-anvil-items`             | Prevents stacked items from being used in anvils.          |
| `update-inventory-on-merge`                | Forces a client-side inventory update for cleaner visuals. |
| `prevent-shift-combining-damageable-items` | Prevents durability exploits.                              |
| `one-potion-per-slot`                      | Restricts brewing stands to one potion per slot.           |