Modernize XMas Tree for Paper 26.1.2 / Java 25

- move the project from the legacy deployed build to an actively maintained Paper 26.1.2 / Java 25 Gradle build
- simplify the build around the active Paper 26.1.2 target and remove the retired 1.21.11 local server dependency
- keep build output clean and predictable in build/libs with the new 2026 versioned jar naming

- keep legacy tree data compatible by continuing to read plugins/X-Mas/trees.yml
- add world alias migration support so old saved trees can survive renamed worlds
- preserve old event data while modernizing the runtime and admin tooling

- make /xmastree the primary command
- keep /xmas as an optional legacy alias controlled by config
- fix legacy alias reload/unregister behavior so reload no longer crashes when alias settings change
- improve /xmastree help output and keep it aligned with the actual command surface

- add granular permissions under onembxmastree.*
- replace the old xmas.admin permission with onembxmastree.admin
- add separate permissions for status, help, give, gifts, addhand, reload, debug, debug.toggle, end, and tree.override

- add a modern debug system with named categories:
  status, commands, permissions, placeholders, and config
- keep numeric debug pages working as a legacy shortcut
- improve debug output formatting with clearer key/value coloring
- make invalid debug page/section requests return a helpful response instead of silently falling back
- add /xmastree debug toggle <key> true|false for live boolean config changes
- keep tab completion focused on named debug categories instead of numeric page suggestions

- add optional PlaceholderAPI support with the onembxmastree namespace
- add placeholders for event state, end time, end countdown, auto-end, resource-back, particles, luck, tree totals, owner totals, player tree count, and plugin version
- document placeholders in the README and show them in debug output

- modernize message handling with MiniMessage support while keeping legacy color compatibility
- improve player-facing text, prefixes, debug output, and help text
- change the visible plugin/chat identity toward XMas Tree for clearer user-facing output
- make the Christmas Crystal display name non-italic

- fix resource-back so destroying a tree returns only the materials actually spent on that tree
- fix the old refund dupe issue where the plugin could return more than the player had used
- improve refund delivery with fallback order:
  chest -> barrel -> player inventory -> floor drops

- reduce the loud grow/ingredient sound behavior
- make first-hit and repeat-hit grow sound volumes configurable and reloadable
- support silent/quiet/loud tuning through config without server restarts

- modernize material and item handling for current Paper names
- use safer material matching/validation to avoid legacy enum failures
- improve displayed item names so materials such as Redstone Dust render properly in requirement output
- add configurable per-stage particle effects using modern Paper particle names

- harden config and item parsing:
  restrict present texture URLs to textures.minecraft.net
  cap Base64 gift payload handling
  skip invalid or legacy material names safely

- update config comments and improve documentation for installation, building, commands, permissions, placeholders, support, and credits
- point support to the GitHub issues page
- refresh .gitignore for local dev/test folders and obvious OS/build junk

i consider this a tested and worth public beta that can be used to figure out any bugs, report them on github as an issue. december is not around the corner, so we have a summer to find issues. Enjoy.

Author: mrfloris

README.md

