⭐️ClothesPlus⭐️ v3.0.4

# ClothesPlus v3.0.4 — Changelog

**Release Date:** March 21, 2026  
**Minecraft Support:** 1.20.x – 1.21.10+  
**PacketEvents:** 2.11.3

---

## ✨ New Features

### 🆕 Wardrobe Category Pagination (Multi-Page Categories)
The wardrobe categories menu now supports **multiple pages**, allowing servers with many overlay categories to spread them across separate pages with individual titles.

**How it works:**
- Each category in `guis.yml` can optionally specify `page: <number>` (defaults to `1` if omitted)
- A new `wardrobe.pages` section defines per-page titles
- **Prev / Next** navigation buttons appear automatically when more than one page exists
- Clicking "Back" from an overlay menu returns the player to the **same page** they were on
- Fully backward-compatible — existing configs without `page` or `pages` work identically to before

**Configuration (`guis.yml`):**
```yaml
wardrobe:
  # Per-page title overrides
  pages:
    1:
      title: "&6&lWardrobe - Categories"
    2:
      title: "&6&lWardrobe - More Categories"

  categories:
    shirts:
      page: 1                              # appears on page 1
      slots: [0, 1, 2, 9, 10, 11]
      # ...existing item/overlay-icons...
    eyes:
      page: 2                              # appears on page 2
      slots: [0, 1, 2, 9, 10, 11]
      # ...
```

**Details:**
- Pages can have unlimited categories, each with their own slot positions
- The `Prev` / `Next` buttons use the existing disabled material variants on boundary pages
- The `Exit` button in the navigation bar now properly closes the inventory
- Page state is cleaned up on player quit to prevent memory leaks
- Running `/clothes reload` hot-reloads page definitions without a restart

---

### 🆕 Auto-Migration of guis.yml for Existing Servers
Servers upgrading from v3.0.3 or earlier no longer need to manually edit `guis.yml`. On startup, the plugin automatically:

1. **Injects the `pages` section** after `wardrobe.titles` if missing — includes default page 1 title and a commented-out page 2 example
2. **Adds `page: 1`** to every existing category that lacks a `page` property

All injections preserve existing formatting, comments, and custom values. A log message confirms each migration step.

---

### 🆕 Exit Button Now Functional in Wardrobe
The `exit` button defined in `wardrobe.navigation` was previously configured but non-functional. It now properly closes the inventory when clicked.

---

## 📋 Technical Notes

- **Minimum Java Version:** 21
- **API Version:** 1.21+
- **Folia Support:** ✅ Yes
- All changes are fully backwards-compatible with existing configs
- The `page` property defaults to `1` — no config changes required for single-page setups

---

*Thank you for using ClothesPlus! Report issues on our support channel.*

---
---

# ClothesPlus v3.0.3 — Patch Changelog

**Release Date:** March 19, 2026  
**Minecraft Support:** 1.20.x – 1.21.10+  
**PacketEvents:** 2.11.3

---

## 🐛 Bug Fixes

### 🔧 Scale/Height Section Not Showing Options Until Manual Refresh
The scale/height section in the character creator would appear as if no options were available. Players had to manually save `cursor_creator.yml` and run `/clothes cursor refresh` for scale options to actually appear.

**Root Cause:** The scale section and its configuration were not being auto-injected into existing user configs on plugin load. Users who updated the plugin without manually copying the new scale section from the default config would see an empty section.

**Fix:** The scale section (with default height presets) is now **automatically injected** into `cursor_creator.yml` on startup if missing. This happens before the YAML is parsed, so it works immediately — no manual save/refresh needed. The injection also adds a scale button to the main menu if one isn't present.

---

### 🔧 Scale Value Not Written When Saving Config via Regenerate
When using `/clothes cursor regenerate` or any config save operation, the `scale-value` field for cycle options was silently dropped. This meant regenerated configs would lose all scale preset values.

**Fix:** The `writeSectionToConfig` method now properly serializes `scale-value` for cycle options alongside all other properties.

---

## ✨ New Features

### 🆕 Scale System Enable/Disable Toggle
A new `scale-system-enabled` option has been added to `cursor_creator.yml`, allowing server admins to completely enable or disable the height/scale feature.

```yaml
# Enable scale/height system (uses Minecraft 1.20.5+ generic.scale attribute)
# When true: Height button shows on main menu, players can adjust their character height
# When false: Height button hidden, scale selection unavailable
# NOTE: Requires Minecraft 1.20.5+ for the attribute to actually work
scale-system-enabled: true
```

