Quest system redesign: Achievements, Community, Risk & Secret

.github/workflows/build.yml

@@ -2,7 +2,9 @@ name: Build plugin
 on:
   workflow_dispatch:
   push:
-    branches: [ main, master ]
+    branches: [ main, master, integrated-release, 'feature/**' ]
+  pull_request:
+    branches: [ main, master, integrated-release ]
 permissions:
   contents: read
   actions: read
@@ -18,8 +20,25 @@ jobs:
       - uses: gradle/actions/setup-gradle@v4
       - name: Build with Gradle
         run: gradle clean build
+      - name: Package source archive
+        run: git archive --format=zip --output=build/XZHEconomySystem-source.zip HEAD
       - name: Upload plugin JAR
         uses: actions/upload-artifact@v4
         with:
           name: XZHEconomySystem-1.0.0
           path: build/libs/XZHEconomySystem-1.0.0.jar
+      - name: Package coin resource pack
+        run: |
+          mkdir -p build
+          cd resource-pack
+          zip -r ../build/XZH-Coin-Resource-Pack.zip .
+      - name: Upload coin resource pack
+        uses: actions/upload-artifact@v4
+        with:
+          name: XZH-Coin-Resource-Pack
+          path: build/XZH-Coin-Resource-Pack.zip
+      - name: Upload source archive
+        uses: actions/upload-artifact@v4
+        with:
+          name: XZHEconomySystem-source
+          path: build/XZHEconomySystem-source.zip

BUILD_STATUS.md

@@ -0,0 +1,24 @@
+# XZHEconomySystem — Fix Draft Status
+
+**Status: source draft only. Not a release JAR.**
+
+The source draft contains the current reported fixes and additions. It has not been compiled against the Purpur/Paper 26.3 API in this environment because only Java 21 is installed, the project requires Java 25, Gradle is not installed, and downloading build tools is unavailable here.
+
+## Included in this draft
+- Admin utility commands restricted by `xzh.admin`: `/gmc`, `/gms`, `/gma`, `/gmsp`, `/gamemode`, `/day`, `/night`, `/heal`, `/feed`, `/fly`, `/weather`.
+- In-game world clock in the action bar, configurable under `hud.clock`.
+- Bed-based `/home`: place a bed to set it, and breaking either half clears that bed home; named homes remain available by name.
+- Full potion-type listings for regular, splash, and lingering potions, with separate variant pricing and variant-aware selling.
+- XP bottle shop entry retained.
+- Revised quest pack objectives and restricted global stock for several rare items.
+- Netherite Upgrade template is buyable; all smithing templates and selected exploit-prone rare items are blocked from selling.
+- `/pay` spends pocket coins first and bank funds second; existing bank and loan code was left intact.
+- Custom XZH coin resource-pack assets and CustomModelData assignment.
+- Very cheap default sell value for unfeatured items; values under 1 coin total cannot be sold.
+
+## Before release
+1. Build using JDK 25 and Gradle (`gradle clean build`).
+2. Fix any compile errors against the exact Purpur 26.3 API.
+3. Install the JAR on a disposable Purpur 26.3 server and complete `docs/TEST_CHECKLIST.md`.
+4. Validate `resource-pack/` on a matching client version; `pack_format` is marked as a candidate until checked in-game.
+5. Only then publish a release JAR.

README.md

@@ -1,22 +1,67 @@
-# XZHEconomySystem 1.0.0
+# XZHEconomySystem 1.0.0 — integrated development branch
 
