From 63e9185bf8dfd885a66b5721aad3804d850cef03 Mon Sep 17 00:00:00 2001 From: Matt Date: Sat, 6 Jun 2026 20:51:14 +0000 Subject: [PATCH] docs: add quest tracking + cancel UX to economy design Three-layer visibility plan: V1 (Phase 3): /quests, /quests info, /quests cancel commands. Mobile-friendly via the bridge, no extra mods. V2 (Phase 3.5): Quest Log book item with dynamic pages. V3 (later): optional sidebar HUD via vanilla scoreboards. 3-slot active-quest cap so cancellation is a real choice: - Prevents accept-all-then-cancel-easy-ones RNG shopping - Keeps state files small - READY frees the slot so turn-in backlogs are workable State storage schema documented (active + completed/cooldown). Phase 3.5 added to the roadmap for the book item. Co-Authored-By: Claude Opus 4.7 --- docs/economy-system.md | 55 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 53 insertions(+), 2 deletions(-) diff --git a/docs/economy-system.md b/docs/economy-system.md index c46d3b5..1a62898 100644 --- a/docs/economy-system.md +++ b/docs/economy-system.md @@ -120,12 +120,62 @@ The same accept → complete → return pattern works for every guild: | **Library** | "Recover this lost tome" | find the book in a structure | NPC pays + grants reputation | | **Foundry** | "Craft 10 Andesite Casings" | craft them | NPC pays commission | +### Player-facing tracking & cancellation + +A quest engine that players can't inspect is worthless. The design ships with three layers of visibility: + +#### V1 — command-driven (Phase 3, with the engine) + +| Command | Effect | +|---|---| +| `/quests` | Lists all of your ACTIVE and READY quests with progress, source guild, and reward | +| `/quests info ` | Detail view for one quest — description, objective, progress, reward | +| `/quests cancel ` | Drops an active quest, freeing your slot. The quest goes on cooldown as if completed (prevents accept-cancel-accept RNG farming) | + +Cheap to ship. Works on mobile via the Telegram bridge. Doesn't require any extra mods. + +#### V2 — Quest Log book item (Phase 3.5) + +Every new player joins with a **Quest Log** book in their inventory (KubeJS `PlayerEvents.loggedIn` grants it once). Right-click to open. Dynamic Patchouli-style pages list active/ready quests, with a "Cancel" button per quest. Same backend as the `/quests` commands — just a nicer surface. + +#### V3 — Sidebar HUD (later) + +Optional scoreboard sidebar showing 2-3 most recent quests + progress, always-on. Implemented via vanilla scoreboard objectives driven by KubeJS. Players can toggle on/off via `/quests sidebar`. + +### Quest slot limit + +Players have a **maximum of 3 active quests at a time.** This is the friction that makes cancel meaningful: + +- Forces players to pick which quests they actually want — no "accept all 5, see what's easiest, cancel the rest" RNG-shopping. +- Keeps the state files small. +- Makes ready-to-turn-in queues meaningful (you can hold 3 unrewarded quests in your back pocket). + +A quest moving to READY frees the slot for accepting a new one even before turn-in. + ### KubeJS implementation sketch -- **State storage:** per-player JSON in `world/data/bns_quests/.json`, written via KubeJS persistent-data hooks. +- **State storage:** per-player JSON in `world/data/bns_quests/.json`, written via KubeJS persistent-data hooks. Schema: + ```json + { + "active": [ + { + "id": "advg_plunderer_10", + "acceptedAt": 1717684800, + "progress": 7, + "target": 10, + "rewardSpurs": 50, + "source": "adventurers_guild" + } + ], + "completed": { + "advg_plunderer_10": { "cooldownUntil": 1717771200, "completions": 3 } + } + } + ``` - **Event tracking:** standard KubeJS event handlers (`EntityEvents.death`, `ItemEvents.pickedUp`, `BlockEvents.broken`) read the player's active quests and increment. - **Dialog branching:** Easy NPC dialog with conditions that call KubeJS to check quest state and route the dialog appropriately. - **Reward delivery:** call Numismatics' wallet API to deposit spurs. +- **Commands:** registered via `ServerEvents.commandRegistry` in KubeJS, scoped to the player who runs them. --- @@ -217,7 +267,8 @@ Each phase is independently shippable. Earlier phases unlock value without depen | **0** | Spawn skeleton built — 7 guild buildings placed (rough). | Locations have to exist before NPCs can stand in them. | | **1** | **Merchant's Bazaar V1:** Numismatics sell shop (fixed prices, no DR yet) for diamonds & netherite. | Cheapest to ship, immediate economy unlock. | | **2** | **Civic Office V1:** Plot claim cost via KubeJS `/ftbchunks claim` override. | Real money sink. Tests FTB Chunks integration depth. | -| **3** | **Adventurer's Guild V1:** Bounty board engine. 5 daily quests, accept→complete→return flow. | The biggest gameplay feature. Validates the universal quest pattern. | +| **3** | **Adventurer's Guild V1:** Bounty board engine. 5 daily quests, accept→complete→return flow, `/quests` commands, 3-slot cap. | The biggest gameplay feature. Validates the universal quest pattern. | +| **3.5** | Quest Log book item (V2 of tracking surface). | Nicer UX surface on top of the same engine — non-blocking. | | **4** | **Villager rebalance:** strip vanilla, ship the spur-priced trade table. | Closes the exploit. Big JSON pass. | | **5** | **Library / Academy:** FTB Quests anchor + first chapter of progression quests. | Long-form content begins. | | **6** | **Civic Office V2:** FTB Ranks integration + tier upgrades. | Endgame money sink. |