**When disabled (`false`):**
- The 📏 Height button is hidden from the main creator menu
- The scale section cannot be opened
- Scale is not applied to players or NPCs

---

### 🆕 Auto-Injection of Scale Section for Existing Configs
Users upgrading from older versions no longer need to manually copy the scale section into their `cursor_creator.yml`. On every load/reload, the plugin checks for:

1. **`scale-system-enabled`** — Injected after `class-system-enabled` if missing
2. **`scale` section** under `sections:` — Full default scale section with 5 height presets (Tiny, Short, Normal, Tall, Giant) injected if missing
3. **`scale` button** in the main menu — Height button auto-added before the exit button if missing

All injections preserve existing formatting and comments.

---

## 📋 Technical Notes

- **Minimum Java Version:** 21
- **API Version:** 1.18+
- **Folia Support:** ✅ Yes
- All changes are fully backwards-compatible with existing configs

---

*Thank you for using ClothesPlus! Report issues on our support channel.*

---
---

# ClothesPlus v3.0.2 — Changelog

**Release Date:** March 18, 2026  
**Minecraft Support:** 1.20.x – 1.21.10+  
**PacketEvents:** 2.11.3

---

## 🐛 Bug Fixes

### 🔧 Cursor System Lag/Freeze on 1.21.2 – 1.21.9 (Critical Fix)
The cursor in `/wardrobe` (cursor mode) and `/outfits` previewer would freeze on servers running **Minecraft 1.21.2 – 1.21.9**. The cursor item would only jump to the correct position when the player pressed Shift, then freeze again.

**Root Cause:** On MC 1.21.2-1.21.9, the combination of mounting the player on a pig AND repeatedly sending `WrapperPlayServerCamera` packets pointing at that pig **every tick** causes the Minecraft client to suppress `PLAYER_ROTATION` packets. Without rotation data, the cursor position cannot be calculated.

**Fix (3 layers):**
1. **Throttled camera packet resends** — Camera packets are now sent only on mount/remount and every 20 ticks (1s) instead of every tick. This prevents the client from suppressing PLAYER_ROTATION packets.
2. **PLAYER_INPUT rotation sync** — On 1.21.2+, `PLAYER_INPUT` packets are sent by the client as a heartbeat. When no recent PLAYER_ROTATION packet has been received, we use PLAYER_INPUT as a trigger to force-sync rotation from Bukkit's `player.getLocation()`.
3. **Faster Bukkit fallback** — Reduced the Bukkit location rotation fallback threshold from 500ms to 100ms (~2 ticks), so the cursor recovers almost immediately when packet-based tracking fails.
4. **Added VehicleExitEvent handler** for the Previewer system to prevent pig dismounting via Bukkit API (was already present in Cursor system but missing from Previewer).

**Affected systems:** Cursor menu, Previewer (/wardrobe, /outfits)

---

### 🔧 Multiverse-Core Compatibility — Cursor Not Spawning in Mob-Disabled Worlds
On servers using **Multiverse-Core** with animal/mob spawning disabled per-world, the cursor system would fail to start. The cursor item wouldn't appear, and the previewer would get stuck.

**Root Cause:** ClothesPlus spawns a `Pig` (invisible camera mount) and an `ArmorStand` (cursor marker) as part of the cursor/previewer system. When Multiverse-Core disables mob spawning in a world, it cancels the `CreatureSpawnEvent` for these entities — preventing them from ever being created.

**Fix:** A new **entity spawn protection** system tags all ClothesPlus-spawned entities via `PersistentDataContainer` at spawn time. A `CreatureSpawnEvent` listener at `HIGHEST` priority detects tagged entities that were cancelled by other plugins and un-cancels them. This ensures ClothesPlus entities always spawn, **without affecting general mob spawning rules** set by Multiverse-Core or similar plugins.

**Affected systems:** Cursor menu, Previewer (/wardrobe, /outfits)  
**Compatibility:** Works with Multiverse-Core, Multiverse-Inventories, and any plugin that cancels `CreatureSpawnEvent`

---

### 🔧 GUI Buttons Not Working on 1.21.4 (Critical Fix)
The `/wardrobe` and overlay selection menus were completely unresponsive on servers running **Minecraft 1.21+**. Clicking any button — categories, overlays, pagination, outfits — did nothing.