-A first deployable baseline for Paper/Purpur 26.3. This is **not yet the complete planned EssentialsX/economy/shop/quest replacement**; it is a small real-API build intended to verify loading and basic economy behavior first.
+A Java plugin project targeting Purpur 26.3 (Java 25). This branch combines the economy, shop, loans, quests, death recovery, HUD, admin tools, and selected Essentials-style utilities. It is still under development and must be tested on a separate Purpur server before production use.
+
+## Current features
+
+- Physical, server-tagged XZH pocket coins in 1/10/100/1000 denominations that naturally drop on death, separate persistent bank balances, `/balance`, `/pay`, admin `/eco`, and an optional Vault bridge.
+- Recipient-confirmed `/sendmoney <player> <amount>` and `/askmoney <player> <amount>` requests with accept/decline GUI and 60-second expiry.
+- Configurable global announcements for expensive/rare shop purchases, progression unlocks, new loans, and full loan repayments.
+- Shop GUI with confirmation dialogs, quantities, curated products, global stock, daily restock, and cheap sell-hand support for unfeatured items.
+- Enchantment-book GUI with confirmation, 24-hour per-player cooldown per enchantment, and daily global limits for selected useful/rare books.
+- Elytra purchase lock until the player has visited the End.
+- `/bank` opens the separate `XZH BANK` GUI with persistent bank balances, 09:00–20:00 Minecraft-time deposit/withdrawal hours, and the Loans menu. Shop purchases and loan repayments spend pocket funds first, then bank funds; bank-funded purchases and repayments remain available after closing time.
+- Loan GUI inside the bank, configured terms/rates, 12-hour grace period, automatic repayment from combined pocket/bank funds when sufficient, and shop purchase restriction once overdue.
+- Quest packs with shared daily stock, active quest boss bar/progress, 30-minute actionbar reminders, and a daily global community ore event.
+- Paid death inventory recovery: 30-minute window, two recoveries per day, configured recovery fee, and death money penalty.
+- HUD sidebar for pocket/bank balance, amount owed, and due/overdue time; an in-game clock appears in the action bar. The clock can be disabled or reformatted in `hud.clock`.
+- Admin GUI `/xzhadmin` for balance updates, shop stock management, transaction history, and diagnostics.
+- Essentials-style commands: spawn, bed home, named homes, warps, TPA, back, private messages, ignore, AFK, near, list, top, RTP, configurable starter kit, and help. Admin utilities include `/gmc`, `/gms`, `/gma`, `/gmsp`, `/gamemode`, `/day`, `/night`, `/heal`, `/feed`, `/fly`, and `/weather` (permission `xzh.admin`).
+- Librarian enchanted-book trade blocking.
+- YAML persistence for balances, loans, quests, shop stock, book cooldowns/stock, death recovery, and locations; balance changes are appended to a transaction log.
 
 ## Commands
