inventory

docs/playable-slices/0.9-First-Quest-and-Bag-Tutorial.md

@@ -0,0 +1,321 @@
+# Ashen Realms – Playable Slice 0.9
+
+## First Quest & Loot-Bag Tutorial
+
+**Status:** Implementation Specification  
+**Depends on:** Slice 0.8.5  
+**Purpose:** Introduce quests, NPC-directed progression, bag capacity and the merchant loop through one small coherent tutorial chain.
+
+---
+
+## 1. Goal
+
+This slice should teach several systems without a conventional tutorial popup sequence.
+
+The player learns naturally that:
+
+- NPCs provide direction
+- monster goods must be carried
+- carrying capacity matters
+- merchants can help
+- reputation affects relationships/offers
+- hunting goods can later be exchanged for progression
+
+The quest should feel like world interaction, not a checklist tutorial.
+
+---
+
+## 2. Quest Concept
+
+Working quest title:
+
+**Trouble Beyond the Gate**
+
+Quest-giver:
+
+**South Gate Warden**
+
+Use an existing named gate NPC if one has already been implemented. Do not create a duplicate NPC merely because this document uses a generic title.
+
+Merchant:
+
+**Borin, Quartermaster** or the existing Graufurt merchant.
+
+---
+
+## 3. Narrative Flow
+
+### Step 1 – Speak with the South Gate Warden
+
+The warden is concerned about increasingly aggressive scavengers and raiders beyond the gate.
+
+Player-facing English example:
+
+> "The road has gone bad. Start small. Bring me five Ashen Pelts from the rats beyond the gate. I want to know what the ash is doing to them."
+
+Objective:
+
+```text
+Collect 5 Ashen Pelts
+```
+
+---
+
+## 4. Capacity Problem
+
+The player currently has no Hide Bag.
+
+Default HIDE capacity is 1.
+
+After collecting the first Ashen Pelt:
+
+```text
+Ashen Pelts 1 / 1
+Hide capacity reached.
+```
+
+The quest remains at `1 / 5`.
+
+The game should now provide a clear next action rather than leaving the player confused.
+
+Suggested quest update:
+
+```text
+You cannot carry enough pelts. Return to the South Gate Warden.
+```
+
+Do not secretly increase capacity for the quest.
+
+---
+
+## 5. Referral to the Merchant
+
+On returning, the warden acknowledges the problem and refers the player to Borin.
+
+Example:
+
+> "Right. You're not equipped for hauling spoils yet. Go see Borin in Graufurt. Tell him I sent you. He'll complain, but he'll give you something useful."
+
+Set a persisted unlock/referral flag, for example:
+
+```text
+referred-by-south-gate-warden
+```
+
+New objective:
+
+```text
+Speak with Borin in Graufurt
+```
+
+---
+
+## 6. Merchant Interaction
+
+Borin normally would not provide the bag at the player's current reputation.
+
+His dialogue should make the relationship system visible.
+
+Example:
+
+> "I don't know you, and I don't hand out gear to every wanderer who walks in here."
+
+Then after recognizing the referral:
+
+> "But the South Gate Warden sent you. Fine. Take this. Bring it back full and make it worth my trouble."
+
+Grant:
+
+**Basic Hide Bag**
+
+```text
+Category: HIDE
+Capacity: 5
+```
+
+The grant should use the quest/referral exception supported by Slice 0.8.5.
+
+---
+
+## 7. Continue the Hunt
+
+The player can now carry five HIDE-category goods.
+
+Objective returns to:
+
+```text
+Collect 5 Ashen Pelts
+```
+
+Important:
+
+- an already-owned first pelt still counts
+- the player should need four more, not five more
+- the bag capacity view changes immediately to `1 / 5`
+
+---
+
+## 8. Quest Turn-In
+
+The player returns to the South Gate Warden with five Ashen Pelts.
+
+The quest consumes the required five pelts.
+
+The warden explains the normal long-term loop:
+
+> "Good. That's enough for me. From now on, take hides and trophies to Borin. He'll pay for useful spoils, and word gets around when you keep the roads clear."
+
+This line connects:
+
+- monster loot
+- merchant exchange
+- Silver
+- regional reputation
+- World Renown
+
+without needing a separate tutorial screen.
+
+---
+
+## 9. Quest Rewards
+
+The main reward of this quest is the **Basic Hide Bag** and system knowledge.
+
+Optional one-time rewards may include:
+
+- small regional reputation increase
+- small World Renown milestone increase
+- quest completion flag
+
+Avoid a large Silver reward that undermines the merchant trade loop.
+
+No XP reward.
+
+---
+
+## 10. Minimal Quest System Requirements
+
+The system must support at least:
+
+- quest definition
+- quest acceptance
+- ordered objectives
+- item collection progress
+- NPC interaction objective
+- persisted completion
+- quest flags/unlock flags
+- item consumption on turn-in
+- one-time rewards
+
+Do not build a full branching narrative engine.
+
+A simple step-based quest state machine is sufficient.
+
+---
+
+## 11. Quest State Safety
+
+The flow must not softlock when:
+
+- player already owns one or more Ashen Pelts before accepting
+- player sells/trades pelts while quest is active
+- player disconnects during a quest step
+- bag was already obtained through development data
+- player tries to receive the referral bag twice
+
+Define deterministic behavior.
+
+Recommended:
+
+- objectives derive progress from current owned quantity where appropriate
+- quest item consumption validates quantity at turn-in
+- bag grant is idempotent
+- referral flag persists
+
+---
+
+## 12. UI Requirements
+
+At minimum:
+
+### NPC / Local View
+
+- quest available marker
+- quest in progress marker
+- quest turn-in marker
+- Talk interaction
+
+### Quest UI
+
+Show:
+
+- title
+- short description
+- current objective
+- progress
+
+Example:
+
+```text
+Trouble Beyond the Gate
+Collect Ashen Pelts 1 / 5
+
+You cannot carry enough pelts. Return to the South Gate Warden.
+```
+
+### Bag UI
+
+When the bag is granted:
+
+```text
+New Loot Bag
+Basic Hide Bag
+Hide Capacity: 5
+```
+
+---
+
+## 13. Tests
+
+- quest can be accepted only once in active state
+- first pelt updates objective to 1/5
+- no bag blocks carrying second HIDE item
+- return step activates correctly
+- referral flag is set
+- merchant grants Basic Hide Bag once
+- capacity becomes 5
+- previously owned pelt remains counted
+- five pelts allow turn-in
+- turn-in consumes five pelts
+- quest completes and cannot reward bag repeatedly
+
+---
+
+## 14. Acceptance Criteria
+
+- [ ] One complete NPC quest chain is playable.
+- [ ] The quest intentionally exposes the default 1-item carrying limit.
+- [ ] The player is directed back instead of softlocked.
+- [ ] A persisted merchant referral is created.
+- [ ] Merchant grants Basic Hide Bag because of the referral.
+- [ ] Hide capacity becomes 5.
+- [ ] Player can collect five Ashen Pelts.
+- [ ] Turn-in consumes the pelts and completes the quest.
+- [ ] NPC explains that future goods should be traded to the merchant.
+- [ ] Quest grants no XP.
+- [ ] All dialogue/UI text is English.
+
+---
+
+## 15. Out of Scope
+
+Do not implement:
+
+- branching quest choices
+- voice acting
+- cinematic dialogue
+- daily quests
+- repeatable bounty framework
+- quest sharing
+- party quest progress
+- large quest journal taxonomy