**Cause:** Paper 1.21 changed `InventoryView` from an abstract class to an interface. Any plugin compiled against the older API that calls `getView().getTitle()` directly would crash with a `NoSuchMethodError` at runtime, silently breaking all inventory click handling.

**Fix:** All GUI title checks now use a new reflection-based compatibility layer (`CompatInventory.getTitle()`) that works seamlessly on both 1.20.x and 1.21.4+ servers.

**Affected menus:** Wardrobe categories, overlay selection, pagination (prev/next), outfit manager, search

---

### 🔧 NPC Preview Not Reacting to Clicks
Left-clicking and right-clicking the NPC in `/npcpreview` was not triggering spin toggles on 1.21.4.

**Cause:** The packet listener was incorrectly grouping all interaction types together and only processing `ATTACK` actions. Right-click interactions (`INTERACT` / `INTERACT_AT`) were never handled.

**Fix:** The NPC packet listener now properly separates:
- **Left-click on NPC** → Toggle counter-clockwise spin
- **Right-click on NPC** → Toggle clockwise spin
- **Left-click in air** → Toggle counter-clockwise spin
- **F key (swap hand)** → Zoom in / out

---

### 🔧 Outfit Loading Reverts to Default Skin
When using `/outfit` to save an outfit and then clicking it to load, the player's skin would briefly show the outfit and then snap back to their original Mojang skin.

**Cause:** The outfit loader called `resetPlayerSkins()` before applying overlays, which triggers an async HTTP request to the Mojang session server. This request would complete *after* the outfit overlays were already applied, overwriting them with the vanilla skin.

**Fix:** Outfit loading no longer calls the Mojang API reset. Instead, it clears the current overlay list in-memory and applies the saved outfit overlays directly — no race condition, no flickering.

---

### 🔧 PacketEvents Updated to 2.11.3
Upgraded the PacketEvents dependency from **2.11.1** to **2.11.3**, bringing:
- Full 1.21.4 protocol support
- NPC team name uniqueness fixes
- Entity spawn packet improvements
- Registry synchronization fixes

---

## ✨ New Features

### 🆕 Player Scale / Height Selection (1.20.5+)
Players can now adjust their character's **height** in the character creator. A new **📏 Height** category appears in the main menu, allowing players to cycle through configurable scale options.

**How it works:**
- Each click on Previous/Next cycles through scale presets (e.g., Tiny → Short → Normal → Tall → Giant)
- Scale is applied instantly to the player using the `generic.scale` attribute
- The **NPC preview reflects the selected scale in real-time** — the NPC visually grows or shrinks
- Scale persists across sessions and server restarts (saved in character data JSON)
- Scale is re-applied automatically on player join

**Configuration (`cursor_creator.yml`):**
```yaml
sections:
  scale:
    title: <gradient:#32CD32:#228B22>━━ 📏 Height ━━</gradient>
    cycle-enabled: true
    show-navigation: true
    cycle-options:
      - id: scale_tiny
        display: <gray>Tiny
        scale-value: 0.5
      - id: scale_normal
        display: <green>Normal
        scale-value: 1.0
      - id: scale_tall
        display: <aqua>Tall
        scale-value: 1.2
      # Add as many options as you want!
```

**Details:**
- The `scale-value` field accepts any double from `0.0625` (1/16th) to `16.0` (16× size)
- Reasonable values for roleplay are `0.5` – `2.0`
- Requires **Minecraft 1.20.5+** for the `generic.scale` attribute; on older servers the section appears but scale won't visually apply
- NPC preview scale works in all three systems: Character Creator, Previewer (`/outfits`), and NPC Preview (`/npcpreview`)

---

### 🆕 `/npcpreview <playername>` — Preview Another Player's Skin
You can now preview any online player's current appearance by specifying their name.

**Usage:**
```
/npcpreview              — Preview your own skin (existing behavior)
/npcpreview Steve        — Preview Steve's current skin/outfit
```

**Details:**
- Tab-completion for online player names
- Requires `wardrobeclothes.npcpreview.other` permission (or `wardrobeclothes.admin`)
- The NPC shows the target player's current skin including any active overlays
- All existing controls work (spin, zoom, toggle stop)

---

### 🆕 PlaceholderAPI Integration
ClothesPlus now registers a full **PlaceholderAPI expansion** that exposes skin and overlay data to any plugin that supports PAPI.

**Available Placeholders:**