-- `/xzh` — help
-- `/balance` or `/bal` — own balance
-- `/balance <online-player>` — another online player's balance
-- `/pay <online-player> <amount>` — transfer coins
-- `/eco set <online-player> <amount>` and `/eco add <online-player> <amount>` — admin economy commands (`xzh.admin`, default OP)
-
-Balances persist in `plugins/XZHEconomySystem/balances.yml`. The default starting balance is 100 coins and can be changed in `config.yml`.
-
-## Build
-Requires JDK 25 and an internet connection. Run `gradle build` or use the included GitHub Actions workflow. The Paper API is a compile-only dependency; it is supplied by the server at runtime.
-
-## Falix install
-1. Make sure the server software is Paper or Purpur 26.3 and its Java runtime is Java 25.
-2. Upload `XZHEconomySystem-1.0.0.jar` to `plugins/`.
-3. Fully stop and start the server.
-4. Check `/plugins`, then run `/xzh` and `/balance`.
-5. If it fails, send the startup error from the console.
+
+Player:
+- `/xzh`
+- `/balance`, `/bal`, `/money`
+- `/pay <player> <amount>`
+- `/sendmoney <player> <amount>`, `/askmoney <player> <amount>` (recipient confirmation required)
+- `/shop`, `/bank`, `/books`
+- `/loan` (opens the bank), `/loan repay`
+- `/quests`
+- `/deathinventory`
+- `/spawn`, `/sethome [name]`, `/home [name]`, `/delhome [name]`
+- `/warp <name>`, `/tpa <player>`, `/tpaccept`, `/tpdeny`, `/back`
+- `/msg <player> <message>`, `/reply <message>`, `/ignore <player>`
+- `/afk`, `/near`, `/list`, `/top`, `/rtp`, `/kit starter`, `/help
+
+Admin (permission `xzh.admin`, default OP):
+- `/eco <set|add> <online-player> <amount>`
+- `/xzhadmin`
+- `/shopadmin restock`
+- `/shopadmin stock <MATERIAL> <amount>`
+- `/setspawn`, `/setwarp <name>`, `/delwarp <name>`
+
+## Pocket coin texture
+
+The companion `XZHEconomySystem-coin-resource-pack.zip` adds custom denomination art for physical XZH coins. Install it client-side; the plugin sets CustomModelData on official coin items. The included pack is a candidate for Minecraft 26.3 and still needs a live-client version check.
+
+## Build and install
+
+Requires JDK 25. Run `gradle clean build` or use the GitHub Actions workflow. Successful workflow runs publish a JAR artifact and a source ZIP.
+
+See [configuration documentation](docs/CONFIGURATION.md), the [manual test checklist](docs/TEST_CHECKLIST.md), and the [Falix install guide](docs/FALIX_INSTALL.md).
+
+## Release validation still required
+
+The previously integrated base version has a GitHub Actions build workflow, but this local fix draft has not yet been compiled against the Purpur 26.3 API. See `BUILD_STATUS.md` for the exact limitation. A green build confirms compilation and packaging only; it does **not** prove runtime behavior on Purpur 26.3.
+
+Before production use, run [the manual test checklist](docs/TEST_CHECKLIST.md) on a disposable Purpur 26.3 server, especially:
+- GUI buy/sell confirmation, inventory-full handling, global stock and daily resets.
+- Loan due time, 12-hour grace countdown, overdue purchase restrictions, and auto-repayment with both sufficient and insufficient funds.
+- Death inventory and XP recovery through deaths, full inventories, expiry, and server restarts.
+- Vault compatibility with the economy plugins you intend to run.
+- Librarian trade restrictions, End-visit Elytra unlock, quest progress/event claims, and all utility commands.
+
+No live Purpur server is attached to this workflow, so these runtime checks must be performed on your test server before calling this a production release.

build.gradle.kts

@@ -7,10 +7,14 @@ version = "1.0.0"
 
 repositories {
     maven("https://repo.papermc.io/repository/maven-public/")
+    maven("https://jitpack.io")
 }
 
 dependencies {
     compileOnly("io.papermc.paper:paper-api:26.3.build.195-stable")
+    compileOnly("com.github.MilkBowl:VaultAPI:1.7") {
+        exclude(group = "org.bukkit", module = "bukkit")
+    }
 }
 
 java {

docs/CONFIGURATION.md

@@ -0,0 +1,209 @@
+# XZHEconomySystem configuration
+
+This document describes the settings currently implemented by the development branch for Purpur 26.3.
+
+## Economy
+
+The plugin registers as a Vault economy provider when Vault is installed. If another economy plugin is installed too, make sure XZHEconomySystem is intended to be the primary provider.
+
+```yaml
+currency-name: coins
+currency-name-singular: coin
+starting-balance: 100.0
+minimum-pay: 1.0
+maximum-pay: 1000000.0
+```
+
+- `currency-name`: label used in balance messages.
+- `starting-balance`: initial balance for a UUID that has never had a saved balance.
+- `minimum-pay` / `maximum-pay`: accepted range for `/pay`.
+
+## Global announcements
+
+```yaml
+announcements:
+  shop:
+    enabled: true
+    minimum-purchase-total: 1000
+    rare-items:
+      - ELYTRA
+      - NETHERITE_INGOT
+      - ENCHANTED_GOLDEN_APPLE
+      - TOTEM_OF_UNDYING
+      - TRIDENT
+      - MACE
+      - WITHER_SKELETON_SKULL
+      - SILENCE_ARMOR_TRIM_SMITHING_TEMPLATE
+    progression-items:
+      - ELYTRA
+  loan:
+    borrowing: true
+    full-repayment: true
+```
+
+Shop announcements are limited to purchases at or above the configured total, listed rare items, or progression items. Loan announcements are sent when a loan is granted and when the full balance is repaid, including automatic repayment.
+
+## Bank
+
+The separate `/bank` GUI is titled `XZH BANK`. Bank balances are stored in `bank-balances.yml`; pocket money is represented by tagged physical XZH coin items, with `balances.yml` holding migration/offline snapshots and `wallets.yml` tracking wallet initialization. Deposits and withdrawals are available only between the configured Minecraft-time hours; the bank menu and loan details remain accessible outside those hours. Shop purchases and loan repayments can spend pocket funds first and then bank funds at any time.
+
+```yaml
+bank:
+  clock-world: world
+  open-hour: 9
+  close-hour: 20
+```
+
+- `clock-world`: world whose Minecraft day/night clock determines bank opening hours; if missing, the first loaded world is used.
+- `open-hour` / `close-hour`: 24-hour Minecraft time. The default is 09:00–20:00.
+- Pocket coins use server-tagged denominations of 1, 10, 100, and 1000 coins. They cannot be crafted or placed as blocks and naturally drop with inventory on death in worlds where items drop.
+- The default pocket carrying limit is 1,000,000 coins; overflow is secured in the bank. Withdrawals are limited by available pocket capacity.
+- Bank balance is saved separately. Deposit/withdraw buttons are disabled by server-side checks while the bank is closed; direct inventory clicks cannot bypass the hours.
+- The Loans menu is accessed from the bank. `/loan` opens the bank for compatibility, and `/loan repay` remains available as a direct repayment command.
+
+## Pocket wallet
+
+```yaml
+wallet:
+  max-pocket-coins: 1000000
+```
+
+`max-pocket-coins` limits the physical currency carried in inventory. Any excess credited to the pocket is automatically secured in the bank. The server migrates an existing saved balance into physical coins when a player first joins after this feature is installed.
+
+## HUD
+
+```yaml
+hud:
+  scoreboard:
+    enabled: true
+    position: sidebar
+  quest-bossbar:
+    enabled: true
+```
+
+The sidebar shows pocket balance, bank balance, active loan amount owed, and time remaining/overdue state. The active quest boss bar is driven by quest progress.
+
+## Shop global stock
+
+```yaml
+shop:
+  stock-limits:
+    coal: 2000
+    iron_ingot: 1000
+    gold_ingot: 500
+    diamond: 250
+    obsidian: 250
+    bread: 1000
+    cooked_beef: 1000
+    iron_pickaxe: 100
+    diamond_pickaxe: 30
+    elytra: 3
+```
+
+Stock is shared across all players and saved in `shop-stock.yml`. Each configured value is the daily restock cap. Buy/sell prices can be overridden under `shop.prices.<material>.buy` and `shop.prices.<material>.sell`; unfeatured held items use `shop.default-sell-price`. The administrator command `/shopadmin stock <MATERIAL> <amount>` changes current stock; `/shopadmin restock` refills configured shop products immediately.
+
+## Death recovery
+
+```yaml
+death-recovery:
+  overworld-only: true
+  fee-multiplier: 1.5
+  xp-value-per-point: 0.25
+  material-values:
+    elytra: 2500
+    netherite_ingot: 600
+    netherite_scrap: 150
+    diamond: 125
+    diamond_block: 720
+    ancient_debris: 120
+```
+
+- Recovery window: 30 minutes after death.
+- Daily limit: 2 successful recoveries per player.
+- Fee: estimated lost value multiplied by `fee-multiplier`.
+- On death, the money penalty is 10% of estimated lost value, bounded to 10–1000 coins and capped by the player's available balance.
+- Per-material entries override the built-in estimate. Use lowercase material names.
+
+## Quests and global event
+
+```yaml
+quests:
+  pack-stock:
+    beginner: 50
+    miner: 30
+    hunter: 25
+    explorer: 15
+    nether: 10
+    end: 5
+  global-event:
+    goal: 500
+    reward: 100
+    claims-per-day: 25
+```
+
+Quest pack stock resets to these configured values each server-local day. The global event uses a shared ore goal, pays the configured reward, and allows the configured number of successful claims per day. `/xzhadmin` can also change the current pack stock until the next daily reset.
+
+## Gameplay restrictions
+
+```yaml
+restrictions:
+  disable-librarian-enchanted-book-trades: true
+  elytra-requires-end-visit: true
+  buy-only-spawn-eggs: true
+```
+
+- `disable-librarian-enchanted-book-trades`: when enabled, librarian enchanted-book offers are blocked and existing offers are removed when interacted with. Turning it off allows future offers, but recipes removed while the restriction was enabled may not be restored automatically.
+- `elytra-requires-end-visit`: when enabled, players must unlock the vanilla End-visit advancement before buying an Elytra.
+- `buy-only-spawn-eggs`: when enabled, spawn eggs cannot be sold back to the shop. When disabled, eggs default to a 30% sellback unless a material-specific sell price overrides it.
+
+## Enchantment books
+
+The book shop is available through `/books` and the main `/shop` menu. Each player has a configurable cooldown per enchantment, while selected useful/rare books have a shared global daily stock cap.
+
+```yaml
+book-shop:
+  cooldown-hours: 24
+  rare-daily-stock: 3
+  normal-daily-stock: 100
+  prices:
+    mending: 1200
+    wind_burst: 1500
+    swift_sneak: 700
+    soul_speed: 700
+    frost_walker: 700
+```
+
+Price entries are optional overrides; omitted entries use built-in defaults. Selected rare books (including Mending) reset to the rare daily stock limit each day. Administrators can clear an individual player's book cooldowns from `/xzhadmin`.
+
+## Player utilities
+
+```yaml
+utilities:
+  max-homes: 3
+  rtp-radius: 3000
+  rtp-cooldown-seconds: 600
+```
+
+The random teleport search is centered on the configured spawn when available and uses a safe-location check. The cooldown is currently in-memory and resets on a server restart.
+
+## Starter kit
+
+```yaml
+kits:
+  starter:
+    cooldown-hours: 24
+    items:
+      - STONE_PICKAXE:1
+      - BREAD:8
+      - TORCH:16
+```
+
+Item entries use `MATERIAL:AMOUNT`. The kit cooldown is persisted per player in `locations.yml`. The `xzh.kit.starter` permission defaults to true.
+
+## Data files
+
+The plugin maintains separate YAML files for pocket-balance snapshots and wallet migration status (`balances.yml`, `wallets.yml`), bank savings (`bank-balances.yml`), loans, quests, shop stock, book cooldowns, and death recovery. Back up the server and these files before testing a development build.
+
+## Important scope note
+
+These docs describe settings that exist in the current branch. They do not mean every item from the full release specification is complete. The branch still requires additional feature work and in-server testing before it should be treated as a finished production release.