@@ -6,16 +6,15 @@ This fork keeps the old X-Mas event data usable for winter 2026 while moving the
 
 ![X-Mas tree preview](http://puu.sh/dKlK1/85c3dad454.jpg)
 
-## Current targets
+## Current target
 
-The Gradle build creates the legacy reference jar and the current Paper 26.1.2 target jar in `build/libs`:
+The Gradle build creates the current Paper 26.1.2 target jar in `build/libs`:
 
 | Jar | Purpose |
 | --- | --- |
-| `1MB-XMas-2026-v2.0.0-004-v21-1.21.8.jar` | Legacy reference jar copied from the deployed 2025 server jar. |
-| `1MB-XMas-2026-v2.0.1-011-v25-26.1.2.jar` | Modern Paper 26.1.2 build, Java 25 bytecode. |
+| `1MB-XMas-2026-v2.0.1-021-v25-26.1.2.jar` | Modern Paper 26.1.2 build, Java 25 bytecode. |
 
-The checked-in source targets Paper 26.1.2. The legacy jar is preserved so the deployed working 2025 behavior can be compared or rolled back during testing.
+The checked-in source targets Paper 26.1.2 only.
 
 ## Features
 
@@ -28,7 +27,7 @@ The checked-in source targets Paper 26.1.2. The legacy jar is preserved so the d
 - Existing `plugins/X-Mas/trees.yml` data remains the event data source.
 - Optional resource refunds when a tree is destroyed or cleaned up after the event.
 - Configurable per-stage particles using Paper 26.1.2 particle names.
-- `/xmastree debug` pages for status, commands, permissions, placeholders, and global boolean toggles.
+- `/xmastree debug` sections for `status`, `commands`, `permissions`, `placeholders`, and `config`, plus live global boolean toggles.
 - Primary `/xmastree` command with an optional legacy `/xmas` alias.
 - Optional PlaceholderAPI placeholders for CMI holograms, ajLeaderboards, scoreboards, and menus.
 - Legacy `trees.yml` world-name alias support for renamed destination worlds.
@@ -44,7 +43,7 @@ The checked-in source targets Paper 26.1.2. The legacy jar is preserved so the d
 
 For the 2026 target, use the modern Paper 26.1.2 jar:
 
-- Paper 26.1.2: `1MB-XMas-2026-v2.0.1-011-v25-26.1.2.jar`
+- Paper 26.1.2: `1MB-XMas-2026-v2.0.1-021-v25-26.1.2.jar`
 
 ## Building
 
@@ -54,9 +53,8 @@ Requirements:
 - Gradle
 - The current local dev/test setup in this repo uses `servers/Server-Two-Paper-26.1.2` for Paper API jars and local smoke testing
 - The current local dev/test setup in this repo uses `servers/Server-Two-Paper-26.1.2/plugins/PlaceholderAPI-2.12.3-DEV-265.jar` for the optional PlaceholderAPI compile-time classpath
-- The deployed legacy jar in `servers/Server-One-Paper-1.21.11/plugins` is only needed if you want the `legacyJar` copy task
 
-Build the current Paper 26.1.2 jar and the legacy reference jar:
+Build the current Paper 26.1.2 jar:
 
 ```bash
 gradle clean buildAllJars
@@ -74,12 +72,6 @@ The `paper2612Jar` task is kept as an alias:
 gradle paper2612Jar
 ```
 
-Copy the deployed legacy jar into the requested legacy filename:
-
-```bash
-gradle legacyJar
-```
-
 End users do not need the `servers/` folder. The build output jars are written to `build/libs/`, and those are the files you install on a Paper server.
 
 In this workspace, the current Gradle setup compiles against the Paper 26.1.2 API jars found in `servers/Server-Two-Paper-26.1.2`. If that folder is missing or has not been started far enough for Paper to download its libraries, Gradle will not have the local Paper API classpath it currently expects.
@@ -98,10 +90,44 @@ If `core.commands.legacy-command-enabled` is `true`, the legacy `/xmas` alias is
 | `/xmastree gifts` | Spawns a small batch of presents under every loaded Christmas tree. |
 | `/xmastree addhand` | Adds the item in your main hand to the gift list and saves it to `config.yml`. |
 | `/xmastree reload` | Reloads config, locale, present heads, gifts, luck settings, command alias settings, and tree level requirements. |
-| `/xmastree debug [page]` | Shows paginated status, commands, permissions, placeholders, and toggleable global config keys. |
+| `/xmastree debug` | Opens the `status` debug section by default. |
+| `/xmastree debug [section\|page]` | Shows debug output for `status`, `commands`, `permissions`, `placeholders`, or `config`. Numeric pages `1-5` still work as a legacy shortcut. |
 | `/xmastree debug toggle <key> true\|false` | Toggles supported global boolean config keys and reloads the plugin config. |
 | `/xmastree end` | Ends the event and sets `core.plugin-enabled` to `false`. |
 
+### Debug sections
+
+The preferred debug syntax is category-based:
+
+| Section | Example | Purpose |
+| --- | --- | --- |
+| `status` | `/xmastree debug status` | Event state, end date, auto-end, refund state, particles, loaded tree count, and owner count. |
+| `commands` | `/xmastree debug commands` | Command list, debug syntax, and legacy alias state. |
+| `permissions` | `/xmastree debug permissions` | All registered `onembxmastree.*` permissions and what they allow. |
+| `placeholders` | `/xmastree debug placeholders` | All built-in PlaceholderAPI placeholders plus their descriptions. |
+| `config` | `/xmastree debug config` | The current values of the toggleable global config keys. |
+
+Numeric compatibility remains available for existing habits and old screenshots:
+
+| Page | Section |
+| --- | --- |
+| `1` | `status` |
+| `2` | `commands` |
+| `3` | `permissions` |
+| `4` | `placeholders` |
+| `5` | `config` |
+
+### Debug toggle keys
+
+`/xmastree debug toggle <key> true|false` currently supports:
+
+- `core.commands.legacy-command-enabled`
+- `core.plugin-enabled`
+- `core.holiday-ends.enabled`
+- `core.holiday-ends.resource-back`
+- `core.particles-enabled`
+- `xmas.luck.enabled`
+
 ## Permissions
 
 | Permission | Default | Description |
@@ -113,7 +139,7 @@ If `core.commands.legacy-command-enabled` is `true`, the legacy `/xmas` alias is
 | `onembxmastree.command.gifts` | `op` | Allows `/xmastree gifts`. |
 | `onembxmastree.command.addhand` | `op` | Allows `/xmastree addhand`. |
 | `onembxmastree.command.reload` | `op` | Allows `/xmastree reload`. |
-| `onembxmastree.command.debug` | `op` | Allows `/xmastree debug [page]`. |
+| `onembxmastree.command.debug` | `op` | Allows `/xmastree debug [section\|page]`. |
 | `onembxmastree.command.debug.toggle` | `op` | Allows `/xmastree debug toggle <key> true\|false`. |
 | `onembxmastree.command.end` | `op` | Allows `/xmastree end`. |
 | `onembxmastree.tree.override` | `op` | Allows managing other players' trees. |
@@ -211,7 +237,7 @@ The dotted key after `onembxmastree_` is supported to keep the placeholders read
 | `%onembxmastree_trees.total%` | `14` | Total loaded X-Mas trees. |
 | `%onembxmastree_trees.owners%` | `6` | Number of unique loaded tree owners. |
 | `%onembxmastree_player.trees%` | `2` | Number of loaded trees owned by the placeholder player. |
-| `%onembxmastree_version%` | `2.0.1-011` | Loaded plugin version. |
+| `%onembxmastree_version%` | `2.0.1-021` | Loaded plugin version. |
 
 CMI hologram example:
 

build.gradle

@@ -3,14 +3,10 @@ plugins {
 }
 
 group = 'com.onemb.xmas'
-version = '2.0.1-011'
+version = '2.0.1-021'
+def paper2612ArchiveName = '1MB-XMas-2026-v2.0.1-021-v25-26.1.2.jar'
 
-def legacyArchiveName = '1MB-XMas-2026-v2.0.0-004-v21-1.21.8.jar'
-def paper2612ArchiveName = '1MB-XMas-2026-v2.0.1-011-v25-26.1.2.jar'
-
-def serverOne = layout.projectDirectory.dir('servers/Server-One-Paper-1.21.11')
 def serverTwo = layout.projectDirectory.dir('servers/Server-Two-Paper-26.1.2')
-def legacyServerJar = serverOne.file('plugins/1MB-X-Mas_2025-1.21.8.jar')
 def placeholderApiJar = serverTwo.file('plugins/PlaceholderAPI-2.12.3-DEV-265.jar')
 
 def paper2612Api = serverTwo.file('libraries/io/papermc/paper/paper-api/26.1.2.build.18-alpha/paper-api-26.1.2.build.18-alpha.jar')
@@ -50,20 +46,12 @@ tasks.register('paper2612Jar') {
     dependsOn tasks.named('jar')
 }
 
-tasks.register('legacyJar', Copy) {
-    description = 'Copies the deployed legacy jar into the requested 2026 legacy filename.'
-    group = 'build'
-    from(legacyServerJar)
-    into(layout.buildDirectory.dir('libs'))
-    rename { legacyArchiveName }
-}
-
 tasks.register('buildAllJars') {
-    description = 'Builds the legacy reference jar plus the modern Paper 26.1.2 target jar.'
+    description = 'Builds the current Paper 26.1.2 target jar.'
     group = 'build'
-    dependsOn tasks.named('legacyJar'), tasks.named('jar')
+    dependsOn tasks.named('jar')
 }
 
 tasks.named('assemble') {
-    dependsOn tasks.named('legacyJar'), tasks.named('paper2612Jar')
+    dependsOn tasks.named('paper2612Jar')
 }