| Placeholder | Description |
|---|---|
| `%clothesplus_skin_texture%` | Current skin texture value (Base64) |
| `%clothesplus_skin_signature%` | Current skin signature value |
| `%clothesplus_overlays%` | Comma-separated list of currently worn overlays (or `none`) |
| `%clothesplus_overlay_count%` | Number of currently worn overlays |
| `%clothesplus_has_overlay_<path>%` | Whether the player is wearing a specific overlay (`true`/`false`) |
| `%clothesplus_model%` | Player's skin model type (`steve`/`alex`) |

**Example:** `%clothesplus_has_overlay_hairs/wizard_hat%` → `true` if the player has that overlay equipped.

**Use Cases:**
- Display outfit info on scoreboards, tab lists, or holograms
- Save/restore skin states via external plugins
- Conditional logic in DeluxeMenus, ConditionalEvents, etc.

*Requires PlaceholderAPI to be installed (soft dependency).*

---

### 🆕 Item Model Component Support (1.21.4+)
ClothesPlus now supports Minecraft's **`item_model` component** alongside traditional Custom Model Data.

Since Minecraft 1.21.4, `item_model` is the preferred way to specify custom item appearances. It offers better organization, namespace support, and is more flexible than integer-based Custom Model Data.

**How to use in config:**
```yaml
# Works on 1.21.4+ (takes priority when supported):
item-model: "mynamespace:custom_shirt_icon"

# Fallback for servers running 1.20.x – 1.21.3:
custom-model-data: 1234
```

Both keys can coexist — the plugin automatically detects server capability and uses the appropriate one.

**Supported in:**
- Wardrobe category icons
- Overlay item icons (available / equipped / locked / unequip)
- Navigation buttons (prev / next / outfits / back / search)
- Outfit GUI items and control buttons
- Previewer cursor displays
- All per-category icon overrides

---

## 📋 Technical Notes

- **Minimum Java Version:** 21
- **API Version:** 1.18+
- **Folia Support:** ✅ Yes
- **Tested on:** Paper 1.21.4, Paper 1.20.4
- All changes are fully backwards-compatible with 1.20.x servers

---

## 📦 Dependency Changes

| Dependency | Old Version | New Version |
|---|---|---|
| PacketEvents (Spigot) | 2.11.1 | 2.11.3-SNAPSHOT |

---

*Thank you for using ClothesPlus! Report issues on our support channel.*

# ClothesPlus v3.0.3 — Patch Changelog

**Release Date:** March 19, 2026  
**Minecraft Support:** 1.20.x – 1.21.10+  
**PacketEvents:** 2.11.3

---

## 🐛 Bug Fixes

### 🔧 Scale/Height Section Not Showing Options Until Manual Refresh
The scale/height section in the character creator would appear as if no options were available. Players had to manually save `cursor_creator.yml` and run `/clothes cursor refresh` for scale options to actually appear.

**Root Cause:** The scale section and its configuration were not being auto-injected into existing user configs on plugin load. Users who updated the plugin without manually copying the new scale section from the default config would see an empty section.

**Fix:** The scale section (with default height presets) is now **automatically injected** into `cursor_creator.yml` on startup if missing. This happens before the YAML is parsed, so it works immediately — no manual save/refresh needed. The injection also adds a scale button to the main menu if one isn't present.

---

### 🔧 Scale Value Not Written When Saving Config via Regenerate
When using `/clothes cursor regenerate` or any config save operation, the `scale-value` field for cycle options was silently dropped. This meant regenerated configs would lose all scale preset values.

**Fix:** The `writeSectionToConfig` method now properly serializes `scale-value` for cycle options alongside all other properties.

---

## ✨ New Features

### 🆕 Scale System Enable/Disable Toggle
A new `scale-system-enabled` option has been added to `cursor_creator.yml`, allowing server admins to completely enable or disable the height/scale feature.

```yaml
# Enable scale/height system (uses Minecraft 1.20.5+ generic.scale attribute)
# When true: Height button shows on main menu, players can adjust their character height
# When false: Height button hidden, scale selection unavailable
# NOTE: Requires Minecraft 1.20.5+ for the attribute to actually work
scale-system-enabled: true
```

**When disabled (`false`):**
- The 📏 Height button is hidden from the main creator menu
- The scale section cannot be opened
- Scale is not applied to players or NPCs

---

### 🆕 Auto-Injection of Scale Section for Existing Configs
Users upgrading from older versions no longer need to manually copy the scale section into their `cursor_creator.yml`. On every load/reload, the plugin checks for:

1. **`scale-system-enabled`** — Injected after `class-system-enabled` if missing
2. **`scale` section** under `sections:` — Full default scale section with 5 height presets (Tiny, Short, Normal, Tall, Giant) injected if missing
3. **`scale` button** in the main menu — Height button auto-added before the exit button if missing

All injections preserve existing formatting and comments.

---

## 📋 Technical Notes

- **Minimum Java Version:** 21
- **API Version:** 1.18+
- **Folia Support:** ✅ Yes
- All changes are fully backwards-compatible with existing configs

---

*Thank you for using ClothesPlus! Report issues on our support channel.*

---
---

# ClothesPlus v3.0.2 — Changelog

**Release Date:** March 18, 2026  
**Minecraft Support:** 1.20.x – 1.21.10+  
**PacketEvents:** 2.11.3

---

## 🐛 Bug Fixes

### 🔧 Cursor System Lag/Freeze on 1.21.2 – 1.21.9 (Critical Fix)
The cursor in `/wardrobe` (cursor mode) and `/outfits` previewer would freeze on servers running **Minecraft 1.21.2 – 1.21.9**. The cursor item would only jump to the correct position when the player pressed Shift, then freeze again.

**Root Cause:** On MC 1.21.2-1.21.9, the combination of mounting the player on a pig AND repeatedly sending `WrapperPlayServerCamera` packets pointing at that pig **every tick** causes the Minecraft client to suppress `PLAYER_ROTATION` packets. Without rotation data, the cursor position cannot be calculated.

**Fix (3 layers):**
1. **Throttled camera packet resends** — Camera packets are now sent only on mount/remount and every 20 ticks (1s) instead of every tick. This prevents the client from suppressing PLAYER_ROTATION packets.
2. **PLAYER_INPUT rotation sync** — On 1.21.2+, `PLAYER_INPUT` packets are sent by the client as a heartbeat. When no recent PLAYER_ROTATION packet has been received, we use PLAYER_INPUT as a trigger to force-sync rotation from Bukkit's `player.getLocation()`.
3. **Faster Bukkit fallback** — Reduced the Bukkit location rotation fallback threshold from 500ms to 100ms (~2 ticks), so the cursor recovers almost immediately when packet-based tracking fails.
4. **Added VehicleExitEvent handler** for the Previewer system to prevent pig dismounting via Bukkit API (was already present in Cursor system but missing from Previewer).

**Affected systems:** Cursor menu, Previewer (/wardrobe, /outfits)

---

### 🔧 Multiverse-Core Compatibility — Cursor Not Spawning in Mob-Disabled Worlds
On servers using **Multiverse-Core** with animal/mob spawning disabled per-world, the cursor system would fail to start. The cursor item wouldn't appear, and the previewer would get stuck.

**Root Cause:** ClothesPlus spawns a `Pig` (invisible camera mount) and an `ArmorStand` (cursor marker) as part of the cursor/previewer system. When Multiverse-Core disables mob spawning in a world, it cancels the `CreatureSpawnEvent` for these entities — preventing them from ever being created.

**Fix:** A new **entity spawn protection** system tags all ClothesPlus-spawned entities via `PersistentDataContainer` at spawn time. A `CreatureSpawnEvent` listener at `HIGHEST` priority detects tagged entities that were cancelled by other plugins and un-cancels them. This ensures ClothesPlus entities always spawn, **without affecting general mob spawning rules** set by Multiverse-Core or similar plugins.

**Affected systems:** Cursor menu, Previewer (/wardrobe, /outfits)  
**Compatibility:** Works with Multiverse-Core, Multiverse-Inventories, and any plugin that cancels `CreatureSpawnEvent`

---

### 🔧 GUI Buttons Not Working on 1.21.4 (Critical Fix)
The `/wardrobe` and overlay selection menus were completely unresponsive on servers running **Minecraft 1.21+**. Clicking any button — categories, overlays, pagination, outfits — did nothing.

**Cause:** Paper 1.21 changed `InventoryView` from an abstract class to an interface. Any plugin compiled against the older API that calls `getView().getTitle()` directly would crash with a `NoSuchMethodError` at runtime, silently breaking all inventory click handling.

**Fix:** All GUI title checks now use a new reflection-based compatibility layer (`CompatInventory.getTitle()`) that works seamlessly on both 1.20.x and 1.21.4+ servers.

**Affected menus:** Wardrobe categories, overlay selection, pagination (prev/next), outfit manager, search

---

### 🔧 NPC Preview Not Reacting to Clicks
Left-clicking and right-clicking the NPC in `/npcpreview` was not triggering spin toggles on 1.21.4.

**Cause:** The packet listener was incorrectly grouping all interaction types together and only processing `ATTACK` actions. Right-click interactions (`INTERACT` / `INTERACT_AT`) were never handled.

**Fix:** The NPC packet listener now properly separates:
- **Left-click on NPC** → Toggle counter-clockwise spin
- **Right-click on NPC** → Toggle clockwise spin
- **Left-click in air** → Toggle counter-clockwise spin
- **F key (swap hand)** → Zoom in / out

---

### 🔧 Outfit Loading Reverts to Default Skin
When using `/outfit` to save an outfit and then clicking it to load, the player's skin would briefly show the outfit and then snap back to their original Mojang skin.

**Cause:** The outfit loader called `resetPlayerSkins()` before applying overlays, which triggers an async HTTP request to the Mojang session server. This request would complete *after* the outfit overlays were already applied, overwriting them with the vanilla skin.

**Fix:** Outfit loading no longer calls the Mojang API reset. Instead, it clears the current overlay list in-memory and applies the saved outfit overlays directly — no race condition, no flickering.

---

### 🔧 PacketEvents Updated to 2.11.3
Upgraded the PacketEvents dependency from **2.11.1** to **2.11.3**, bringing:
- Full 1.21.4 protocol support
- NPC team name uniqueness fixes
- Entity spawn packet improvements
- Registry synchronization fixes

---

## ✨ New Features

### 🆕 Player Scale / Height Selection (1.20.5+)
Players can now adjust their character's **height** in the character creator. A new **📏 Height** category appears in the main menu, allowing players to cycle through configurable scale options.

**How it works:**
- Each click on Previous/Next cycles through scale presets (e.g., Tiny → Short → Normal → Tall → Giant)
- Scale is applied instantly to the player using the `generic.scale` attribute
- The **NPC preview reflects the selected scale in real-time** — the NPC visually grows or shrinks
- Scale persists across sessions and server restarts (saved in character data JSON)
- Scale is re-applied automatically on player join

**Configuration (`cursor_creator.yml`):**
```yaml
sections:
  scale:
    title: <gradient:#32CD32:#228B22>━━ 📏 Height ━━</gradient>
    cycle-enabled: true
    show-navigation: true
    cycle-options:
      - id: scale_tiny
        display: <gray>Tiny
        scale-value: 0.5
      - id: scale_normal
        display: <green>Normal
        scale-value: 1.0
      - id: scale_tall
        display: <aqua>Tall
        scale-value: 1.2
      # Add as many options as you want!
```

**Details:**
- The `scale-value` field accepts any double from `0.0625` (1/16th) to `16.0` (16× size)
- Reasonable values for roleplay are `0.5` – `2.0`
- Requires **Minecraft 1.20.5+** for the `generic.scale` attribute; on older servers the section appears but scale won't visually apply
- NPC preview scale works in all three systems: Character Creator, Previewer (`/outfits`), and NPC Preview (`/npcpreview`)

---

### 🆕 `/npcpreview <playername>` — Preview Another Player's Skin
You can now preview any online player's current appearance by specifying their name.

**Usage:**
```
/npcpreview              — Preview your own skin (existing behavior)
/npcpreview Steve        — Preview Steve's current skin/outfit
```

**Details:**
- Tab-completion for online player names
- Requires `wardrobeclothes.npcpreview.other` permission (or `wardrobeclothes.admin`)
- The NPC shows the target player's current skin including any active overlays
- All existing controls work (spin, zoom, toggle stop)

---

### 🆕 PlaceholderAPI Integration
ClothesPlus now registers a full **PlaceholderAPI expansion** that exposes skin and overlay data to any plugin that supports PAPI.

1.
**Use Cases:**
- Display outfit info on scoreboards, tab lists, or holograms
- Save/restore skin states via external plugins
- Conditional logic in DeluxeMenus, ConditionalEvents, etc.

*Requires PlaceholderAPI to be installed (soft dependency).*

---

### 🆕 Item Model Component Support (1.21.4+)
ClothesPlus now supports Minecraft's **`item_model` component** alongside traditional Custom Model Data.

Since Minecraft 1.21.4, `item_model` is the preferred way to specify custom item appearances. It offers better organization, namespace support, and is more flexible than integer-based Custom Model Data.

**How to use in config:**
```yaml
# Works on 1.21.4+ (takes priority when supported):
item-model: "mynamespace:custom_shirt_icon"

# Fallback for servers running 1.20.x – 1.21.3:
custom-model-data: 1234
```

Both keys can coexist — the plugin automatically detects server capability and uses the appropriate one.

**Supported in:**
- Wardrobe category icons
- Overlay item icons (available / equipped / locked / unequip)
- Navigation buttons (prev / next / outfits / back / search)
- Outfit GUI items and control buttons
- Previewer cursor displays
- All per-category icon overrides

---

## 📋 Technical Notes

- **Minimum Java Version:** 21
- **API Version:** 1.18+
- **Folia Support:** ✅ Yes
- **Tested on:** Paper 1.21.4, Paper 1.20.4
- All changes are fully backwards-compatible with 1.20.x servers

---

## 📦 Dependency Changes

| Dependency | Old Version | New Version |
|---|---|---|
| PacketEvents (Spigot) | 2.11.1 | 2.11.3-SNAPSHOT |

---

*Thank you for using ClothesPlus! Report issues on our support channel.*

# ClothesPlus v3.0.2 — Changelog

**Release Date:** March 18, 2026  
**Minecraft Support:** 1.20.x – 1.21.10+  
**PacketEvents:** 2.11.3

---

## 🐛 Bug Fixes

### 🔧 Cursor System Lag/Freeze on 1.21.2 – 1.21.9 (Critical Fix)
The cursor in `/wardrobe` (cursor mode) and `/outfits` previewer would freeze on servers running **Minecraft 1.21.2 – 1.21.9**. The cursor item would only jump to the correct position when the player pressed Shift, then freeze again.

**Root Cause:** On MC 1.21.2-1.21.9, the combination of mounting the player on a pig AND repeatedly sending `WrapperPlayServerCamera` packets pointing at that pig **every tick** causes the Minecraft client to suppress `PLAYER_ROTATION` packets. Without rotation data, the cursor position cannot be calculated.

**Fix (3 layers):**
1. **Throttled camera packet resends** — Camera packets are now sent only on mount/remount and every 20 ticks (1s) instead of every tick. This prevents the client from suppressing PLAYER_ROTATION packets.
2. **PLAYER_INPUT rotation sync** — On 1.21.2+, `PLAYER_INPUT` packets are sent by the client as a heartbeat. When no recent PLAYER_ROTATION packet has been received, we use PLAYER_INPUT as a trigger to force-sync rotation from Bukkit's `player.getLocation()`.
3. **Faster Bukkit fallback** — Reduced the Bukkit location rotation fallback threshold from 500ms to 100ms (~2 ticks), so the cursor recovers almost immediately when packet-based tracking fails.
4. **Added VehicleExitEvent handler** for the Previewer system to prevent pig dismounting via Bukkit API (was already present in Cursor system but missing from Previewer).

**Affected systems:** Cursor menu, Previewer (/wardrobe, /outfits)

---

### 🔧 Multiverse-Core Compatibility — Cursor Not Spawning in Mob-Disabled Worlds
On servers using **Multiverse-Core** with animal/mob spawning disabled per-world, the cursor system would fail to start. The cursor item wouldn't appear, and the previewer would get stuck.

**Root Cause:** ClothesPlus spawns a `Pig` (invisible camera mount) and an `ArmorStand` (cursor marker) as part of the cursor/previewer system. When Multiverse-Core disables mob spawning in a world, it cancels the `CreatureSpawnEvent` for these entities — preventing them from ever being created.

**Fix:** A new **entity spawn protection** system tags all ClothesPlus-spawned entities via `PersistentDataContainer` at spawn time. A `CreatureSpawnEvent` listener at `HIGHEST` priority detects tagged entities that were cancelled by other plugins and un-cancels them. This ensures ClothesPlus entities always spawn, **without affecting general mob spawning rules** set by Multiverse-Core or similar plugins.

**Affected systems:** Cursor menu, Previewer (/wardrobe, /outfits)  
**Compatibility:** Works with Multiverse-Core, Multiverse-Inventories, and any plugin that cancels `CreatureSpawnEvent`

---

### 🔧 GUI Buttons Not Working on 1.21.4 (Critical Fix)
The `/wardrobe` and overlay selection menus were completely unresponsive on servers running **Minecraft 1.21+**. Clicking any button — categories, overlays, pagination, outfits — did nothing.

**Cause:** Paper 1.21 changed `InventoryView` from an abstract class to an interface. Any plugin compiled against the older API that calls `getView().getTitle()` directly would crash with a `NoSuchMethodError` at runtime, silently breaking all inventory click handling.

**Fix:** All GUI title checks now use a new reflection-based compatibility layer (`CompatInventory.getTitle()`) that works seamlessly on both 1.20.x and 1.21.4+ servers.

**Affected menus:** Wardrobe categories, overlay selection, pagination (prev/next), outfit manager, search

---

### 🔧 NPC Preview Not Reacting to Clicks
Left-clicking and right-clicking the NPC in `/npcpreview` was not triggering spin toggles on 1.21.4.

**Cause:** The packet listener was incorrectly grouping all interaction types together and only processing `ATTACK` actions. Right-click interactions (`INTERACT` / `INTERACT_AT`) were never handled.

**Fix:** The NPC packet listener now properly separates:
- **Left-click on NPC** → Toggle counter-clockwise spin
- **Right-click on NPC** → Toggle clockwise spin
- **Left-click in air** → Toggle counter-clockwise spin
- **F key (swap hand)** → Zoom in / out

---

### 🔧 Outfit Loading Reverts to Default Skin
When using `/outfit` to save an outfit and then clicking it to load, the player's skin would briefly show the outfit and then snap back to their original Mojang skin.

**Cause:** The outfit loader called `resetPlayerSkins()` before applying overlays, which triggers an async HTTP request to the Mojang session server. This request would complete *after* the outfit overlays were already applied, overwriting them with the vanilla skin.

**Fix:** Outfit loading no longer calls the Mojang API reset. Instead, it clears the current overlay list in-memory and applies the saved outfit overlays directly — no race condition, no flickering.

---

### 🔧 PacketEvents Updated to 2.11.3
Upgraded the PacketEvents dependency from **2.11.1** to **2.11.3**, bringing:
- Full 1.21.4 protocol support
- NPC team name uniqueness fixes
- Entity spawn packet improvements
- Registry synchronization fixes

---

## ✨ New Features

### 🆕 `/npcpreview <playername>` — Preview Another Player's Skin
You can now preview any online player's current appearance by specifying their name.

**Usage:**
```
/npcpreview              — Preview your own skin (existing behavior)
/npcpreview Steve        — Preview Steve's current skin/outfit
```

**Details:**
- Tab-completion for online player names
- Requires `wardrobeclothes.npcpreview.other` permission (or `wardrobeclothes.admin`)
- The NPC shows the target player's current skin including any active overlays
- All existing controls work (spin, zoom, toggle stop)

---

### 🆕 PlaceholderAPI Integration
ClothesPlus now registers a full **PlaceholderAPI expansion** that exposes skin and overlay data to any plugin that supports PAPI.

1.
**Use Cases:**
- Display outfit info on scoreboards, tab lists, or holograms
- Save/restore skin states via external plugins
- Conditional logic in DeluxeMenus, ConditionalEvents, etc.

*Requires PlaceholderAPI to be installed (soft dependency).*

---

### 🆕 Item Model Component Support (1.21.4+)
ClothesPlus now supports Minecraft's **`item_model` component** alongside traditional Custom Model Data.

Since Minecraft 1.21.4, `item_model` is the preferred way to specify custom item appearances. It offers better organization, namespace support, and is more flexible than integer-based Custom Model Data.

**How to use in config:**
```yaml
# Works on 1.21.4+ (takes priority when supported):
item-model: "mynamespace:custom_shirt_icon"

# Fallback for servers running 1.20.x – 1.21.3:
custom-model-data: 1234
```

Both keys can coexist — the plugin automatically detects server capability and uses the appropriate one.

**Supported in:**
- Wardrobe category icons
- Overlay item icons (available / equipped / locked / unequip)
- Navigation buttons (prev / next / outfits / back / search)
- Outfit GUI items and control buttons
- Previewer cursor displays
- All per-category icon overrides

---

## 📋 Technical Notes

- **Minimum Java Version:** 21
- **API Version:** 1.18+
- **Folia Support:** ✅ Yes
- **Tested on:** Paper 1.21.4, Paper 1.20.4
- All changes are fully backwards-compatible with 1.20.x servers

---

## 📦 Dependency Changes

| Dependency | Old Version | New Version |
|---|---|---|
| PacketEvents (Spigot) | 2.11.1 | 2.11.3-SNAPSHOT |

---

*Thank you for using ClothesPlus! Report issues on our support channel.*

Small update:
- Fixed PacketEvents UUID system not being read correctly